Storybook 实战：用 CSF 3 与 CSF Next 编写类型安全的 Button 基线故事

Storybook 实战：用 CSF 3 与 CSF Next 编写类型安全的 Button 基线故事

这篇指南围绕 Storybook 官方代码片段 docs/_snippets/button-story-baseline.md 展开——它是在 docs/configure/integration/typescript.mdx 的 “Write stories with TypeScript” 一节中作为开箱即用、零配置示例被引用的“基线故事”模板。文章会逐步拆解 CSF 3 与实验性的 CSF Next（preview.meta/meta.story）两种写法，覆盖 Angular、React、Vue 3、Web Components 等渲染器变体，并结合仓库源码解释Meta/StoryObj泛型如何把args与组件 props 关联起来做编译期校验，以及如何用 TypeScript 4.9 的satisfies运算符进一步收紧类型。读完后你将能独立写出任意框架下类型安全、可被编辑器自动补全并被 Storybook 正确索引的故事文件。

一段“基线故事”到底由哪几部分组成

所谓基线（baseline）故事，是指一个组件在没有任何装饰器、全局参数、标签（tags）和渲染逻辑时的最小故事文件骨架。它只承担一件事：把组件声明给 Storybook，并用args声明一种渲染状态。以 Button 组件为例，这段骨架通常包含三个固定动作：

1. 从框架入口导入类型：Meta与StoryObj不是手写的普通接口，而是每个渲染器包（如@storybook/react、@storybook/angular、@storybook/web-components-vite）对外导出的泛型类型；
2. 通过默认导出定义meta：用component字段告诉 Storybook“这段故事要渲染哪个组件”，并可补充title、tags、parameters等元信息；
3. 导出具名故事并声明args：每个导出的具名变量就是一个故事，args会被作为组件的输入（props / inputs）注入。

这份片段之所以被官方文档当作 TypeScript 示例反复引用，是因为它集中演示了 Storybook 的核心理念：默认导出为 meta、具名导出为 story（Component Story Format，CSF）。仓库中负责在构建期把.stories文件解析成故事索引的正是 CSF 工具链，例如 code/core/src/csf-tools/CsfFile.ts 与 code/core/src/csf/index.ts，它们以该文件结构作为解析输入。

CSF 3：同一骨架在不同框架下的写法差异

片段的第一组变体对应的是标准 CSF 3（Meta+StoryObj），同一段意图在 Angular、通用框架、Web Components 上各有细微差别，下面逐一给出可完整运行的最小文件。

通用写法（React、Vue 3、Preact、Svelte 等，需替换框架名）

// 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, }, };

这是全仓库大多数.stories.tsx文件的默认形态（例如 code/core/src/components/components/Button/Button.stories.tsx 就沿用了Meta/StoryObj的组织方式）。三处细节值得注意：

• import type只引入类型，不会进入运行时打包产物；
• meta用satisfies Meta<typeof Button>而非: Meta<typeof Button>注解，保证component、title等字段在不丢失精确类型的前提下被约束；
• StoryObj<typeof meta>让故事对象的args精确对应当前组件的 props 类型，这是“args 不匹配就报类型错误”的关键，后文会结合源码展开。

Angular 写法（Component 类 + 类装饰器输入）

// Button.stories.ts (Angular) import type { Meta, StoryObj } from '@storybook/angular'; import { Button } from './button.component'; const meta: Meta<Button> = { component: Button, }; export default meta; type Story = StoryObj<Button>; //👇 Throws a type error if the args don't match the component props export const Primary: Story = { args: { primary: true, }, };

Angular 的组件是一个带@Input()的类而非纯函数，因此Meta与StoryObj的泛型参数直接传入组件类Button，args会被按@Input声明做类型匹配。Angular 渲染器入口位于 code/frameworks/angular/src/client/preview.ts，其公开类型定义（Meta、StoryObj）在 code/frameworks/angular/src/client/public-types.ts。

Web Components 写法（component 传的是元素标签名）

// Button.stories.ts (Web Components) import type { Meta, StoryObj } from '@storybook/web-components-vite'; const meta: Meta = { component: 'demo-button', }; export default meta; type Story = StoryObj; export const Primary: Story = { args: { primary: true, }, };

Web Components 渲染器没有“导入组件类”这一步，component字段接收的是已在浏览器注册的自定义元素标签字符串（如demo-button），Storybook 会把渲染结果包裹进该标签并通过属性/插槽注入args。其渲染器与类型出口分别位于 code/renderers/web-components/src/preview.ts 与 code/renderers/web-components/src/public-types.ts。由于组件是字符串标签，args无法与真实组件实现一一对应，因此这里既没有typeof Button，也没有 story 级别的组件级类型推导。

类型安全从何而来：StoryObj 在源码里做了什么

片段中反复出现的注释 “Throws a type error if the args don't match the component props” 并不是空话，它的保证来自渲染器包中StoryObj类型定义的写法。以 React 为例，code/renderers/react/src/public-types.ts 从第 47 行起定义了条件类型StoryObj：它会检查传入的TMetaOrCmpOrArgs是否带有render或component字段，并据此尝试从组件身上反向推断出args的精确形状，否则退回Args基线类型。

可以推断出的调用关系是：

• 当meta携带component: Button时，StoryObj<typeof meta>能拿到 Button 的 props 类型；
• 故事对象里args的每一项键值都会被逐一核对；
• 一旦Primary故事写了meta中不存在的属性、或把字符串赋给了布尔字段（如把primary: true写成primary: 'yes'），编译期就会抛错。

在组件与args无法静态关联的场景（如 Web Components 的标签字符串），StoryObj泛型自动退回到不约束args形状的宽松形态，这正是上文 Web Components 变体不写typeof meta也能编译通过的原因。编辑器与构建工具的这类补全能力，均由@storybook/csf提供的基础类型与各渲染器扩展共同支撑。

CSF Next（🧪 实验特性）：preview.meta 与 meta.story 工厂写法

片段的第二组变体标注为 “CSF Next 🧪”，它把“默认导出 meta”的传统写法替换成了先拿到一个全局preview实例，再由它工厂化地派生 meta 与 story：

// Button.stories.ts (React / CSF Next 🧪) import preview from '../.storybook/preview'; import { Button } from './Button'; const meta = preview.meta({ component: Button, }); //👇 Throws a type error if the args don't match the component props export const Primary = meta.story({ args: { primary: true, }, });

CSF Next 的核心思路是：故事文件从.storybook/preview导入一个已携带全局配置（preview annotations、addons 及其扩展类型）的 preview 对象，再通过preview.meta()创建组件级 meta、通过meta.story()创建故事。这样 meta 与 story 会天然继承 preview 中 addon 声明的参数/全局量类型，而不必再靠各文件手动重复声明。这一套工厂 API 在仓库中的实现位于 code/core/src/csf/csf-factories.ts（由 code/core/src/csf/index.ts 统一导出），核心概念是definePreview、definePreviewAddon与preview.meta(...)。

仓库的测试用例 code/core/src/csf/csf-factories.test.ts 直观地证明了这套类型推断能力：它通过definePreviewAddon声明带类型的 addon，然后用preview.type<{ args: ... }>().meta({...}).story({...})连缀创建故事，并断言错误参数（如把value: 1赋给期望字符串的字段）会在类型层被拦截（对应测试中的@ts-expect-error断言）。也就是说，基线片段中preview.meta({ component: Button })与meta.story({ args: { primary: true } })的写法不仅是语法糖，背后还有真实的类型测试覆盖。

CSF Next 的框架变体

Angular（组件类作为输入）：

// Button.stories.ts (Angular / CSF Next 🧪) import preview from '../.storybook/preview'; import { Button } from './button.component'; const meta = preview.meta({ component: Button, }); //👇 Throws a type error if the args don't match the component props export const Primary = meta.story({ args: { primary: true, }, });

Web Components（自定义元素标签）：

// Button.stories.ts (Web Components / CSF Next 🧪) import preview from '../.storybook/preview'; const meta = preview.meta({ component: 'demo-button', }); //👇 Throws a type error if the args don't match the component props export const Primary = meta.story({ args: { primary: true, }, });

Vue 3（SFC 组件）：

// Button.stories.ts (Vue 3 / CSF Next 🧪) import preview from '../.storybook/preview'; import Button from './Button.vue'; const meta = preview.meta({ component: Button, }); //👇 Throws a type error if the args don't match the component props export const Primary = meta.story({ args: { primary: true, }, });

Vue 3 渲染器的公开类型在 code/renderers/vue3/src/public-types.ts，其 CSF 工厂相关测试位于 code/renderers/vue3/src/csf-factories.test.ts；React 侧的同类工厂测试见 code/renderers/react/src/csf-factories.test.tsx。若在本地手动搭建新故事文件，官方 CLI 也会按该模板生成对应的工厂写法，模板源见 code/core/src/core-server/utils/new-story-templates/csf-factory-template.ts。

用 satisfies 运算符把校验再收紧一层

基线故事只保证args的类型正确，而“某个必填的 prop 是否遗漏”这类约束，要靠 TypeScript 4.9+ 的satisfies运算符实现。官方文档对应的两个增强片段是 docs/_snippets/button-story-baseline-with-satisfies.md（组件级）与 docs/_snippets/button-story-baseline-with-satisfies-story-level.md（故事级）。

组件级 satisfies

// Button.stories.ts|tsx (通用写法 / React、Vue 3 等) // 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;

// Button.stories.ts (Angular) import type { Meta } from '@storybook/angular'; import { Button } from './button.component'; const meta = { component: Button, } satisfies Meta<Button>; // 👈 Satisfies operator being used for stricter type checking. export default meta;

注意：基础基线片段（button-story-baseline.md）里只有通用（common）写法内置了satisfies，而 Angular 与 Web Components 的基础版本没有。这与 docs/configure/integration/typescript.mdx 故障排查一节 “Thesatisfiesoperator is not working as expected” 的描述一致——由于 Angular 与 Web Components 渲染器的实现约束，Storybook 目前难以判断这两类组件的属性是否必填，因此对它们使用satisfies可能得不到预期效果。

故事级 satisfies

satisfies不止用于 meta，还可以逐条收紧每个故事对象，从而在新增或修改故事时提示是否缺少必填的 arg：

// Button.stories.ts|tsx (通用写法 / React、Vue 3 等) // 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;

// Button.stories.ts (Angular) import type { Meta, StoryObj } from '@storybook/angular'; import { Button } from './button.component'; const meta = { component: Button, } satisfies Meta<Button>; export default meta; type Story = StoryObj<typeof meta>; export const Example = { args: { primary: true, label: 'Button', }, } satisfies Story;

故事级satisfies Story的价值在于：当 Button 组件新增了必填 prop（例如label），所有未显式标注类型、仅靠 satisfies 约束的故事会被编译器标记为缺参，从而把“漏传必填属性”的问题前置到编码阶段。它同时保留字面量类型的精确性，不会把label: 'Button'拓宽为宽泛的string。

三种写法如何取舍

写在最后

回顾 button-story-baseline.md 这短短一组片段，其实浓缩了 Storybook 组件开发三条最重要的心智模型：meta/story 的导出约定、args 与组件输入的编译期绑定、以及meta → story 的类型继承链条（无论走StoryObj<typeof meta>还是 CSF Next 的preview.meta()）。把这段基线吃透后，任何新组件的故事文件都可以从零开始 30 秒搭好，再在其上叠加 decorator、play function 与 tags，逐步演化出 docs/_snippets 目录中button-story-*系列其余更高阶的完整示例。