
Storybook 7 中改进的类型安全性
CSF3 语法结合 TypeScript satisfies 提供了更严格的类型和改进的开发体验
使用 TypeScript 编写代码可以提高生产力并增强代码的健壮性。你可以获得类型检查警告、自动补全,并且 Storybook 会推断类型以自动生成 ArgsTable。它还有助于在编码时检测 bug 和边界情况。
自 6.0 版本以来,Storybook 就提供了内置的零配置 TypeScript 支持。这带来了很棒的自动补全体验,但不幸的是,它并没有警告你缺少必需的 args。
我很高兴地宣布,Storybook 7 为故事提供了增强的类型安全性。这得益于 组件故事格式 (CSF) 3 和新的 TypeScript (4.9+) satisfies
运算符的结合使用。
- 💪 更严格的故事类型
- ⌨️ 更好的编辑器内类型检查
- 🌐 Meta 和 Story 对象相互关联,用于推断组件级别的 args
- 🎮 Action args 自动检测
- 🤖 轻松升级的 Codemod
为何需要新的类型?
Storybook 6 中的 TypeScript 类型对于自动补全效果很好。然而,它们并非完全类型安全。如果你忘记提供一个 prop,TypeScript 应该在编辑器中提醒你;不幸的是,你只会在运行时收到 TypeError。


喜欢类型安全的人 (比如我!) 一直通过完全不使用 Storybook args 约定来规避这个问题,就像这样
const Primary: Story<ButtonProps> = () => (
<Button disabled label="Label" />
);
这样可行,但如果你想使用 controls,就必须使用 args
,因为 Storybook 需要初始值才能将其显示在 control 面板中,然后根据用户输入动态覆盖它。此外,这种语法需要更多的重复,因为你必须在故事之间重复模板。

介绍 StoryObj
类型
CSF3 使你能够将故事作为对象来操作。为了方便这一点,我们还创建了一个 StoryObj
类型,它可以自动推断组件 props 的类型。
提供组件类型 (例如,typeof Button
) 作为泛型参数。或者,如果你的渲染器是基于类的——比如 Svelte、Angular 或 Web Components——你可以直接使用组件本身 (例如,Button
)。
以下是并排比较


之前的 Story
类型不够强大,无法自动推断 prop 类型,因此你必须手动指定它们。此外,React 组件通常不导出其 props 的类型,因此你必须依赖 React 特有的 ComponentStory
类型。
然而,这种新语法适用于 React、Vue、Svelte、Angular 和 Web Components!因此,我们在 Storybook 7 中弃用了 React 特有的 ComponentMeta
和 ComponentStory
工具。
结合 satisfies
提升类型安全性
如果你使用的是 TypeScript 4.9+,你可以利用新的 satisfies 运算符来获得更严格的类型检查。为了说明这一点,我们来看一个例子。
考虑这个 Button 组件。你会注意到,在 Primary 故事中 (左侧),我们没有指定必需的 label
arg。TypeScript 应该为此抛出错误,但它没有。

我们使用 satisfies
运算符来解决这个问题。
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta = {
title: 'Example/Button',
component: Button,
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Primary: Story = {
args: {
primary: true,
},
};
现在如果你忘记提供必需的 arg,你将收到 TypeScript 错误

自动推断组件级别 args
即使在 meta 级别的 args
中提供了 label
,TypeScript 仍然在我们的故事上显示错误。这是因为 TypeScript 不知道 CSF 中它们之间的关联。所以我们来告诉它!将 typeof meta
传递给 StoryObj
,这样 TypeScript 就能理解 args 可以在故事级别和 meta 级别定义,错误就会消失。
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta = {
title: 'Example/Button',
component: Button,
args: {
label: 'Default',
},
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
// 👇 TS won't complain about "label" missing
export const Primary: Story = {
args: {
primary: true,
},
};
const Secondary: Story = {
args: { disabled: false }
};
const Disabled: Story = {
args: { disabled: true }
};
我们还建议你将 StoryObj<typeof meta>
提取到一个类型中,以便在文件中的所有故事中重用。例如,我们用它来为上面的 Primary、Secondary 和 Disabled 故事进行类型标注。
整合起来
这是一个完整的示例。注意我们在 meta 级别和 story 级别都使用了 satisfies
模式。这有助于我们在故事之间共享 play 函数时保持类型安全。
当在故事之间共享 play
函数时,TypeScript 默认会抛出错误,因为 play
函数可能未定义。然而,satisfies
运算符使 TypeScript 能够推断 play
是否已定义。
import type { Meta, StoryObj } from '@storybook/react';
import { screen, userEvent } from '@storybook/testing-library';
import { AccountForm } from './AccountForm';
const meta = {
component: AccountForm,
} satisfies Meta<typeof AccountForm>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Standard = {
args: {
passwordVerification: false,
},
} satisfies Story;
export const StandardEmailFilled = {
...Standard,
play: async () => {
await userEvent.type(
await screen.findByLabelText('Email'),
'marcus@acme.com'
);
},
} satisfies Story;
export const VerificationSuccess = {
args: {
passwordVerification: true,
},
play: async () => {
// 👇 Reuse play function from previous story
await StandardEmailFilled.play();
await userEvent.type(
await screen.findByLabelText('Password'),
'j129ks#82p23o'
);
await userEvent.type(
await screen.findByLabelText('Verify Password'),
'j129ks#82p23o'
);
await userEvent.click(
await screen.findByRole('button', { name: /submit/i })
);
},
} satisfies Story;
框架特定提示
基于模板的框架(如 Vue 和 Svelte)通常需要编辑器扩展来启用语法高亮、自动补全和类型检查。这里有一些提示,可以帮助你为它们建立理想的环境。
Vue
Vue 对 TypeScript 有极好的支持,我们在故事文件中也尽力利用了这一点。例如,考虑以下强类型的 Vue3 单文件组件 (SFC)
<script setup lang="ts">
defineProps<{ count: number, disabled: boolean }>()
const emit = defineEmits<{
(e: 'increaseBy', amount: number): void;
(e: 'decreaseBy', amount: number): void;
}>();
</script>
<template>
<div class="card">
{{ count }}
<button @click="emit('increaseBy', 1)" :disabled='disabled'>
Increase by 1
</button>
<button @click="$emit('decreaseBy', 1)" :disabled='disabled'>
Decrease by 1
</button>
</div>
</template>
你可以使用 vue-tsc
对 SFC 文件进行类型检查,并通过安装 Vue Language Features (Volar) 和 TypeScript Vue Plugin 扩展来在 VSCode 中获得编辑器支持。
此设置将为你的 .stories.ts
文件添加 *.vue
导入的类型支持,提供相同的类型安全和自动补全功能。

Svelte
Svelte 也为 .svelte
文件提供了出色的 TypeScript 支持。例如,考虑以下组件。你可以使用 svelte-check
运行类型检查,并通过 Svelte for VSCode 扩展添加 VSCode 编辑器支持。
<script lang="ts">
import { createEventDispatcher } from 'svelte';
export let count: number;
export let disabled: boolean;
const dispatch = createEventDispatcher();
</script>
<div class="card">
{count}
<button on:click={() => dispatch('increaseBy', 1)} {disabled}> Increase by 1 </button>
<button on:click={() => dispatch('decreaseBy', 1)} {disabled}> Decrease by 1 </button>
</div>
同样的设置也适用于 Svelte 故事文件,提供了类型安全和自动补全。

Angular 和 Web Components
我们目前尚无法使用 satisfies
运算符为 Angular 和 Web components 提供额外的类型安全。它们都采用了类加装饰器的方式。装饰器提供了运行时元数据,但在编译时无法提供元数据。
因此,似乎无法确定类中的属性是必需属性、可选属性(但由于默认值而非可空)还是非可空内部状态变量。
更多信息,请参阅以下讨论:github.com/storybookjs/storybook/discussions/20988
立即尝试
新的 Meta
和 StoryObj
类型已在 Storybook 7 beta 中提供;请参阅我们的 SB7 迁移指南。项目升级后,你可以运行以下迁移命令
npx storybook migrate upgrade-deprecated-types --glob="**/*.stories.@(js|jsx|ts|tsx)"
请注意,此 codemod 不会自动添加 satisfies
运算符。我们计划很快发布第二个 codemod,它将使 TypeScript 4.9+ 用户能够迁移到新类型并添加 satisfies
运算符。请在未来几周内关注此更新。
下一步是什么?
我们很高兴 TypeScript 4.9 更新最终解决了长期以来关于缺少必需参数没有警告的问题。satisfies
运算符与 StoryObj
类型结合使用,使 TypeScript 能够理解组件级和故事级参数之间的关联。因此,它现在更擅长显示这些警告。
我们希望很快发布更多改进。例如,我们正在探索根据安装的插件改进故事参数类型化的方法。此外,我们正在寻求改进 argTypes
的类型定义。
Storybook 长期以来一直提供内置的 TypeScript 支持。然而,故事并没有强类型。
— Storybook (@storybookjs) 2023年2月8日
你在故事文件中获得了出色的自动补全功能,但没有关于缺少 args 的警告。
Storybook 7 通过结合 CSF3 和 TS satisfies 运算符修复了这个问题 » https://#/eF1NJER00o pic.twitter.com/Qc5sJRFWDF