视口

视口功能允许你调整故事渲染所在的 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)
`iphone5`	iPhone 5	320 × 568
`iphone6`	iPhone 6	375 × 667
`iphone6p`	iPhone 6 Plus	414 × 736
`iphone8p`	iPhone 8 Plus	414 × 736
`iphonex`	iPhone X	375 × 812
`iphonexr`	iPhone XR	414 × 896
`iphonexsmax`	iPhone XS Max	414 × 896
`iphonese2`	iPhone SE (第二代)	375 × 667
`iphone12mini`	iPhone 12 mini	375 × 812
`iphone12`	iPhone 12	390 × 844
`iphone12promax`	iPhone 12 Pro Max	428 × 926
`iphoneSE3`	iPhone SE 第三代	375 × 667
`iphone13`	iPhone 13	390 × 844
`iphone13pro`	iPhone 13 Pro	390 × 844
`iphone13promax`	iPhone 13 Pro Max	428 × 926
`iphone14`	iPhone 14	390 × 844
`iphone14pro`	iPhone 14 Pro	393 × 852
`iphone14promax`	iPhone 14 Pro Max	430 × 932
`galaxys5`	Galaxy S5	360 × 640
`galaxys9`	Galaxy S9	360 × 740
`nexus5x`	Nexus 5X	412 × 668
`nexus6p`	Nexus 6P	412 × 732
`pixel`	Pixel	540 × 960
`pixelxl`	Pixel XL	720 × 1280
`mobile1`	小型手机（也包含在 `MINIMAL_VIEWPORTS` 中）	320 × 568
`mobile2`	大型手机（也包含在 `MINIMAL_VIEWPORTS` 中）	414 × 896
`ipad`	iPad	768 × 1024
`ipad10p`	iPad Pro 10.5 英寸	834 × 112
`ipad11p`	iPad Pro 11 英寸	834 × 1194
`ipad12p`	iPad 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';
  };
}

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

导出

此模块为 Storybook 贡献以下导出

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

`INITIAL_VIEWPORTS`

类型: object

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

`MINIMAL_VIEWPORTS`

类型: object

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