CSF 格式（Component Story Format）

• 默认导出为组件元信息——包括 title、component、args 和 decorators
• 具名导出即为故事（story）——每个导出都会在侧边栏中生成一个独立的故事
• 使用 satisfies Meta 实现 TypeScript 类型检查
• CSF3 采用对象语法而非函数语法——例如：export const Primary = { args: {...} }

Args 与 ArgTypes

• args 是实际传入组件的属性值——例如：args: { label: 'Click me' }
• argTypes 用于配置 Controls 面板中的 UI 控件——例如：argTypes: { size: { control: 'select', options: ['sm', 'lg'] } }
• 元信息（meta）中定义的默认 args 将应用于所有故事，可在单个故事中覆盖
• argTypes: { onClick: { action: 'clicked' } } 可在 Actions 面板中自动记录事件

Controls

• 自动从 TypeScript 的 props 类型推断控件类型——boolean 类型对应开关控件，string 类型对应文本输入框
• 可手动覆盖控件类型：argTypes: { color: { control: 'color' } }
• 禁用某项控件：argTypes: { children: { control: false } }
• 下拉选择控件的选项配置：control: { type: 'select' }, options: ['a', 'b', 'c']

Decorators

• 用于为故事包裹上下文——如 Provider、布局包装器、主题等
• 组件级装饰器定义在 meta 中：decorators: [(Story) => ]
• 全局装饰器定义在 .storybook/preview.js 中——作用于全部故事
• 装饰器执行顺序重要——后声明的装饰器会包裹先声明的装饰器

Play Functions

• 在故事内进行交互式测试：play: async ({ canvasElement }) => {...}
• 使用 @storybook/testing-library 进行 DOM 查询——例如：within(canvasElement).getByRole()
• 使用 await userEvent.click(button) 模拟用户交互
• 使用 expect(element).toBeVisible() 执行断言——测试运行于浏览器环境中

Actions

• argTypes: { onClick: { action: 'clicked' } } 可自动将事件日志输出至 Actions 面板
• 也可显式导入：import { action } from '@storybook/addon-actions'
• 在 Storybook 8+ 中，可在 play 函数中使用 @storybook/test 提供的 fn() 进行事件监听（spying）
• Actions 可帮助验证事件处理器逻辑，无需手动添加 console.log

故事组织方式

• 标题路径决定层级结构——例如：title: 'Components/Forms/Button'
• 故事在侧边栏中按导出顺序排列——建议将 Primary 放在首位
• tags: ['autodocs'] 可自动生成文档页面
• parameters: { docs: { description: { story: 'text' } } } 可为故事添加描述文本

常见模式

• 默认状态：export const Default = {}
• 包含全部属性：export const WithIcon = { args: { icon: } }
• 边界情况：Empty、Loading、Error、Disabled 等状态应作为独立故事分别编写
• 响应式设计：可为每个故事单独配置 viewport addon 参数

Render Functions

• 自定义渲染逻辑：render: (args) =>
• 在 render 函数中访问上下文：render: (args, { globals }) => ...
• 适用于需要与默认 JSX 结构不同的场景
• 推荐使用 decorators 实现“包裹”，使用 render 实现“重构”

配置

• .storybook/main.js：配置插件（addons）、框架（framework）、stories 匹配规则（glob patterns）等
• .storybook/preview.js：配置全局 decorators、parameters 和 argTypes
• Stories 匹配规则：stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)']
• 静态资源目录：staticDirs: ['../public']——用于托管图片、字体等资源

常见错误

• 忘记安装插件（addon）并将其加入 main.js 的 addons 数组中
• 仍在使用已废弃的 storiesOf API——请改用 CSF 导出方式
• 元信息（meta）中缺失 component 字段——导致 Controls 无法自动推导
• Decorators 返回 Story 时未调用它——应写为 (Story) => ，而非 (Story) => Story