Storybook 侧边栏 Roots 配置指南：使用 sidebar.showRoots 控制层级展示
Storybook 侧边栏 Roots 配置指南使用 sidebar.showRoots 控制层级展示【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇技术指南聚焦 Storybook 管理器侧边栏中的 Roots根节点机制讲解如何通过./storybook/manager.js中的addons.setConfig配置sidebar.showRoots将顶级分组从区块切换为普通文件夹视图。读完本文你将掌握 Roots 的生成规则、禁用方法、相关侧边栏选项collapsedRoots、filters、renderLabel以及底层实现原理可直接应用到你的组件库文档项目中。Roots 是什么Storybook 的侧边栏会列出所有 stories并按组件分组展示。当组件数量增多时你可以在 CSF 文件的title中使用/分隔符来构造层级Storybook 会基于公共前缀将 stories 自动聚合为分组。例如对于文件components/modals/Alert.js将 CSF 文件命名为components/modals/Alert.stories.js并设置标题为Components/Modals/Alert侧边栏便会按此路径分层。默认情况下Storybook 会把顶级节点即标题路径的第一段视为 Roots根节点。在 UI 中Roots 以区块sections的形式展示——它们是大写且不可折叠的层级条目而更底层的分组则显示为可展开的文件夹。图为 Storybook 侧边栏中 Roots 与文件夹分组的实际展示差异出自 docs/_assets/configure/sidebar-roots.png。如果希望顶级节点以普通文件夹的形式展示而非不可折叠的区块可以通过设置sidebar.showRoots选项为false来关闭该行为。配置方法在 manager.js 中关闭 Roots关闭 Roots 的配置位于 Storybook 管理器的入口文件./storybook/manager.js中通过storybook/manager-api包暴露的addons.setConfig方法完成// ./storybook/manager.js import { addons } from storybook/manager-api; addons.setConfig({ sidebar: { showRoots: false, }, });要点说明文件位置该文件位于 Storybook 项目配置目录./storybook/下与main.js、preview.js同目录这是管理器侧manager专用配置不会进入预览preview运行时导入来源addons从storybook/manager-api导入旧版本中为storybook/manager-api本仓库以storybook/manager-api为准见 addons/manager-api 相关包结构配置结构showRoots是sidebar配置对象下的一个布尔选项false表示禁用根节点区块展示生效时机配置在 Storybook 管理器启动时读取修改后需重启开发服务器或重新构建静态站点才能生效。源码级原理Roots 是如何生成的showRoots的核心逻辑位于 code/core/src/manager-api/lib/stories.ts 中。当 Storybook 根据 story index 构建侧边栏层级树时会先从 provider 的配置中读取sidebar选项const { sidebar {} } provider.getConfig(); const { showRoots, collapsedRoots [], renderLabel } sidebar; const setShowRoots typeof showRoots ! undefined;随后在将每个条目的title按/拆分为groups后决定是否把第一段提升为 rootconst root (!setShowRoots || showRoots) groups.length 1 ? [groups.shift()] : [];这段代码揭示了三个关键行为未配置时的默认行为setShowRoots为false即showRoots为undefined时!setShowRoots为真只要标题层级多于一级groups.length 1第一段就会被提升为 root。这与文档默认情况下顶级节点被视为 Roots的描述一致显式关闭显式设置showRoots: false后setShowRoots为真、!setShowRoots为假root为空数组顶级分组降级为普通文件夹单级标题不受影响即使showRoots: true当标题只有一级如title: a无/分隔时也不会创建 root 节点而是直接作为组件/分组展示。层级树构建时root 条目会以type: root写入内部状态哈希hash并携带startCollapsed: collapsedRoots.includes(id)等属性见 code/core/src/manager-api/lib/stories.ts即 root 条目是否默认折叠由collapsedRoots决定。测试验证showRoots 的行为边界仓库中的单元测试 code/core/src/manager-api/tests/stories.test.ts 直接验证了上述逻辑sets roots when showRoots true第 232 行起当provider.getConfig返回{ sidebar: { showRoots: true } }时对标题为a/b的 story内部索引index会生成type: root的条目a、type: component的条目a-b以及最终的 story 条目a-b--1层级关系为a → a-b → a-b--1does not put bare stories into a root when showRoots true第 275 行起即使开启了showRoots标题为a无/分隔的裸 story 也不会被包进 root印证了上述第 3 条行为。这些测试覆盖了 Roots 机制的核心边界是否创建 root、何时创建、层级 id 的拼接规则sanitize处理后的parent-name形式可以作为你排查侧边栏层级问题的参考。相关侧边栏选项一览showRoots只是sidebar配置中的一项。根据类型定义 code/core/src/types/modules/api.tsAPI_SidebarOptions完整支持以下选项选项类型说明showRootsboolean是否将顶级分组展示为 Roots 区块默认未设置时开启设为false则降级为文件夹filtersRecordstring, API_FilterFunction按条件过滤侧边栏条目如隐藏特定分组或 storiescollapsedRootsstring[]指定默认折叠的 root id 列表展开层级时结合startCollapsed使用renderLabel(item, api) any自定义条目标签的渲染逻辑可用于改写自动标题的大小写等需要特别注意的是在 code/core/src/manager-api/modules/stories.ts 中showRoots与enableShortcuts、theme一起被列入removedOptions数组。这表明在管理器 API 演进过程中这些选项从stories模块的顶层配置中移出统一归入sidebar配置对象下管理。因此务必通过sidebar.showRoots的方式配置而不是在addons.setConfig的顶层直接写showRoots。使用建议与注意事项何时关闭 Roots如果你的 Storybook 主要面向终端用户提供组件浏览体验希望侧边栏更紧凑、减少不可折叠区块对视觉的割裂可关闭 Roots详见 docs/writing-stories/naming-components-and-hierarchy.mdx 中的说明。大规模组件库建议保持默认当 Storybook 由大量组件 stories 组成时官方文档建议让组件命名遵循文件系统层级并保留 Roots 提供的分区结构便于快速定位见 docs/configure/user-interface/sidebar-and-urls.mdx。验证配置生效修改manager.js后重启storybook dev观察侧边栏顶级条目是否由大写区块变为可展开的文件夹也可以通过开启showRoots: true对照观察差异。与其他 sidebar 选项组合showRoots常与collapsedRoots配合使用——当你保留 Roots 但希望某些根默认收起时将对应 root id 加入collapsedRoots数组即可。延伸阅读完整的侧边栏与 URL 配置说明docs/configure/user-interface/sidebar-and-urls.mdx组件命名与层级组织建议docs/writing-stories/naming-components-and-hierarchy.mdxRoots 生成的源码实现code/core/src/manager-api/lib/stories.ts侧边栏选项类型定义code/core/src/types/modules/api.ts行为测试用例code/core/src/manager-api/tests/stories.test.ts【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考