视口

Viewport 工具栏项允许你调整故事渲染的 iframe 的尺寸。它使开发响应式 UI 变得容易。

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

配置

¥Configuration

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

¥Out of the box, the Viewport addon 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.

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

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

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Preview } from '@storybook/your-renderer';
import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
const preview: Preview = {
  parameters: {
    viewport: {
      viewports: INITIAL_VIEWPORTS,
      defaultViewport: 'ipad',
    },
  },
};
 
export default preview;

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Preview } from '@storybook/your-renderer';
 
const preview: Preview = {
  parameters: {
    viewport: {
      viewports: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
};
 
export default preview;

使用一组详细的设备

¥Use a detailed set of devices

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

¥By default, the Viewport addon 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:

要使用详细的设备集，你可以将配置中的 viewports 属性替换为 INITIAL_VIEWPORTS 导出：

¥To use the detailed set of devices, you can replace the viewports property in your configuration with the INITIAL_VIEWPORTS export:

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Preview } from '@storybook/your-renderer';
import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
const preview: Preview = {
  parameters: {
    viewport: {
      viewports: INITIAL_VIEWPORTS,
      defaultViewport: 'ipad',
    },
  },
};
 
export default preview;

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Preview } from '@storybook/your-renderer';
 
const preview: Preview = {
  parameters: {
    viewport: {
      viewports: 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-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import { Preview } from '@storybook/your-renderer';
import { MINIMAL_VIEWPORTS } from '@storybook/addon-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: {
      viewports: {
        ...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:

import type { Meta, StoryObj } from '@storybook/react';
import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
import { MyComponent } from './MyComponent';
 
const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  parameters: {
    viewport: {
      //👇 Set available viewports for every story in the file
      viewports: INITIAL_VIEWPORTS,
    },
  },
};
 
export default meta;

定义故事的视口

¥Defining the viewport for a story

Viewport 插件使你可以通过从工具栏中的预定义视口列表中进行选择来更改应用于故事的视口。如果需要，你可以使用 parameters.viewport.default 参数将故事默认设置为特定的视口：

¥The Viewport addon 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 parameters.viewport.default parameter:

// Replace your-framework with the name of your framework
import type { Meta, StoryObj } from '@storybook/your-framework';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  parameters: {
    // 👇 Set default viewport for all component stories
    viewport: { defaultViewport: 'tablet' },
  },
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const OnPhone: Story = {
  parameters: {
    // 👇 Override default viewport for this story
    viewport: { defaultViewport: 'mobile1' },
  },
};

顾名思义，此方法仅设置故事的默认视口。查看故事时，你仍然可以使用工具栏更改视口。

¥As implied by the name, this method only sets the default viewport for a story. You can still change the viewport using the toolbar when viewing the story.

// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
import type { Meta, StoryObj } from '@storybook/your-renderer';
 
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  component: Button,
  globals: {
    // 👇 Set viewport for all component stories
    viewport: { value: 'tablet', isRotated: false },
  },
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
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

参数

¥Parameters

此插件将以下 参数 贡献给 Storybook，位于 viewport 命名空间下：

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

defaultOrientation

类型：'portrait' | 'landscape'

¥Type: 'portrait' | 'landscape'

默认：'portrait'

¥Default: 'portrait'

指定查看故事时使用的默认方向。仅在你未启用 全局 API 时可用。

¥Specifies the default orientation used when viewing a story. Only available if you haven't enabled the globals API.

defaultViewport

类型：string

¥Type: string

指定查看故事时使用的默认视口。必须与 viewports（或 options）对象中的键匹配。

¥Specifies the default viewport used when viewing a story. Must match a key in the viewports (or options) object.

disable

类型：boolean

¥Type: boolean

关闭此插件的行为。如果你希望为整个 Storybook 关闭此插件，你应该在注册 addon-essentials 时这样做。有关更多信息，请参阅 必备插件文档。

¥Turn off this addon's behavior. If you wish to turn off this addon for the entire Storybook, you should do so when registering addon-essentials. See the essential addon's docs for more information.

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

¥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.

viewports

类型：

¥Type:

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

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

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

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

导出

¥Exports

此插件为 Storybook 贡献了以下导出：

¥This addon contributes the following exports to Storybook:

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

INITIAL_VIEWPORTS

类型：object

¥Type: object

Viewport 插件 上面列出 提供的全套初始视口。

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

MINIMAL_VIEWPORTS

类型：object

¥Type: object

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

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