TypeScript

Storybook 提供了一体化的 TypeScript 体验，包括零配置设置以及 API、插件和故事的内置类型。

配置 Storybook 与 TypeScript

Storybook 的配置文件（即 main.ts）定义为一个使用 TypeScript 编写的 ESM 模块，为您提供支持现有框架的基线配置，同时在编辑器中启用更严格的类型检查和自动完成。以下是一个精简的配置文件。

.storybook/main.ts

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
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-docs'],
  staticDirs: ['../public'],
};
 
export default config;

有关更多详细信息和附加属性，请参阅 main 配置 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-vite, nextjs, vue3-vite, etc.
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 编写故事

Storybook 提供零配置的 TypeScript 支持，允许您在无需额外配置的情况下使用该语言编写故事。您可以使用此格式来改进类型安全和代码补全。例如，如果您正在测试一个 Button 组件，您可以在故事文件中执行以下操作：

Button.stories.ts|tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
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>;
 
//👇 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+ 的项目，您可以更新组件故事以使用新的 satisfies 操作符来确保组件故事更严格的类型检查。例如：

Button.stories.ts|tsx

// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
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 framework you are using, e.g. react-vite, nextjs, vue3-vite, etc.
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-vite, nextjs, vue3-vite, etc.
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-vite, nextjs, vue3-vite, etc.
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.org.cn/docs/configure/typescript for more information.
    reactDocgenTypescriptOptions: {},
  },
};
 
export default config;

如果您仍然遇到问题，我们建议您通过默认的沟通渠道（例如，GitHub discussions）与社区联系。