視窗

觀看影片教學

「視窗」工具列項目可讓您調整渲染 story 的 iframe 的尺寸。它讓開發響應式 UI 變得容易。

globals API

此擴充功能已更新為在啟用 viewportStoryGlobals 功能旗標時使用 globals API。使用 globals 時，如果您為 story 指定了視窗，則無法從工具列覆寫它，這可確保在 story 之間導覽時體驗一致。這將是 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，像素)
`mobile1`	小型手機	320 × 568
`mobile2`	大型手機	414 × 896
`tablet`	平板電腦	834 × 1112

如果您需要更詳細的裝置組，您可以使用 INITIAL_VIEWPORTS 匯出，其中包含下列裝置

索引鍵	描述	尺寸 (w×h，像素)
`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 時，可用的視埠會使用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;

定義故事的視埠

視埠附加元件可讓您從工具列中預定義的視埠清單中選取，來變更套用至故事的視埠。如果需要，您可以使用 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

指定檢視故事時使用的預設方向。只有在您未啟用全域 API時才可用。

`defaultViewport`

類型：string

指定檢視故事時使用的預設視埠。必須符合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 附加元件提供的最小視窗集如上所列。預設情況下會使用這些。

視窗

設定

使用詳細的裝置組

新增裝置

為每個元件或故事設定

定義故事的視埠

API

鍵盤快捷鍵

全域設定

`value`

`isRotated`

參數

`defaultOrientation`

`defaultViewport`

`disable`

`viewports`

`options`

匯出

`INITIAL_VIEWPORTS`

`MINIMAL_VIEWPORTS`