加入直播会议:美国东部时间周四上午 11 点,Storybook 9 发布及问答
文档
Storybook 文档

视口

视口功能允许你调整故事渲染所在的 iframe 的尺寸。它使开发响应式 UI 变得容易。

配置

开箱即用,视口功能为你提供了一组标准的视口供你使用。如果你想更改默认的视口集合,可以在 .storybook/preview.js|ts 中使用 viewport 参数 配置自己的视口。

你可以使用 options 属性 定义可用的视口,并使用 initialGlobals 属性 设置初始视口

.storybook/preview.ts
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import { Preview } from '@storybook/your-framework';
 
import { INITIAL_VIEWPORTS } from 'storybook/viewport';
 
const preview: Preview = {
  parameters: {
    viewport: {
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
};
 
export default preview;

使用详细的设备集合

默认情况下,视口功能会使用一组最小的视口,这使得你可以在常见的响应式场景中测试你的 UI。这些也通过 MINIMAL_VIEWPORTS 导出 提供,并包括以下设备

描述尺寸
(w×h,px)
mobile1小型手机320 × 568
mobile2大型手机414 × 896
tablet平板电脑834 × 1112

如果你需要更详细的设备集合,可以使用 INITIAL_VIEWPORTS 导出,它包括以下设备

描述尺寸
(w×h,px)
iphone5iPhone 5320 × 568
iphone6iPhone 6375 × 667
iphone6piPhone 6 Plus414 × 736
iphone8piPhone 8 Plus414 × 736
iphonexiPhone X375 × 812
iphonexriPhone XR414 × 896
iphonexsmaxiPhone XS Max414 × 896
iphonese2iPhone SE (第二代)375 × 667
iphone12miniiPhone 12 mini375 × 812
iphone12iPhone 12390 × 844
iphone12promaxiPhone 12 Pro Max428 × 926
iphoneSE3iPhone SE 第三代375 × 667
iphone13iPhone 13390 × 844
iphone13proiPhone 13 Pro390 × 844
iphone13promaxiPhone 13 Pro Max428 × 926
iphone14iPhone 14390 × 844
iphone14proiPhone 14 Pro393 × 852
iphone14promaxiPhone 14 Pro Max430 × 932
galaxys5Galaxy S5360 × 640
galaxys9Galaxy S9360 × 740
nexus5xNexus 5X412 × 668
nexus6pNexus 6P412 × 732
pixelPixel540 × 960
pixelxlPixel XL720 × 1280
mobile1小型手机
(也包含在 MINIMAL_VIEWPORTS 中)
320 × 568
mobile2大型手机
(也包含在 MINIMAL_VIEWPORTS 中)
414 × 896
ipadiPad768 × 1024
ipad10piPad Pro 10.5 英寸834 × 112
ipad11piPad Pro 11 英寸834 × 1194
ipad12piPad Pro 12.9 英寸1024 × 1366
tablet平板电脑
(也包含在 MINIMAL_VIEWPORTS 中)
834 × 1112

要使用详细的设备集合,可以在配置中调整 options 属性,使其包含 INITIAL_VIEWPORTS 导出

.storybook/preview.ts
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import { Preview } from '@storybook/your-framework';
 
import { INITIAL_VIEWPORTS } from 'storybook/viewport';
 
const preview: Preview = {
  parameters: {
    viewport: {
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
};
 
export default preview;

添加新设备

如果预定义的视口不满足你的需求,你可以将新设备添加到视口列表中。例如,让我们将两个 Kindle 设备添加到默认的最小视口集合中

.storybook/preview.ts
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import { Preview } from '@storybook/your-framework';
 
import { MINIMAL_VIEWPORTS } from 'storybook/viewport';
 
const kindleViewports = {
  kindleFire2: {
    name: 'Kindle Fire 2',
    styles: {
      width: '600px',
      height: '963px',
    },
  },
  kindleFireHD: {
    name: 'Kindle Fire HD',
    styles: {
      width: '533px',
      height: '801px',
    },
  },
};
 
const preview: Preview = {
  parameters: {
    viewport: {
      options: {
        ...MINIMAL_VIEWPORTS,
        ...kindleViewports,
      },
    },
  },
};
 
export default preview;

按组件或故事配置

在某些情况下,全局使用特定的视觉视口可能不切实际,你需要将其调整到单个故事或组件的一组故事中。

参数 可以应用于项目、组件和故事级别,这使得你可以在需要的地方指定配置。例如,你可以像这样为一个组件的所有故事设置可用的视口

MyComponent.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { INITIAL_VIEWPORTS } from 'storybook/viewport';
 
import { MyComponent } from './MyComponent';
 
const meta = {
  component: MyComponent,
  parameters: {
    viewport: {
      //👇 Set available viewports for every story in the file
      options: INITIAL_VIEWPORTS,
    },
  },
} satisfies Meta<typeof MyComponent>;
 
export default meta;

为故事定义视口

视口模块使你能够通过从工具栏中预定义的视口列表中选择来更改应用于故事的视口。如果需要,你可以使用 globals 选项 将故事设置为默认使用特定视口

Button.stories.ts|tsx
// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
  globals: {
    // 👇 Set viewport for all component stories
    viewport: { value: 'tablet', isRotated: false },
  },
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const OnPhone: Story = {
  globals: {
    // 👇 Override viewport for this story
    viewport: { value: 'mobile1', isRotated: false },
  },
};

当你使用 globals 为故事(或组件的故事)指定视口时,该视口会被应用,并且不能通过工具栏更改。这对于确保故事始终在特定视口上渲染非常有用。

API

键盘快捷键

如果需要,可以在快捷键页面编辑这些快捷键。

  • 下一个视口: alt + v
  • 上一个视口: alt + shift + v
  • 重置视口: alt + control + v

全局变量

此模块在 viewport 命名空间下为 Storybook 贡献以下全局变量

value

类型: string

设置后,视口将被应用,并且不能通过工具栏更改。必须与 可用视口 的键匹配。

isRotated

类型: boolean

当为 true 时,应用的视口将旋转 90°,例如,从纵向旋转到横向。

参数

此模块在 viewport 命名空间下为 Storybook 贡献以下 参数

disable

类型: boolean

关闭此模块的行为。此参数最常用于允许在更具体的级别上进行覆盖。例如,如果在项目级别将此参数设置为 true,则可以在元数据(组件)或故事级别将其设置为 false 来重新启用。

options

类型

{
  [key: string]: {
    name: string;
    styles: { height: string, width: string };
    type: 'desktop' | 'mobile' | 'tablet' | 'other';
  };
}

指定可用的视口。参见上面的使用示例widthheight 值必须包含单位,例如 '320px'

导出

此模块为 Storybook 贡献以下导出

import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from 'storybook/viewport';

INITIAL_VIEWPORTS

类型: object

视口模块提供的完整初始视口集合,如上所示

MINIMAL_VIEWPORTS

类型: object

视口模块提供的最小视口集合,如上所示。这些是默认使用的。