TypeScript
Storybook 提供集成的 TypeScript 体验,包括零配置设置和内置的 API、插件和 stories 类型。
使用 TypeScript 配置 Storybook
Storybook 的配置文件(即,main.ts
)被定义为用 TypeScript 编写的 ESM 模块,为您提供支持现有框架的基线配置,同时使您能够在编辑器中获得更严格的类型检查和自动补全。以下是精简的配置文件。
// 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;
有关更多详细信息和其他属性,请参阅 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,}, |
// 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 文件中执行以下操作
// 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 进行更严格的类型检查。例如
// 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 级别使用它。例如
// 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
运算符未按预期工作
开箱即用,对于几乎每个已经使用 TypeScript 4.9 或更高版本的框架,Storybook 都支持 satisfies
运算符。但是,由于 Angular 和 Web Components 框架的限制,在应用此运算符以获得额外的类型安全性时,您可能会遇到问题。这主要是由于这两个框架当前的实现方式,使得 Storybook 几乎不可能确定组件属性是否是必需的。如果您遇到此问题,请在 GitHub Discussions 上发起支持请求。
Storybook 没有为外部包创建所需的类型
如果您的项目依赖于第三方库,并且没有生成预期的类型,从而阻止您准确地记录您的组件,您可以调整 Storybook 配置文件中的 reactDocgen
配置选项以使用 react-docgen-typescript
并包含所需的选项。例如
// 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
。例如
// 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.org.cn/docs/configure/typescript for more information.
reactDocgenTypescriptOptions: {},
},
};
export default config;
如果您仍然遇到问题,我们建议使用默认的沟通渠道(例如,GitHub 讨论)联系社区。