视窗

观看视频教程

视窗工具栏项允许您调整故事渲染的 iframe 的尺寸。它可以轻松地开发响应式 UI。

globals API

此插件已更新为在启用 viewportStoryGlobals 功能标志时使用 globals API。使用 globals，当您为故事指定视窗时，无法从工具栏覆盖它，这确保了在故事之间导航时的一致体验。这将是 Storybook 9 中的默认行为和 API。

配置

默认情况下，视窗插件提供了一组标准的视窗供您使用。如果您想更改默认的视窗集，您可以使用 viewport 参数在您的 .storybook/preview.js 中配置您自己的视窗。

您可以使用 viewports 属性定义可用的视窗，并使用 defaultViewport 属性设置初始视窗

.storybook/preview.ts

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

使用 globals API

当使用 globals API 时，您必须使用 options 属性定义可用的视窗。可以使用 initialGlobals 属性设置初始视窗，该属性接受与此插件的 globals 相同的对象属性。

.storybook/preview.ts

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

使用一组详细的设备

默认情况下，视窗插件将使用一组最小的视窗，这使您能够在常见的响应式场景中测试您的 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

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

.storybook/preview.ts

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

使用 globals API

使用 globals API 时，可用的视口使用 options 属性定义。

.storybook/preview.ts

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

添加新设备

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

使用 globals API

使用 globals API 时，请注意可用的视口使用 options 属性定义。

.storybook/preview.ts

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

为每个组件或故事配置

在某些情况下，在全局范围内使用特定视觉视口并不实用，您需要将其调整为组件的单个故事或一组故事。

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

MyComponent.stories.ts|tsx

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;

定义故事的视口

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

Button.stories.ts|tsx

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

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

使用 globals API

当您使用 globals 为故事（或组件的故事）指定视口时，视口将被应用，并且不能使用工具栏更改。当您希望确保故事始终在特定视口上渲染时，这很有用。

Button.stories.ts|tsx

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

键盘快捷键

如果需要，您可以在快捷键页面编辑它们。

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

使用 globals API

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

`defaultViewport`

类型：string

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

`disable`

使用 globals API

请注意，该属性已重命名为 disabled。

类型：boolean

关闭此附加组件的行为。如果您希望关闭整个 Storybook 的此附加组件，则应在注册 addon-essentials 时执行此操作。有关更多信息，请参阅基本附加组件的文档。

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

`viewports`

类型

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

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

使用 globals API

`options`

类型

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

替换：viewports

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

导出

此插件为 Storybook 贡献以下导出内容

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

`INITIAL_VIEWPORTS`

类型：object

Viewport 插件提供的完整初始视窗集，上面列出。

`MINIMAL_VIEWPORTS`

类型：object

Viewport 插件提供的最小视窗集，上面列出。这些是默认使用的。

视窗

配置

使用一组详细的设备

添加新设备

为每个组件或故事配置

定义故事的视口

API

键盘快捷键

全局

`value`

`isRotated`

参数

`defaultOrientation`

`defaultViewport`

`disable`

`viewports`

`options`

导出

`INITIAL_VIEWPORTS`

`MINIMAL_VIEWPORTS`