Viewport

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

Storybook with default viewports visible

配置

开箱即用，视口功能提供了一组标准的视口供您使用。如果您想更改默认的视口集，您可以在 .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 type { 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 导出中找到，包括以下设备：

键	描述	尺寸 (宽×高, px)
`mobile1`	小型手机	320 × 568
`mobile2`	大型手机	414 × 896
`tablet`	平板电脑	834 × 1112
`desktop`	桌面	1024 × 1280

如果您需要更详细的设备集，您可以使用 INITIAL_VIEWPORTS 导出，它包含以下设备：

键	描述	尺寸 (宽×高, 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
`iphone11pro`	iPhone 11 Pro	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
`ipad`	iPad	768 × 1024
`ipad10p`	iPad Pro 10.5 英寸	834 × 1112
`ipad11p`	iPad Pro 11 英寸	834 × 1194
`ipad12p`	iPad Pro 12.9 英寸	1024 × 1366

要使用详细的设备集，您可以调整配置文件中的 options 属性，以包含 INITIAL_VIEWPORTS 导出。

.storybook/preview.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
import type { 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 type { 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

全局变量

此模块向 Storybook 贡献了以下全局变量，位于 viewport 命名空间下：

`value`

类型：string

设置后，将应用视口，并且无法通过工具栏进行更改。必须与可用视口中的某个键匹配。

`isRotated`

类型：boolean

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

参数

此模块向 Storybook 贡献了以下参数，位于 viewport 命名空间下：

`disable`

类型：boolean

禁用此模块的行为。此参数最适用于允许在更特定的级别进行覆盖。例如，如果此参数在项目级别设置为 true，则可以通过在 meta（组件）或故事级别将其设置为 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

视口模块提供的最小视口集，如上文列表所示。默认情况下使用这些视口。