Storybook storySort 配置对象完全指南用 method、order、locales 精确控制侧边栏故事排序【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook 默认按故事文件的导入顺序在侧边栏展示故事但在大型组件库中我们往往需要把 Intro、设计规范、页面级故事等按业务优先级排列。本文以 Storybook 仓库中 storybook-preview-empty-sort-object.md 片段为骨架系统讲解parameters.options.storySort配置对象method、order、locales、includeNames四个字段的完整语义并结合 storySort.ts 源码逐行拆解其排序算法让你既能照着配置立即上手也能理解底层为什么这样排序。storySort 是什么侧边栏排序的入口Storybook 的侧边栏层级Category → Folder → Component → Docs → Story由每个故事的title用/分隔符组织而成详见 naming-components-and-hierarchy.mdx。默认情况下Storybook 按照故事被导入的先后顺序排列即configure()的导入顺序。当你想打破这种文件系统顺序例如把Intro置顶、把WIP排到最后就需要在.storybook/preview.js或.ts中通过parameters.options.storySort覆盖排序策略。storySort有两种形态对应类型Addon_StorySortParameterV7定义见 addons.ts配置对象Object{ method, order, locales, includeNames }即本文主题比较函数Comparator(a, b) number形式完全自定义见 storybook-preview-sort-function.md。配置对象的空骨架从零开始的模板官方文档给出的最小骨架如下完整见 storybook-preview-empty-sort-object.md三个字段全部以空值占位方便你在此基础上按需填充// .storybook/preview.js|jsx export default { parameters: { options: { storySort: { method: , // 留空等价于默认 configure order: [], // 空数组等价于不指定任何显式顺序 locales: , // 留空则使用系统区域设置 }, }, }, };TypeScript 形态需要把your-framework替换为你实际使用的框架如react-vite、nextjs、vue3-vite等// .storybook/preview.ts|tsx import type { Preview } from storybook/your-framework; const preview: Preview { parameters: { options: { storySort: { method: , order: [], locales: , }, }, }, }; export default preview;字段总览表字段类型说明必填默认值示例methodString决定故事的展示顺序策略否Storybook 配置顺序configurealphabeticalorderArray按给定名称显式排列故事否空数组[][Intro, Components]includeNamesBoolean是否把故事名称纳入排序计算否falsetruelocalesString排序时使用的区域设置否系统区域en-US四个字段的完整类型定义可在 addons.ts 中找到Addon_StorySortMethod configure | alphabeticalorder是any[]locales是字符串includeNames是布尔值。关于空对象的语义从 storySort.ts 源码可以看到空值都会被兜底逻辑接管method为空 → 使用options.method || configure兜底为configure即维持导入顺序order为空 → 使用options.order || []兜底为空数组即不匹配任何名称、也不含通配符所有故事都走默认策略。所以空骨架 只填你需要的一个字段是完全合法且推荐的用法它既是占位模板也是理解各字段默认行为的起点。methodconfigure 与 alphabetical 两种排序策略method决定当故事名称不在order列表中时如何排列。configure默认保持 Storybook 配置文件导入顺序。源码中对应 storySort.ts// Use the default configure() order. if (method configure) { return 0; }alphabetical按字母顺序排序并支持locales。源码对应 storySort.tsreturn nameA.localeCompare(nameB, options.locales ? options.locales : undefined, { numeric: true, sensitivity: accent, });注意两个细节numeric: true让Story 2排在Story 10之前数字按数值而非字符比较sensitivity: accent让重音符号参与比较如é与e视为不同。locales直接透传给localeCompare的第二个参数因此支持en-US、zh-CN、ja等任意 BCP 47 区域标签。// .storybook/preview.js export default { parameters: { options: { storySort: { method: alphabetical, locales: en-US, }, }, }, };order用显式名称列表锁定排序位置order是最常用的字段。它是一个字符串数组按数组顺序排列故事分类没有出现在order列表中的故事会被排到列表末尾。// .storybook/preview.js export default { parameters: { options: { storySort: { order: [Intro, Pages, [Home, Login, Admin], Components], }, }, }, };嵌套数组二级排序order支持嵌套数组来细化二级分类的排序。上面示例产生的顺序是Intro及Intro/*下的故事Pages故事Pages/Home及Pages/Home/*故事Pages/Login及Pages/Login/*故事Pages/Admin及Pages/Admin/*故事Pages/*下的其余故事Components及Components/*故事所有其他故事嵌套数组在源码中由 storySort.ts 实现当进入下一层标题段时若当前名称在order中对应的下一项是数组则把该数组作为下一层的orderlet index order.indexOf(nameA); if (index -1) { index order.indexOf(*); } order index ! -1 Array.isArray(order[index 1]) ? order[index 1] : [];这意味着每层标题都可以独立指定显式顺序 其余兜底非常适合Pages/Home、Pages/Login、Pages/Admin这类同前缀多页面的场景。通配符*指定其余故事的位置默认未匹配的故事排末尾如果你想在中间插入一个兜底位置可以用*标注所有其他故事应出现的位置// .storybook/preview.js export default { parameters: { options: { storySort: { order: [Intro, Pages, [Home, Login, Admin], Components, *, WIP], }, }, }, };此时WIP分类会被排到*之后、即整个列表的末尾。源码中通配符逻辑位于 storySort.ts未命中的名称若存在通配符则插入通配符位置否则取order.length末尾。注意order与method是独立生效的。故事先按order数组排序order无法决策的部分再由method: alphabetical或默认的configure()导入顺序决定见 naming-components-and-hierarchy.mdx 末尾的说明。locales多语言环境下的字母排序locales只作用于method: alphabetical场景为localeCompare提供区域上下文。不同语言对字符排序的规则差异很大例如德语ö的排序位置、中文的拼音排序显式指定locales可以保证排序结果与你的用户语言环境一致// 德语环境按德语规则排序 storySort: { method: alphabetical, locales: de-DE }如果不传则使用运行 Storybook 的浏览器/Node 环境默认区域源码中为options.locales ? options.locales : undefined。includeNames把故事名也纳入排序默认情况下同一title同一组件下的多个故事保持它们在故事文件中的定义顺序——这是 storySort.ts 的快速通道// If the two stories have the same story kind, then use the default ordering if (a.title b.title !options.includeNames) { return 0; }当你希望同一组件下的故事名也参与排序时设置includeNames: true。此时排序器会把故事名追加到标题层级之后一起比较storySort.tsif (options.includeNames) { storyTitleA.push(a.name); storyTitleB.push(b.name); }典型应用配合method: alphabetical让一个组件下Button/Primary、Button/Secondary等故事按名称字母排序而不是依赖文件内的书写顺序。源码原理storySort 算法逐段拆解完整的排序实现位于 storySort.ts核心算法如下同 title 短路若两个故事title相同且未开启includeNames返回0保持定义顺序标题分段用正则/\s*\/\s*/把title按/拆分容忍/两侧的空格若开启includeNames则把a.name追加进分段数组逐层比较while (storyTitleA[depth] || storyTitleB[depth])逐段比较——深度更短层级更浅的故事优先storySort.tsorder 命中检测同一层名称不同时在order数组中查找两者的索引只要有一个命中就按索引排序未命中的落到通配符位置或末尾未命中兜底两个都不在order中时method configure返回0保持导入序否则走localeCompare字母序层级下沉进入下一层时按上文所述切换到嵌套order数组。类型层面排序器接收的输入是IndexEntry含id、title、name、importPath等字段比较函数签名(a, b) number与 JavaScript 原生Array.prototype.sort完全兼容。调用链排序发生在 Story Index 构建阶段storySort并非运行时渲染时才生效而是在 Story Index故事索引构建阶段完成的。调用链位于 sortStories.tssortStoriesCommon判断storySortParameter是否存在是函数则直接用是对象则调用storySort(storySortParameter)生成比较器sortStories.ts未配置 storySort 时按fileNameOrder文件导入顺序排序配置了 storySort 时用生成的比较器对stories.sort()排序sortStoriesV7包裹了错误处理排序抛错时会提示 Are you using a V6-style sort function in V7 mode?sortStories.ts并指引参考MIGRATION.md。此外CSF 解析阶段还有 getStorySortParameter.ts 负责从preview配置中提取storySort参数含对应测试 getStorySortParameter.test.ts排序算法本身也有独立单元测试 storySort.test.ts覆盖configure/alphabetical、order嵌套数组、通配符、includeNames、locales等组合场景可作为行为契约参考。对比配置对象 vs 自定义排序函数当配置对象无法表达你的排序规则时可以直接传比较函数见 storybook-preview-sort-function.md// .storybook/preview.js export default { parameters: { options: { storySort: (a, b) a.id b.id ? 0 : a.id.localeCompare(b.id, undefined, { numeric: true }), }, }, };两者取舍配置对象声明式、可读性强覆盖 90% 的置顶/排序/兜底需求无需关心算法细节比较函数完全可控可基于id、title、name、importPathIndexEntry字段任意组合适合按 importPath 排除某些文件按故事名长度等非常规需求。常见问题与排查建议配置了 storySort 但顺序没变化检查是否把storySort放在了parameters.options下而非parameters顶层确认文件名是.storybook/preview.js|tsStorybook 启动时加载的全局配置文件。未匹配的故事位置不对未出现在order中的分类默认排在末尾如需插入中间位置请使用*通配符。同一组件内故事顺序不受order控制order匹配的是title层级要排序同组件内的故事名设置includeNames: true。V6 风格的函数签名报错V7 模式下比较函数接收的是IndexEntry对象而非旧的数组元组报错信息会明确提示可参考MIGRATION.md。中文字符串排序结果奇怪显式指定locales: zh-CN并确认method: alphabetical否则会依赖运行环境默认区域。小结storySort配置对象用四个字段覆盖了侧边栏排序的完整需求method决定策略导入序/字母序、order决定显式位置含嵌套数组与通配符、locales决定多语言字母序规则、includeNames决定是否细化到故事名一级。理解其底层算法storySort.ts与调用链sortStories.ts之后你就能精准预测任何配置组合下的侧边栏结果为团队打造文档置顶、WIP 沉底、页面分级的高质量 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），仅供参考