StoryBook Stories

一句话定义

Story 是 UI 组件在特定参数组合下的独立渲染快照，用于在隔离环境中开发、展示和测试组件的各状态。

核心机制 / 工作原理

Storybook 将每个组件的每种状态封装为一个”Story”。Story 本质上是一个函数，返回组件在给定 props/args 下的渲染结果。Storybook 读取这些 Story，将其渲染在独立的 iframe 中，开发者可以在浏览器中逐个查看和交互。

Story 文件结构（CSF 格式）

CSF（Component Story Format）是 Storybook 推荐的标准文件格式：

// Button.stories.jsx
export default {
  title: 'Components/Button',  // 侧边栏路径
  component: Button,            // 关联的组件
  tags: ['autodocs'],           // 自动生成文档
  argTypes: {
    variant: { control: 'select', options: ['primary', 'secondary'] },
  },
};

// 每个 named export 就是一个 Story
export const Primary = {
  args: {
    label: 'Button',
    variant: 'primary',
  },
};

export const Disabled = {
  args: {
    label: 'Button',
    variant: 'primary',
    disabled: true,
  },
};

关键概念

• Default export：定义组件的元信息（title、component、decorators、argTypes）。
• Named export：每个命名导出对应一个 Story，即组件的一种状态。
• args：传给组件的 props，可在 Storybook Controls 面板中实时调整。
• argTypes：定义 args 的类型、控件样式（slider、select、color 等）和描述。
• Decorators：包装组件的高阶函数，用于提供上下文（ThemeProvider、Router 等）。

// Decorator 示例
export default {
  decorators: [
    (Story) => (
      <div style={{ padding: '2rem' }}>
        <Story />
      </div>
    ),
  ],
};

Stories 的三重用途

1. 开发环境：隔离开发组件，不依赖应用路由和数据。
2. 文档：配合 autodocs 自动生成组件 API 文档，Story 即文档。
3. 视觉测试：配合 Chromatic 等工具做截图回归测试，检测 UI 变化。

CSF 2 vs CSF 3

• CSF 2：Story 是函数 Primary = (args) => <Button {...args} />
• CSF 3（当前推荐）：Story 是对象 { args: { ... } }，更声明式，与 TypeScript 兼容更好。

最小例子

// 最简 Story —— 一个按钮的默认状态
export default {
  title: 'UI/Input',
  component: Input,
};

export const Default = {
  args: { placeholder: 'Type here...' },
};

边界与常见误解

• Story 不是测试用例，虽然可以驱动测试，但它的主要目的是展示和开发。
• Story 不等于组件文档本身，但 autodocs 可以从 Story 自动生成文档。
• args 不等于组件的完整 API，有些内部状态不适合通过 args 暴露。
• CSF 文件中的 default export 是必须的，缺少会导致 Storybook 无法识别。

Related notes

• Storybook
• React
• [[component-driven-development|组件驱动开发]]