Storybook：构建更优秀的 UI 文档

组件文档往往在编写完成的那一刻就开始过时。开发者更新代码，设计师调整界面，但文档却在 wiki 和 markdown 文件中日渐陈旧。Storybook 通过将组件故事转化为与实际 UI 组件保持同步的活文档来解决这一问题。

Storybook UI 文档的独特之处

传统文档将代码与其说明分离。Storybook 将它们融合在一起。每个组件故事都成为一个实时的交互式示例，开发者和设计师可以实时探索、修改和理解。

神奇之处在于 Autodocs——Storybook 的自动文档生成器。当你为组件编写故事时，Storybook 会提取 props、控件和使用模式，无需额外努力即可创建全面的文档页面。

为组件设置 Autodocs

通过在 Storybook 配置中添加一个标签来启用自动文档生成：

// .storybook/preview.js
export default {
  tags: ['autodocs']
}

对于单个组件，可以在故事文件中控制文档生成：

// Button.stories.js
export default {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'] // 为此组件生成文档
}

这个简单的设置会创建显示以下内容的文档页面：

• 组件描述和用法
• 交互式属性控件
• 源代码示例
• 所有故事变体

使用 MDX 和 Doc Blocks 自定义文档

虽然 Autodocs 提供了优秀的默认设置，但实际项目中的组件需要上下文说明。MDX 文件让你将 markdown 文档与实时组件示例结合：

import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
import { Button } from './Button';

<Meta title="Components/Button" component={Button} />

# Button 组件

我们的按钮组件支持多种变体和状态。

## 交互式示例

<Canvas>
  <Story name="Primary">
    <Button variant="primary">点击我</Button>
  </Story>
</Canvas>

## 属性

<Controls />

## 使用指南

主要操作使用主按钮，次要操作使用次按钮。

Doc Blocks 为文档提供构建模块：

• Canvas：显示带有源代码的故事
• Controls：交互式属性表
• Story：嵌入特定的故事示例
• ArgTypes：记录组件属性

使用 Controls 扩展文档

Storybook Controls 将静态文档转换为交互式演练场。在故事中定义控件：

export default {
  title: 'Components/Card',
  component: Card,
  argTypes: {
    variant: {
      control: 'select',
      options: ['default', 'highlighted', 'muted'],
      description: '视觉样式变体'
    },
    padding: {
      control: { type: 'range', min: 0, max: 50 },
      description: '内边距（像素）'
    }
  }
}

这些控件会自动出现在文档中，让用户可以尝试不同的属性组合并即时查看结果。

组织故事以获得清晰的文档

构建故事来讲述组件的完整故事：

// Card.stories.js
export default {
  title: 'Components/Card',
  component: Card
}

// 基本用法
export const Default = {}

// 常见模式
export const WithImage = {
  args: { image: '/placeholder.jpg' }
}

// 边界情况
export const LongContent = {
  args: { 
    content: '可能会换行的很长文本内容...' 
  }
}

// 组合示例
export const InGrid = {
  render: () => (
    <div className="grid">
      <Card />
      <Card />
      <Card />
    </div>
  )
}

使用文件夹对相关组件进行分组：

• Components/Forms/Input
• Components/Forms/Select
• Components/Layout/Grid

创建单一数据源

Storybook 在设计和开发团队之间架起桥梁。设计师可以在不深入代码的情况下审查已实现的组件。开发者通过交互式示例了解设计意图。

关键协作功能：

• 设计令牌：记录颜色、间距和排版
• 组件状态：显示悬停、激活、禁用变体
• 响应式行为：展示移动端和桌面端视图
• 无障碍注释：包含 ARIA 标签和键盘导航

与设计工具的集成加强了这种连接。Storybook Design 插件直接在文档中嵌入 Figma 文件。Figma 插件将故事带入设计文件。

活文档的最佳实践

1. 先写故事：在构建组件时创建故事，而不是之后
2. 记录边界情况：包括错误状态、空状态和加载状态
3. 添加使用说明：解释何时以及为什么使用每个变体
4. 保持故事专注：一个故事应该演示一个概念
5. 使用有意义的名称：PrimaryLargeButton 比 Story1 更好

为较长的文档配置目录：

// .storybook/preview.js
export default {
  parameters: {
    docs: {
      toc: {
        headingSelector: 'h2, h3',
        title: '本页内容'
      }
    }
  }
}

结论

Storybook 将 UI 文档从繁重任务转变为开发的自然组成部分。通过故事、控件和 MDX 定制，你的组件变得自文档化。当文档与代码共存，随着组件演进自动更新时，团队可以更快地交付产品。从 Autodocs 开始，在需要时使用 MDX 增强，看着你的设计系统文档焕发生机。

常见问题

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.