Storybook 快速上手：3 步把 UI 组件变成可演示、可测试的故事

Storybook 快速上手：3 步把 UI 组件变成可演示、可测试的故事

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook

Storybook 是一个 UI 组件开发工具，让你在不启动完整应用的情况下，单独展示、调试和测试前端组件。React、Vue、Angular、Svelte 项目都适用，装完一条命令就能看到所有组件的演示页面。

为什么需要它

先看几个日常场景：

• 想改一个输入框组件，得先启动整个应用、登录、点三层菜单才能看到它。
• 设计师让你改按钮配色，你改完却没法直接给她看效果，只能发截图。
• 改完代码不放心：这个组件还在别处被三种不同用法引用，你不确定改坏没有。

Storybook 把组件放进独立工作区，每个组件状态写成一条"故事"（Story），在浏览器里直接浏览、调参、测试，不用碰应用业务逻辑。

一条命令安装

在项目根目录执行：

npm create storybook@latest

CLI 会检查你的依赖，识别框架后自动生成配置和 Button、Header、Page 三个示例组件。装完运行npm run storybook，本地 6006 端口打开页面，侧边栏已经列好示例故事。

具体版本要求和各包管理器的变体写法，见官方文档 docs/get-started/install.mdx。

核心用法

展示一个组件：写一条故事

故事是一个描述组件某种渲染状态的 JS 对象，放在组件旁的.stories.ts文件里：

import { Button } from './Button'; export default { component: Button }; export const Primary = { args: { label: 'Button', variant: 'primary' }, };

保存后侧边栏出现 Primary 条目，点击即见渲染结果。改代码后页面自动刷新，不用手动重载。

实时演示交互状态：Controls 面板

args里的每个字段都会在右侧 Controls 面板生成对应控件——文本框、数字、开关、颜色选择器。开发时直接改控件值，组件实时响应；调出满意的参数组合后，可以一键存成新的 story，不用改代码。组件的回调事件会被 Actions 面板自动记录，排查点击行为不用写console.log。

自动生成组件文档

Storybook 扫描组件的 TypeScript 类型标注，自动产出属性表和用法示例。配合 MDX（在 Markdown 里嵌入可运行代码块的格式）还能补更长篇的说明，文档和代码在同一个项目里，不存在"文档过期"的问题。

检查响应式与无障碍

顶部工具栏的 Viewport 控件能一键切换常见设备宽度，快速确认断点表现是否符合预期；加上无障碍插件后，每条故事还会跑 Axe 规则检查，把缺失标签、对比度不足这类问题直接标出来。

把故事跑成测试

装上 Vitest 插件后执行npm run test-storybook，每条故事自动变成一个测试用例：真实浏览器里渲染组件、模拟点击、验证输出，还可以接进 CI 在合并前拦截回归。写法详见 docs/writing-tests/index.mdx。

进阶与避坑

故事不显示在侧边栏

现象是.stories.ts写了却刷不出来。原因是文件不在stories配置匹配的目录里，默认只扫src下与组件同级的文件。去.storybook/main配置里核对 glob 路径，把故事文件挪到匹配位置即可。

Controls 认不出参数

现象是args有值，面板里却没有对应控件或类型不对。原因是组件参数缺 TS 类型或 JSDoc 注释，文档生成器推断不出。给参数补上类型标注和说明后控件会自动出现，这也是官方建议把类型写全的一个实际收益，参考 docs/writing-stories/index.mdx。

开发服务和构建产物混淆

npm run storybook是开发服务，npm run build-storybook产出可部署的静态目录，两者在模块解析、部分插件行为上可能不一致。分享或发布时用静态构建，排查问题时先确认自己跑的是哪一个。

适合什么项目

组件库、设计系统、有大量复用组件的业务项目收益最大：故事即文档、即测试。如果你只是做一次性页面、几乎没有独立组件，上它纯属增加维护成本。

下一步

1. 给你的项目装好 Storybook 后，先给最常用的 3~5 个组件各写两条故事，跑通 Controls 调参流程。
2. 装 Vitest 插件并把npm run test-storybook加进 CI。
3. 阅读仓库内 docs/writing-stories/ 下的配置文档，了解 args、decorators 的完整能力。

【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook