Viewport

观看视频教程

Viewport 工具栏项允许您调整渲染 story 的 iframe 的尺寸。它可以轻松开发响应式 UI。

globals API

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

配置

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

您可以使用 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: {
      options: INITIAL_VIEWPORTS,
    },
  },
  initialGlobals: {
    viewport: { value: 'ipad', isRotated: false },
  },
};
 
export default preview;

使用详细的设备集

默认情况下，Viewport 插件将使用最小的视口集，这使您能够在常见的响应式场景中测试 UI。这些也适用于 MINIMAL_VIEWPORTS 导出，并包括以下设备

键	描述	尺寸（宽×高，像素）
`mobile1`	小型手机	320 × 568
`mobile2`	大型手机	414 × 896
`tablet`	平板电脑	834 × 1112

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

键	描述	尺寸（宽×高，像素）
`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

要使用详细的设备集，您可以将配置中的 viewports 属性替换为 INITIAL_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: {
      options: 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;

配置每个组件或 story

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

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

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;

定义 story 的视口

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

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

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

使用 globals API

当您使用 globals 为 story（或组件的 stories）指定视口时，将应用该视口，并且无法使用工具栏进行更改。当您想要确保 story 始终在特定视口上呈现时，这非常有用。

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

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

`defaultViewport`

类型：string

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

`disable`

使用 globals API

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

类型：boolean

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

此参数对于允许在更具体的级别进行覆盖非常有用。例如，如果此参数在项目级别设置为 true，则可以通过在 meta（组件）或 story 级别将其设置为 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 插件提供的最小视口集如上所列。这些是默认使用的。

Viewport

配置

使用详细的设备集

添加新设备

配置每个组件或 story

定义 story 的视口

API

键盘快捷键

Globals

`value`

`isRotated`

参数

`defaultOrientation`

`defaultViewport`

`disable`

`viewports`

`options`

导出

`INITIAL_VIEWPORTS`

`MINIMAL_VIEWPORTS`