如何利用 Storybook 为组件编写文档：提升团队协作效率的工具实战

Storybook天然是组件文档系统，通过DocsPage自动生成属性表与交互预览，MDX支持富文本与嵌入故事，结合Controls、Actions、Viewport实现可操作文档，并按业务逻辑结构化组织提升查找效率。

Storybook 不只是预览组件的工具，它天然就是组件文档系统。用好 DocsPage 和 MDX，能让文档和代码始终同步，团队成员点开就能看效果、改参数、抄代码，协作成本大幅下降。

启用 DocsPage 插件，一键生成基础文档

DocsPage 是 Storybook 官方推荐的文档方案，无需手写 Markdown，它会自动解析组件的 props（TypeScript 接口或 PropTypes）并生成属性表格、使用示例和交互预览。

• 在 .storybook/main.js 中启用插件：
  addons: ['@storybook/addon-docs']
• 确保你的组件故事文件（如 Button.stories.tsx）导出了 component 字段：
  export default { title: 'Components/Button', component: Button };
• 启动 Storybook 后，每个组件故事页右侧会自动出现 “Docs” 标签页，内容即为自动生成文档

用 MDX 编写富文本交互文档

当默认 DocsPage 不够用时（比如需要对比用法、插入设计规范、嵌入多个故事），MDX 是更灵活的选择。它把 Markdown 的易读性和 JSX 的表现力结合在一起。

• 新建 Button.docs.mdx 文件，开头声明元数据：
  <Meta of={ButtonStories} />（注意：of 必须指向故事文件的默认导出）
• 正文用标准 Markdown 写说明，用 <Story of={ButtonStories.Primary} /> 嵌入可交互的故事
• 还能自由插入自定义组件，例如：
  <DoDont><Do><Button size="large">正确尺寸</Button></Do></DoDont>

让文档真正“活”起来：Controls + Actions + Viewport

静态文档容易过时，而 Storybook 文档的核心优势是“可操作”。把文档变成实验沙盒，团队成员能自己调参数、点按钮、切屏幕尺寸，理解立刻加深。

• Controls：在故事中定义 args，文档页自动生成控件面板（颜色选择器、开关、输入框等）
• Actions：添加 onSubmit 或 onClick 等事件监听，点击后在控制台实时看到触发日志
• Viewport：在文档页顶部切换 iPhone、Tablet、Desktop 等尺寸，直接验证响应式行为

结构化组织，降低团队查找成本

文档再好，找不到也白搭。按业务逻辑或 UI 层级组织侧边栏，比堆砌文件名更有效。

• 在 story title 中使用斜杠分组，如：'Forms/LoginForm'、'Layouts/TwoColumn'
• 基础组件（Button、Input）和业务组件（UserProfileCard、OrderSummary）分开归类
• 为高频场景单独建故事，例如：LoginForm/WithValidationErrors、Button/LoadingState