Viewport

觀看影片教學

Viewport 工具列項目可讓您調整 Story 渲染所在 iframe 的尺寸。這讓開發響應式 UI 變得容易。

globals API

此附加元件已更新為使用 globals API，當 viewportStoryGlobals 功能標誌啟用時。使用 globals，當您為 Story 指定 viewport 時，無法從工具列覆寫，這確保了在 Story 之間導航時體驗的一致性。這將是 Storybook 9 中的預設行為和 API。

設定

Viewport 附加元件開箱即用，提供一組標準的 viewport 供您使用。如果您想變更預設的 viewport 集合，您可以使用 viewport 參數在您的 .storybook/preview.js 中設定您自己的 viewport。

您可以使用 viewports 屬性定義可用的 viewport，並使用 defaultViewport 屬性設定初始 viewport

.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 屬性定義可用的 viewport。可以使用 initialGlobals 屬性設定初始 viewport，該屬性接受與此附加元件的 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 附加元件將使用最小的 viewport 集合，這使您能夠在常見的響應式情境中測試您的 UI。這些也在 MINIMAL_VIEWPORTS 導出中提供，並包含以下裝置

Key	描述	尺寸 (寬×高，像素)
`mobile1`	小型手機	320 × 568
`mobile2`	大型手機	414 × 896
`tablet`	平板	834 × 1112

如果您需要更詳細的裝置集合，您可以使用 INITIAL_VIEWPORTS 導出，其中包含以下裝置

Key	描述	尺寸 (寬×高，像素)
`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 (第 2 代)	375 × 667
`iphone12mini`	iPhone 12 mini	375 × 812
`iphone12`	iPhone 12	390 × 844
`iphone12promax`	iPhone 12 Pro Max	428 × 926
`iphoneSE3`	iPhone SE 第 3 代	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 時，可用的 viewport 是使用 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;

新增裝置

如果預定義的 viewport 無法滿足您的需求，您可以將新裝置新增至 viewport 列表。例如，讓我們將兩個 Kindle 裝置新增至預設的最小 viewport 集合

使用 globals API

當使用 globals API 時，請注意可用的 viewport 是使用 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

在某些情況下，在全球範圍內使用特定的視覺 viewport 不切實際，您需要針對個別 Story 或元件的一組 Story 進行調整。

Parameters 可以應用於專案、元件和 Story 層級，這讓您可以根據需要指定設定。例如，您可以為元件的所有 Story 設定可用的 viewport，如下所示

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

Viewport 附加元件讓您能夠透過從工具列中預定義的 viewport 列表中選擇來變更應用於 Story 的 viewport。如果需要，您可以使用 parameters.viewport.default 參數將 Story 設定為預設為特定的 viewport

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 的預設 viewport。當檢視 Story 時，您仍然可以使用工具列變更 viewport。

使用 globals API

當您使用 globals 為 Story（或元件的 Stories）指定 viewport 時，viewport 會被應用，且無法使用工具列變更。當您想要確保 Story 始終在特定的 viewport 上渲染時，這非常有用。

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

鍵盤快捷鍵

如果需要，您可以在快捷鍵頁面編輯這些。

下一個 viewport：alt + v
上一個 viewport：alt + shift + v
重設 viewport：alt + control + v

使用 globals API

指定檢視 Story 時使用的預設方向。僅在您尚未啟用 globals API 時可用。

`defaultViewport`

類型：string

指定檢視 Story 時使用的預設 viewport。必須與 viewports（或 options）物件中的 key 相符。

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

指定可用的 viewport。請參閱上方的使用範例。width 和 height 值必須包含單位，例如 '320px'。

使用 globals API

`options`

類型

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

取代：viewports

指定可用的 viewport。請參閱上方的使用範例。width 和 height 值必須包含單位，例如 '320px'。

Exports

此附加元件將以下 exports 貢獻給 Storybook

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

`INITIAL_VIEWPORTS`

類型：object

Viewport 附加元件提供的完整初始 viewport 集合，如上所列。

`MINIMAL_VIEWPORTS`

類型：object

Viewport 附加元件提供的最小 viewport 集合如上所列。這些是預設使用的。

Viewport

設定

使用詳細的裝置集合

新增裝置

設定每個元件或 Story

定義 Story 的 viewport

API

鍵盤快捷鍵

Globals

`value`

`isRotated`

Parameters

`defaultOrientation`

`defaultViewport`

`disable`

`viewports`

`options`

Exports

`INITIAL_VIEWPORTS`

`MINIMAL_VIEWPORTS`