加入直播会话:美国东部时间周四上午 11 点,Storybook 9 发布及 AMA 问答
文档
Storybook Docs

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-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'],
  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-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 编写 Stories

Storybook 提供了零配置的 TypeScript 支持,允许你使用这种语言编写 Stories,而无需额外的配置。你可以使用这种格式来提高类型安全和代码补全。例如,如果你正在测试一个 Button 组件,可以在你的 story 文件中执行以下操作

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 的强大功能和导出的泛型类型(MetaStoryObj),告知 Storybook 如何推断组件的元数据以及组件输入(例如 props)的类型。这可以通过让你的 IDE 显示 Storybook 注入了哪些属性来大大改善开发体验。

TypeScript 4.9 支持

假设你正在使用 TypeScript 4.9+ 的项目工作,你可以更新组件 stories 以使用新的 satisfies 运算符,以确保你的组件 stories 具有更严格的类型检查。例如

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;

现在,当你定义或更新一个 story 时,如果缺少必需的 arg,你将自动收到通知。但是,你不仅限于在组件级别使用 satisfies 运算符。如果需要,你也可以在 story 级别使用它。例如

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)联系社区。