TypeScript

Storybook 提供整合的 TypeScript 體驗，包括零配置設定以及適用於 API、附加元件和 Stories 的內建類型。

使用 TypeScript 設定 Storybook

Storybook 的設定檔（即 main.ts）定義為以 TypeScript 撰寫的 ESM 模組，為您提供基準設定以支援您現有的框架，同時讓您在編輯器中啟用更嚴格的類型檢查和自動完成功能。以下是節略的設定檔。

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  // Required
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  // Optional
  addons: ['@storybook/addon-essentials'],
  docs: {
    autodocs: 'tag',
  },
  staticDirs: ['../public'],
};
 
export default config;

請參閱主要設定 API 參考文件以取得更多詳細資訊和額外屬性。

如果您使用 @storybook/builder-vite，請參閱 Vite 建置工具 TypeScript 文件。

Storybook 開箱即用，旨在與各種第三方函式庫搭配使用，讓您可以安全地存取和記錄元件的中繼資料（例如，props），而無需任何額外設定。它依賴 react-docgen，這是一個快速且高度可自訂的剖析器，用於處理 TypeScript 檔案，以推斷元件的中繼資料並自動產生類型，以提高效能和類型安全性。如果您需要自訂特定使用案例的預設設定，您可以調整 Storybook 設定檔並提供所需的選項。以下列出可用的選項以及如何使用它們的範例。

選項	描述
`check`	適用於基於 Webpack 的專案。在 Storybook 中啟用類型檢查 `typescript: { check: true },`
`checkOptions`	需要啟用 `check` 選項。設定 `fork-ts-checker-webpack-plugin` 外掛程式 `typescript: { checkOptions: {},},`
`reactDocgen`	設定 Storybook 使用的 TypeScript 剖析器。可用選項：`react-docgen`（預設）、`react-docgen-typescript`、`false` `typescript: { reactDocgen: 'react-docgen'},`
`reactDocgenTypescriptOptions`	需要將 `reactDocgen` 選項設為 `react-docgen-typescript`。針對每個建置工具設定 `react-docgen-typescript-plugin` 外掛程式 `typescript: { reactDocgen: 'react-docgen-typescript', reactDocgenTypescriptOptions: {},},`
`skipCompiler`	停用透過編譯器剖析 Typescript 檔案 `typescript: { skipCompiler:false,},`

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    check: false,
    checkOptions: {},
    skipCompiler: false,
  },
};
 
export default config;

適用於 typescript 設定選項的其他選項。請參閱 config.typescript API 參考文件以取得更多資訊。

使用 TypeScript 撰寫 Stories

Storybook 提供零配置 TypeScript 支援，讓您可以使用此語言撰寫 Stories，而無需額外設定。您可以使用此格式來提高類型安全性和程式碼完成度。例如，如果您要測試 Button 元件，您可以在 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,
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
//👇 Throws a type error if the args don't match the component props
export const Primary: Story = {
  args: {
    primary: true,
  },
};

上面的範例結合了 TypeScript 的強大功能與匯出的泛型類型（Meta 和 StoryObj），以告知 Storybook 如何推斷元件的中繼資料和元件輸入的類型（例如，props）。這可以讓您的 IDE 向您顯示 Storybook 注入了哪些屬性，從而大幅改善開發人員體驗。

TypeScript 4.9 支援

假設您正在處理使用 TypeScript 4.9 以上版本的專案，您可以更新元件 Stories 以使用新的 satisfies 運算子，以確保您的元件 Stories 具有更嚴格的類型檢查。例如

Button.stories.ts|tsx

// Replace your-framework with the name of your framework
import type { Meta } from '@storybook/<your-framework>';
 
import { Button } from './Button';
 
const meta = {
  component: Button,
} satisfies Meta<typeof Button>; // 👈 Satisfies operator being used for stricter type checking.
 
export default meta;

現在，當您定義 Story 或更新現有 Story 時，您會自動收到通知，告知您遺失了必要的 arg。但是，您不僅限於在元件層級使用 satisfies 運算子。如果需要，您也可以在 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 = {
  component: Button,
} satisfies Meta<typeof Button>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Example = {
  args: {
    primary: true,
    label: 'Button',
  },
} satisfies Story;

疑難排解

`satisfies` 運算子無法如預期運作

Storybook 開箱即用，幾乎支援所有已使用 TypeScript 4.9 或更高版本的框架的 satisfies 運算子。但是，由於 Angular 和 Web Components 框架的限制，當您將此運算子應用於額外的類型安全性時，可能會遇到問題。這主要是由於這兩個框架目前的實作方式，使得 Storybook 幾乎無法判斷元件屬性是否為必要屬性。如果您遇到此問題，請在 GitHub Discussions 上開啟支援請求。

Storybook 未針對外部套件建立必要的類型

如果您的專案依賴第三方函式庫，且未產生預期的類型，導致您無法準確記錄元件，您可以調整 Storybook 設定檔中的 reactDocgen 設定選項，改為使用 react-docgen-typescript 並包含必要的選項。例如

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, react-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      compilerOptions: {
        allowSyntheticDefaultImports: false,
        esModuleInterop: false,
      },
      // Filter out third-party props from node_modules except @mui packages.
      propFilter: (prop) =>
        prop.parent ? !/node_modules\/(?!@mui)/.test(prop.parent.fileName) : true,
    },
  },
};
 
export default config;

我的元件未產生類型

如果您正在處理 React 專案，則會使用 react-docgen 函式庫自動為您的元件啟用類型推斷，以縮短建置時間並提高類型安全性。但是，您可能會遇到某些選項無法如預期運作的情況（例如，Enums、React 的 forwardRef）。這主要是由於 react-docgen 套件的實作方式，使得 Storybook 難以推斷元件的中繼資料並自動產生類型。若要解決此問題，您可以更新 Storybook 設定檔中的 typescript 設定選項，改為使用 react-docgen-typescript。例如

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, react-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    // Provide your own options if necessary.
    // See https://storybook.dev.org.tw/docs/configure/typescript for more information.
    reactDocgenTypescriptOptions: {},
  },
};
 
export default config;

如果您仍然遇到問題，我們建議使用預設的溝通管道（例如，GitHub 討論區）與社群聯繫。