Storybook CSF 3.0 标题体系详解：meta.title、component 自动标题与 story.name 的命名规则

Storybook CSF 3.0 标题体系详解meta.title、component 自动标题与 story.name 的命名规则【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook这篇技术指南聚焦 Storybook Component Story Format 3.0CSF 3.0中的标题title与命名控制机制内容以仓库中面向组件命名示例的代码片段文档为主体并结合其出处——Sidebar URLS 配置文档中的 CSF 3.0 auto-titles 章节展开。读完本文你将掌握如何在 CSF 文件中通过title、component、name精确控制组件与单个 Story 在侧边栏层级与 URL 中的呈现理解 Storybook 自动推导标题auto-title的完整规则并能在 JS/TS/MDX 三种场景中正确写出可运行的标题配置。一、标题机制一览title、component 与 name 三者各自负责什么在 CSF 3.0 中每个.stories文件通过meta默认导出描述组件容器通过命名导出对象描述单个 Story。决定这个组件/这条 Story 在 Storybook 里叫什么、出现在侧边栏哪个位置的核心字段有三个字段作用层级用途titlemeta文件级设置 Story 容器在侧边栏中的完整路径名含/时会产生分组层级例如components/Buttoncomponentmeta文件级关联被测组件当未设置title时Storybook 会根据文件物理路径自动推断标题name单个 Story覆盖该 Story 的显示名称不设置时默认使用导出变量名三者可同时使用并相互配合这也是示例文档要表达的核心自动标题auto-title与显式标题选项完全兼容设置title后你依然可以使用显式的name逐条命名 Story。二、CSF 3.0 meta 的标准写法JS 与 TS 双版本以按钮组件为例示例文档给出了.js/.jsx与.ts/.tsx两种等价写法。JS/JSX 版本对应 src/components/Button/Button.stories.jsimport { Button } from ./Button; export default { // Sets the name for the stories container title: components/Button, // The component name will be used if title is not set component: Button, }; // The story variable name will be used if name is not set const Primary { // Sets the name for that particular story name: Primary, args: { label: Button, }, };TypeScript 版本使用satisfies Metatypeof Button做类型收窄让框架在编译期帮你校验 title/component/args 等字段拼写// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. import type { Meta, StoryObj } from storybook/your-framework; import { Button } from ./Button; const meta { // Sets the name for the stories container title: components/Button, // The component name will be used if title is not set component: Button, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; // The story variable name will be used if name is not set const Primary: Story { // Sets the name for that particular story name: Primary, args: { label: Button, }, };两点实践提醒对应示例中的注释类型导入处的storybook/your-framework是占位符应按实际框架替换例如storybook/react-vite、storybook/nextjs、storybook/vue3-vite等。title是可选的一旦省略Storybook 会根据文件所在位置自动推断标题而component字段仍用于类型推断与文档生成因此建议始终显式写出。注意示例中的对象式Primary是尚未作为命名导出列出的写法若想让 Story 出现在侧边栏仍需通过export const Primary { ... }之类的方式导出CSF 3.0 中常见的是把对象拆出来再export const X { ...Primary }。从仓库中的 CSF 解析实现看meta 中title的取值会被用于生成稳定 storyId 与 URL 中的kind这正是 title 命名在全局唯一的根因详见 get-story-id.ts。三、title 的斜杠语法如何构建侧边栏分组层级示例把 title 写作components/Button其中/是侧边栏的分组分隔符。Storybook 会按共同前缀把带斜杠的 title 归组所有components/...标题下的组件会收进一个名为components的分组文件夹Button成为该分组下的叶子节点。Sidebar URLS 文档给出了两条实操建议顶层节点默认被渲染为 Roots侧边栏的区段更低层分组显示为文件夹如想将顶层节点也折叠成文件夹可在./storybook/manager.js中将sidebar.showRoots设为false。推荐的层级命名尽量镜像组件文件的文件系统路径例如组件在components/modals/Alert.js那么 Stories 文件命名为components/modals/Alert.stories.jstitle 写为Components/Modals/Alert让目录结构、文件名与侧边栏结构一一对应便于长期维护。四、省略 titleStorybook 的自动标题auto-title规则自 Storybook 6.4 引入 CSF 3.0实验性起你可以省略 meta 中的title让 Storybook 依据故事文件的物理位置自动推断标题这正是示例文档出现的上下文。自动标题与title、name等显式配置可以并存、按需混用。自动标题的推断逻辑实现在 autoTitle.ts 中核心函数userOrAutoTitleFromSpecifier的优先级是匹配到 stories 配置项后若存在用户显式title优先用用户 title仅在缺失时才由文件路径推导。该文件还实现了若干重要启发式规则可由对应测试 autoTitle.test.ts 印证保留大小写Storybook 6.5 起不再依赖 LodashstartCase转换components/MyComponent文件会得到components/MyComponent而不是被拆词成My Component文件名大小写被原样保留。去除冗余文件名当文件名与父目录同名如MyComponent/MyComponent.stories.ts或文件名为index.stories.ts时重复段会被剔除——按旧行为Components/MyComponent/MyComponent会简化为Components/MyComponent。相关示例见 storybook-csf-3-auto-title-redundant.md。若需要保留旧命名只需显式给 meta 添加title。剥离后缀与扩展名推导时会去掉.story(s)、文件扩展名以及路径中的分隔冗余sanitize函数与pathJoin实现。titlePrefix 自动前缀若在 stories 配置对象中配置了titlePrefix所有匹配故事无论自动还是显式 title都会加上此前缀测试中的快照如atoms/title与atoms/...直接证明了显式 title 与前缀的拼接行为。需要说明的是自动标题会保留文件系统路径的层级作为侧边栏层级。例如当你的.storybook/main.ts用stories: [../src/**/*.stories.(js|jsx|mjs|ts|tsx)]加载 stories 且文件位于src/components/Button.stories.tsx时该组件在侧边栏会自动显示为components/Button示例文档语境下的components/My Component情形同理。五、story 的 name 与导出变量名谁决定显示名示例中PrimaryStory 同时设置了export const变量名与name: Primary。二者的分工在 Sidebar URLS 文档中被明确表述Storybook will prioritize theidover the title for ID generation if provided and prioritize thestory.nameover the export key for display.即侧边栏与 Docs 中的显示名以story.name为准未设置时才退化为导出变量名。因此当你要把导出变量名留作代码内引用、却想让读者看到更友好的标题时例如含空格、中文或长描述就给 Story 设置name。相应地story 显示名的修改会自动参与 URL 与 permalink 的生成。六、从 title 到 URLstoryId 的生成规则title 不只影响观感还会决定每个 Story 的稳定 ID 与可分享 URL。默认规则是Storybook 依据组件 title 故事名生成 ID例如 title 为foo/bar、导出名为baz的故事会得到 IDfoo-bar--baz对应链接形如?path/story/foo-bar--baz见 Sidebar URLS 文档。若需要在不破坏既有 permalink 的前提下调整层级或显示名可手动为 meta/Story 提供稳定的idid优先级高于 title这在发布型 Storybook 中尤其重要。整体调用链在仓库中可见于 get-story-id.ts先通过getStoryTitle拿到自动或用户title再由storyNameFromExport归一化故事名最终toId(autoTitle, storyName)产出 storyIdtitle 经sanitize归一化为 URL 友好的kind。七、MDX 文档页里的 Meta/Story文档页标题与组件页引用在.mdx文档文件中同样使用标题体系组织页面。示例文档给出了Button.mdx的用法注意其中的 import 写法为示例使用方式来自 storybook/addon-docs/blocksimport { Meta, Story } from storybook/addon-docs/blocks; {/* Documentation-only page */} Meta titleDocumentation / {/* Component documentation page */} import * as ButtonStories from ./Button.stories; Meta of{ButtonStories} / Story of{ButtonStories.Primary} /该示例同时展示三种常见形态纯文档页documentation-only page通过Meta titleDocumentation /显式命名一个不含组件渲染的文档页面title 决定其在侧边栏中的层级归属。组件文档页Meta of{ButtonStories} /引用同目录下Button.stories模块的全部导出让该 MDX 页与 CSF 中定义的组件及标题自动关联。渲染指定故事Story of{ButtonStories.Primary} /基于of语法按引用渲染Primary这条 Story无需手动复制 args 配置。由此可以总结出贯穿 JS/TS/MDX 的统一心智模型CSF 文件是单一事实来源title/自动标题决定容器归属name/导出名决定故事显示名Meta/Story的of引用则让文档页复用这套命名体系从而保持侧边栏、URL、文档三处命名一致。八、小结何时显式 title何时交给自动标题侧边栏需要精确层级、需按业务模块而非目录组织、或目录路径与展示名不一致时在 meta 中显式声明title配合/分隔这是最可控的方案目录结构合理、希望移动文件即自动重命名时省略title依赖文件路径自动推断并用titlePrefix统一打前缀无论哪种方案都可以给单条 Story 设置name控制显示名并牢记只有显式title缺失时自动推断才会生效component字段与命名无关却对类型安全与文档自动生成至关重要。上述所有规则均可回到仓库中的示例片段、侧边栏配置文档以及 autoTitle.ts、get-story-id.ts 及其测试处进一步验证是理解 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），仅供参考