用 Storybook 构建 UI 组件一条命令从「能跑」到「敢上线」【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook你改了 Button 的一个属性三个页面开始报错设计师问错误态长什么样你只能启动整个应用点四层菜单再截图。Storybook 是 UI 组件隔离开发的工作台把组件从应用里拉出来为每种状态写一个故事测试、文档、分享都在同一个地方完成。先把组件从应用里拉出来三个逼你动手的场景组件改了谁被改崩你给一个输入组件加了新属性只在登录页验证过。两周后才发现注册页、资料页、管理后台都在用它而且各自用了不同的组合方式。组件是全项目的公约数它的测试覆盖却只有一页。设计师要一个按钮你得启动整个应用帮我看下禁用态、带图标、深色背景下的按钮。回答这个问题的成本是启动应用、登录、导航四级菜单、再截图。而对方要的其实只是一个组件的某个状态。新人上手页面根本跑不起来新同事拿到仓库说先跑起来看看。二十分钟后数据库没连上、登录被拦、mock 服务没起。组件代码本身只有几百行它依赖的环境却是整个业务系统。Storybook 工作台左侧故事树右侧是组件画布与源码整个组件库的状态一览无余 从第一条命令到第一个组件故事敲下第一条命令后会发生什么在你的项目目录里运行npx storybooklatest init它是一个交互式向导自动检测你用的是 React、Vue 3、Angular 还是 Svelte问几个问题然后安装依赖、生成.storybook/配置目录并写好 Button、Header、Page 三个示例组件和对应的故事文件。init 之后的 onboarding 向导选框架、选配置剩下的自动生成打开 localhost 后你看到什么然后启动它npm run storybook浏览器自动打开 localhost:6006。左边侧栏是故事树三个示例组件已经挂在那里点开Button / Primary组件就单独渲染在画布里。没有登录、没有路由、没有数据请求这个页面上只有它自己——这是它给你最重要的感觉。改一个属性立刻看到效果故事文件本身是个很普通的对象export default { component: Button }; export const Primary { args: { label: Primary } };第一行叫 meta声明这个文件属于哪个组件第二行是一个故事Primary是故事名args是传给组件的一组参数。保存文件画布热更新不用刷新。⚡️ 建立心智模型故事到底是什么故事是组件的「产品照」一个类比故事就是组件的产品照。每张照片有名字Primary、Disabled、Loading展示一个固定状态照片下方的标签上列着这次用了哪些参数。写故事就是拍照而 Controls 面板让你随时改参数、重拍一张。概念一句话定义对你意味着什么Story组件的一种可渲染状态「悬停超长文本」变成独立可访问的页面args传给组件的参数集在右侧面板改属性不用动代码Controls由 args 生成的 UI改完可以直接存成新故事Docs 页从故事自动生成的文档属性表格和代码永远同步Decorator故事外层的包裹器包一次主题 Provider所有故事都生效故事这个概念在 React、Vue 3、Angular、Svelte、Web Components 里完全一致只是文件后缀和写法不同——换框架不用重新学。Controls 面板args 里定义的 label 变成输入框改完立刻看到画布变化 把 Storybook 推进团队个人、小组、组织三档个人先让一个组件「不崩」挑你最复杂的组件把默认、空数据、错误三类状态写成故事开发时开着 Controls 调状态调出有意思的组合就存为新故事加一条交互测试用 play 函数写点击断言行为坏了 CI 第一时间告诉你小组把故事变成评审准入立一条规矩改组件的 PR 必须带上对应故事更新否则不评审视觉回归和交互测试进 CI组件的每个状态都成为回归基线把 Storybook 链接直接发给 QA 和设计师验收不用启动业务应用交互测试测试步骤逐条打勾失败能精确定位到具体某一步组织把它变成设计系统发布统一实例产品线按版本号锁定组件版本升级有节奏定制主题与品牌色跨团队组件有一个统一入口开启无障碍a11y插件做发布前全量检查合规过程可审计Docs 页属性表、示例和使用说明都由代码生成设计师可直接验收 排掉新手最常踩的三个坑现象、原因、解法为什么 init 完页面是空的现象服务起来了左侧栏一个故事都没有。原因故事靠 glob 匹配发现老项目里组件旁边没有.stories.ts(x)文件它就不会被索引到。解法打开.storybook/main检查stories字段的 glob 是否覆盖你的源码目录然后给组件补一个故事文件。为什么组件样式没了现象应用里组件样式正常故事里却像裸 HTML。原因隔离环境不会自动继承应用的 CSS 构建Tailwind、CSS Modules、主题变量都没被加载。解法让 builder 复用项目的 Vite 或 Webpack 样式配置静态资源路径写进staticDirs。为什么故事突然报 Provider 缺失现象故事里抛出undefined 不可读或主题 Provider 找不到的错误。原因组件依赖上层 Context——主题、路由、登录态应用里天然存在隔离环境里没人提供。解法在preview.tsx里全局加一个 decorator 包上 Provider所有故事一次生效不用逐个改。今天就能做的最小一步打开终端运行npx storybooklatest init十分钟后你就有了自己的组件沙箱。想读源码的话git clone https://gitcode.com/GitHub_Trending/st/storybook【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考