企业官网建设流程全解析

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后，决定是否把第一段提升为 root：

const root = (!setShowRoots || showRoots) && groups.length > 1 ? [groups.shift()] : [];

这段代码揭示了三个关键行为：

1. 未配置时的默认行为：setShowRoots为false（即showRoots为undefined）时，!setShowRoots为真，只要标题层级多于一级（groups.length > 1），第一段就会被提升为 root。这与文档"默认情况下顶级节点被视为 Roots"的描述一致；
2. 显式关闭：显式设置showRoots: false后，setShowRoots为真、!setShowRoots为假，root为空数组，顶级分组降级为普通文件夹；
3. 单级标题不受影响：即使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--1；
• does 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.ts，API_SidebarOptions完整支持以下选项：

需要特别注意的是，在 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.mdx
• Roots 生成的源码实现：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