Backstage Storybook 贡献指南从组件探索到新增 Story 的完整实战【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 的 Storybook 是开发者门户组件体系的“活目录”它以可视化的方式集中展示了backstage/core-components中的可复用 UI 元素按钮、表格、进度条、状态面板等并附带可直接复制的示例代码。本文基于仓库中的 contributing-to-storybook.md 展开结合 Storybook 配置文件与真实组件源码带你掌握如何理解 Backstage 组件与 Material UI 的关系、如何新增一个标准.stories.tsx文件、如何在本机启动 Storybook 进行预览与调试。Backstage Storybook 是什么Backstage 的 Storybook 提供了一种探索 Backstage 可复用 UI 元素及其在 Backstage 核心与插件开发中使用方式的途径。这些 UI 元素通常被称为“组件”components包括按钮、表格、具有特定格式的专用小部件等。在线实例位于http://backstage.io/storybook。如设计总览所述Backstage 的设计体系建立在 Material UImaterial-ui/core之上。因此大量 UI 元素直接使用 Material UI 组件Storybook 中会出现直接演示这些基础组件的 Story同时 Backstage 也扩展并编写了自定义组件用于提供特定功能。当 Backstage 自定义组件被创建后它们会被放入backstage/core-components包并同步添加到 Storybook。仓库中 packages/core-components/src/components 目录下的组件基本都配有一个同名的.stories.tsx文件例如Progress、Avatar、Chip、CodeSnippet、CopyTextButton、EmptyState、Status、LogViewer等这正是“组件与 Story 一一对应”的体现。何时需要新增自定义组件在某些情况下现有的 Material UI 组件已经足够无需包装或重复造轮子。但如果 Backstage 需要为某个组件确立一种“有观点”opinionated的用法Storybook 中同样会加入演示这些既有 Material UI 组件用法的 Story。当某个基于 Material UI 的 Story 示例变得越来越复杂需要一组特定的颜色、变体、参数等时它就具备了被重构为完整 Backstage 核心组件的候选资格。也就是说演进路径是先用 Story 沉淀某种 Material UI 组件的特定用法当这种用法复杂度上升、复用价值凸显时将其提炼为backstage/core-components中的正式组件新的组件再以独立的.stories.tsx继续沉淀更多使用示例。创建新的 Story一个 Story 本质上代表组件的一个可视化状态。创建新 Story 的方式非常轻量在你要文档化的组件旁边新建一个与组件同名的文件。以Progress组件为例标准的目录结构如下core └── src └── components └── Progress ├── Progress.tsx └── Progress.stories.tsx文件名必须遵循componentName.stories.tsx的格式Storybook 配置正是通过src/**/*.stories.(js|jsx|mjs|ts|tsx)这个 glob 模式见 .storybook/main.ts来自动收集所有 Story 文件的。一个真实的最小 Story 示例以 Progress.stories.tsx 为例它完整展示了 Story 文件的标准结构import { Progress } from ./Progress; export default { title: Feedback/Progress, component: Progress, tags: [!manifest], }; export const progress () Progress /;关键要素说明default export定义 Story 的元信息。title决定其在 Storybook 侧边栏中的分组与展示层级Feedback/Progress表示位于 “Feedback” 分组下component指向被演示的组件本身tags: [!manifest]用于将该 Story 排除在“manifest”汇总类 Story 之外可对照 preview.tsx 中tags: [manifest]的全局配置理解其配对关系命名导出named export每个导出就是一个独立的 Story代表组件的一个可视化状态。例如CopyTextButton的 CopyTextButton.stories.tsx 一口气导出了Default、WithTooltip、LongerTooltipDelay、WithAriaLabel四个 Story分别演示默认行为、自定义提示文本、自定义提示延迟tooltipDelay{3000}以及无障碍标签aria-label四种状态多状态演示EmptyState.stories.tsx 则演示了missing参数的info、content、data、field等不同取值以及自定义图片customImage和带操作按钮action的状态是“一个组件多个 Story 状态”的典型范本。这种设计让读者既能直观看到组件长什么样又能直接复制示例代码到自己的插件中使用。组件源码如何支撑 Story以Progress组件本身Progress.tsx为例可以观察到 Backstage 包装 Material UI 组件的典型模式它基于material-ui/core/LinearProgress二次封装通过useTheme()读取主题过渡时长在组件挂载后延迟一小段时间才显示进度条避免页面加载闪烁同时提供默认的aria-label默认值Loading与data-testidprogress保证无障碍与可测试性。这正是前面提到的“包装 Material UI 组件以提供 Backstage 特定行为”的源码级佐证——写 Story 时可以顺着组件的 props 逐一生成演示状态。在本地运行 Storybook要本地预览 Storybook进入仓库根目录storybook所在位置先安装依赖yarn install然后启动开发服务器yarn storybook该命令在 package.json 中定义为storybook dev -p 6006即启动开发模式并固定监听6006端口。看到类似下图的启动日志即表示成功启动成功后在浏览器中访问http://localhost:6006/即可浏览并查看 Storybook 页面中的所有组件与示例。其他相关脚本package.json 中还提供了两个与之配套的构建脚本build-storybook执行storybook build --output-dir dist-storybook将 Storybook 构建为静态站点输出到dist-storybook目录可用于部署到静态托管或 CI 预览build-storybook:chromatic通过STORYBOOK_STORY_SETchromatic环境变量只收集指定 Story 集合见下文并生成--stats-json统计信息供 Chromatic 视觉回归测试使用。深入源码Storybook 是如何组织起来的理解.storybook目录下的配置可以让你新增的 Story 被正确收集与渲染。收集哪些包.storybook/main.ts.storybook/main.ts 中Story 的收集范围分为两种情况全量开发模式默认收集packages/ui、packages/core-components、packages/app、plugins/app、plugins/org、plugins/search、plugins/search-react、plugins/home、plugins/catalog-react共 9 个包的 StoryChromatic 模式设置环境变量STORYBOOK_STORY_SETchromatic只收集packages/ui与plugins/app用于控制视觉回归测试的范围与速度。配置还声明了这些 addonstorybook/addon-linksStory 间跳转、storybook/addon-themes主题切换、storybook/addon-docs文档化渲染、storybook/addon-a11y无障碍检查、storybook/addon-vitest组件测试与storybook/addon-mcp。框架采用storybook/react-vite并通过viteFinal为浏览器环境补充process、util、buffer、stream等 Node.js polyfill保证依赖 Node 全局 API 的组件在浏览器中正常渲染——这是在 Vite 迁移后保证 Storybook 可运行的关键工程细节。全局渲染环境.storybook/preview.tsx.storybook/preview.tsx 通过definePreview配置了所有 Story 共享的渲染环境主题体系提供themeModelight/dark与themeNamebackstage/spotify两个全局工具栏选项并通过UnifiedThemeProvider包裹每个 Story同时利用appThemeApi同步当前激活主题视口预设内置了从 320pxinitial到 1536pxxl共 6 档视口便于验证组件在不同屏幕尺寸下的表现无障碍检测addonA11y配置为test: todo模式将无障碍违规项显示在测试 UI 中而不阻塞 CI容器与装饰器通过TestApiProvider注入 Backstage 测试用 API并挂载AlertDisplay使依赖 Backstage 上下文的组件也能在 Story 中正常运行。因此新增 Story 时无需关心主题、API 注入等问题——这些都由全局 decorator 统一处理你只需要专注写出组件的各个可视化状态即可。总结为 Backstage 贡献 Story 的完整路径可以概括为在backstage/core-components或受支持的插件包中定位或新增目标组件在组件同目录下创建componentName.stories.tsx用title/component声明元信息用命名导出定义组件的各个可视化状态在仓库根目录运行yarn install yarn storybook在http://localhost:6006/预览效果提交后Story 会被 .storybook/main.ts 的 glob 自动收集并受益于 .storybook/preview.tsx 提供的主题、视口、无障碍等全局能力。遵循这套流程你的组件不仅会被 Backstage 开发者社区看到还能成为整个设计系统中可复用的官方参考资料让插件开发者少走弯路、保持体验一致。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考