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 如何推斷元件的 metadata 和元件的輸入類型（例如 props）。這可以讓你的 IDE 顯示 Storybook 注入了哪些屬性，從而大大改善開發人員的體驗。

TypeScript 4.9 支援

假設你正在處理一個使用 TypeScript 4.9+ 的專案，你可以更新你的元件故事，使用新的 satisfies 運算子，以確保你的元件故事有更嚴格的類型檢查。例如：

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;

現在，當你定義一個故事或更新現有的故事時，你會自動收到通知，告知你缺少一個必要的 arg。但是，你不僅限於在元件層級使用 satisfies 運算子。如果你需要，你也可以在故事層級使用它。例如：

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 難以推斷元件的 metadata 並自動產生類型。為了解決這個問題，您可以更新 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 討論）。