组件文档站和 Storybook 在前端工程化中有什么价值？

简化版

组件文档站和 Storybook 用来展示组件 API、交互状态、设计规范和使用示例，让组件可以脱离业务页面独立开发、测试和评审。它们能提升复用效率，也能承载视觉回归、可访问性检查和设计协作。

详细版

价值：

• 独立展示组件不同状态。
• 记录 props、事件、插槽和用法。
• 方便设计、产品、前端一起评审。
• 支持视觉回归测试。
• 支持组件驱动开发。
• 降低业务方接入成本。

注意点：

• 示例必须真实可运行。
• 文档要跟版本一起发布。
• 不要只写 happy path，边界状态也要展示。
• API 文档、设计规范和变更记录要保持同步。

完整版教学

一、组件没有文档就很难复用

组件库的目标是复用，但复用的前提是别人知道怎么用。没有文档时，业务方只能翻源码、问作者、复制旧代码。久而久之，组件库会变成“看起来有，实际没人敢用”的仓库。

文档站把组件的能力、约束、示例和设计意图展示出来。Storybook 这类工具则让组件在独立环境中运行，便于开发和调试。

组件源码
  → Story/示例
  → 文档站
  → 业务方理解和复用

二、Story 是组件状态样本

一个组件不只有默认状态。Button 有 primary、disabled、loading、danger；Table 有空数据、加载中、超长文本、分页；Modal 有确认、取消、嵌套内容。Story 把这些状态显式保存下来。

数字例子：一个表单组件有 6 种字段状态、3 种校验状态、2 种布局，组合可能达到 6 × 3 × 2 = 36 种。虽然不一定全展示，但关键边界必须有样本，否则业务上线才发现样式炸了。

Story 类型	示例	价值
基础状态	默认按钮	快速理解
边界状态	超长文本	防布局问题
交互状态	loading	验证行为
错误状态	校验失败	覆盖异常

三、文档要说明 API 和设计意图

只展示组件长什么样还不够。文档应说明 props、事件、插槽、主题 token、无障碍注意点和使用禁忌。比如 Button 什么时候用 primary，什么时候用 danger，loading 时是否自动禁用。

API 文档可以自动从 TypeScript 类型生成，但设计意图需要人工维护。否则文档会变成参数表，无法指导正确使用。

四、独立开发能减少业务干扰

组件在业务页面里开发，容易受接口、路由、权限、布局影响。Storybook 提供独立沙箱，开发者可以只关注组件状态。设计师也能直接看组件各种状态，不必等业务流程跑通。

这对复杂组件很有价值。比如日期范围选择器，可以在 Story 中模拟禁用日期、快捷选项、错误状态，而不需要进入某个复杂报表页面。

五、文档站可以接入自动化测试

Story 不只是展示，也可以成为测试输入。视觉回归工具可以截图对比 Story，交互测试可以点击 Story 中的按钮，可访问性插件可以检查 aria 和对比度。这样组件变更的影响更容易被发现。

Story
  ├─ 人看：文档和评审
  ├─ 机器看：截图回归
  └─ 测试看：交互和可访问性

六、文档要和版本绑定

组件库升级后，文档必须对应当前版本。用户使用 @ui/button@1.5.0，却看到了 2.0 文档，会导致 API 对不上。成熟组件库会让文档站和版本发布流程绑定，至少 changelog 要清楚。

记忆钩子：Storybook 不是“组件展览馆”，而是组件的样本库、测试入口和协作界面。

七、常见误区与追问

• 误区：组件写了 TypeScript 类型就不需要文档。 类型说明参数，文档说明场景、边界和设计意图。
• 误区：Story 只要默认状态即可。 边界、错误、加载、禁用等状态更能暴露问题。
• 误区：文档站只是给新人看的。 它也是设计评审、视觉回归和组件治理入口。
• 追问：Storybook 如何帮助测试？ Story 可作为视觉回归、交互测试和可访问性检查的输入。
• 追问：文档如何保持更新？ API 可自动生成，示例和设计说明跟随 PR review 与版本发布。
• 追问：组件库没有文档有什么后果？ 使用成本高、重复造轮子、错误用法扩散、组件作者成为人工客服。

八、加强记忆

组件文档站用“能看、能试、能测、能追版本”来记。Story 展示组件各种状态，文档解释 API 和设计意图，自动化测试复用 Story，版本发布同步文档。它让组件库从代码仓库变成真正可用的产品。