视口

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

¥The viewport feature allows you to adjust the dimensions of the iframe your story is rendered in. It makes it easy to develop responsive UIs.

配置

¥Configuration

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

¥Out of the box, the viewport feature offers you a standard set of viewports that you can use. If you want to change the default set of viewports, you can configure your own viewports with the viewport parameter in your .storybook/preview.js|ts.

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

¥You can define the available viewports using the options property and set the initial viewport using the initialGlobals property:

// 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;

使用一组详细的设备

¥Use a detailed set of devices

默认情况下，视口功能将使用一组最小的视口，这使你能够在常见的响应式场景中测试 UI。这些插件在 MINIMAL_VIEWPORTS 导出 中也可用，包括以下设备：

¥By default, the viewport feature will use a minimal set of viewports, which enables you to test your UI in common responsive scenarios. These are also available in the MINIMAL_VIEWPORTS export and include the following devices:

如果你需要更详细的设备集，则可以使用 INITIAL_VIEWPORTS 导出，其中包括以下设备：

¥If you need a more detailed set of devices, you can use the INITIAL_VIEWPORTS export, which includes the following devices:

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

¥To use the detailed set of devices, you can adjust the options property in your configuration to include the INITIAL_VIEWPORTS export:

// 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;

添加新设备

¥Add new devices

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

¥If the predefined viewports don't meet your needs, you can add new devices to the list of viewports. For example, let's add two Kindle devices to the default set of minimal viewports:

// 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;

按组件或故事进行配置

¥Configuring per component or story

在某些情况下，在全球范围内使用特定的可视视口并不切实际，你需要将其调整为组件的单个故事或故事集。

¥In some cases, it's not practical for you to use a specific visual viewport on a global scale, and you need to adjust it to an individual story or set of stories for a component.

参数 可以应用于项目、组件和故事级别，这允许你在需要时指定配置。例如，你可以像这样为组件的所有故事设置可用的视口：

¥Parameters can be applied at the project, component, and story levels, which allows you to specify the configuration where needed. For example, you can set the available viewports for all of the stories for a component like so:

// 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;

定义故事的视口

¥Defining the viewport for a story

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

¥The Viewport module enables you to change the viewport applied to a story by selecting from the list of predefined viewports in the toolbar. If needed, you can set a story to default to a specific viewport by using the globals option:

// 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 },
  },
};

API

键盘快捷键

¥Keyboard shortcuts

如果需要，你可以在快捷方式页面上编辑这些。

¥If you need, you can edit these on the shortcuts page.

• 下一个视口：alt + v

  ¥Next viewport: alt + v

• 上一个视口：alt + shift + v

  ¥Previous viewport: alt + shift + v

• 重置视口：alt + control + v

  ¥Reset viewport: alt + control + v

全局

¥Globals

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

¥This module contributes the following globals to Storybook, under the viewport namespace:

value

类型：string

¥Type: string

设置后，将应用视口，并且无法使用工具栏更改。必须与 可用视口 之一的键匹配。

¥When set, the viewport is applied and cannot be changed using the toolbar. Must match the key of one of the available viewports.

isRotated

类型：boolean

¥Type: boolean

如果为 true，则应用的视口将旋转 90°，例如从纵向旋转到横向。

¥When true, the viewport applied will be rotated 90°, e.g., from portrait to landscape orientation.

参数

¥Parameters

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

¥This module contributes the following parameters to Storybook, under the viewport namespace:

disable

类型：boolean

¥Type: boolean

关闭此模块的行为。此参数最有用，允许在更具体的级别进行覆盖。例如，如果此参数在项目级别设置为 true，则可以通过在元（组件）或故事级别将其设置为 false 来重新启用它。

¥Turn off this module's behavior. This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to true at the project level, it could be re-enabled by setting it to false at the meta (component) or story level.

options

类型：

¥Type:

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

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

¥Specify the available viewports. See usage example above. The width and height values must include the unit, e.g. '320px'.

导出

¥Exports

此模块在 命名空间下为 Storybook 贡献了以下导出变量：

¥This module contributes the following exports to Storybook:

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

INITIAL_VIEWPORTS

类型：object

¥Type: object

Viewport 模块 上面列出 提供的完整初始视口集。

¥The full set of initial viewports provided by the Viewport module listed above.

MINIMAL_VIEWPORTS

类型：object

¥Type: object

由 Viewport 模块 上面列出 提供的一组最小视口。这些是默认使用的。

¥A minimal set of viewports provided by the Viewport module listed above. These are used by default.