VitePress 默认主题侧边栏配置完全指南分组、多侧边栏与折叠实战【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress侧边栏是 VitePress 默认主题中最重要的文档导航模块通过themeConfig.sidebar即可完成从单组链接到按页面路径切换的多侧边栏配置。本文以仓库中的官方参考文档 docs/ko/reference/default-theme-sidebar.md 为骨架结合默认主题的源码实现与端到端测试系统讲解数组/对象两种配置形态、base路径前缀、collapsed折叠分组以及最深 6 级嵌套的限制帮助你为站点搭建一套结构清晰、可折叠、按章节自动切换的侧边栏导航。认识配置入口themeConfig.sidebar侧边栏配置统一放在主题配置对象的sidebar字段下其类型为Sidebar。根据 types/default-theme.d.ts 中的类型定义Sidebar有两种形态export type Sidebar SidebarItem[] | SidebarMulti export interface SidebarMulti { [path: string]: SidebarItem[] | { items: SidebarItem[]; base: string } }数组形态适用于全站只有一套侧边栏的场景对象形态SidebarMulti键为路径前缀值为该路径下显示的侧边栏配置用于按页面路径切换不同侧边栏。而每个SidebarItem则包含以下字段见 types/default-theme.d.tsexport type SidebarItem { text?: string // 条目文本 link?: string // 条目链接 items?: SidebarItem[] // 子条目 collapsed?: boolean // 是否可折叠未指定不可折叠true默认折叠false默认展开 base?: string // 子条目的路径前缀 docFooterText?: string // 上/下页翻页链接中显示的自定义文本 rel?: string target?: string }最基础的配置写法如下export default { themeConfig: { sidebar: [ { text: 指南, items: [ { text: 介绍, link: /introduction }, { text: 快速开始, link: /getting-started }, // ... ] } ] } }基础用法数组形式的侧边栏菜单侧边栏菜单最简单的形式是直接传入一个链接数组。数组中的第一层条目定义了侧边栏的分区section每个分区必须包含text分区标题items实际的导航链接数组。export default { themeConfig: { sidebar: [ { text: 分区标题 A, items: [ { text: 条目 A, link: /item-a }, { text: 条目 B, link: /item-b }, // ... ] }, { text: 分区标题 B, items: [ { text: 条目 C, link: /item-c }, { text: 条目 D, link: /item-d }, // ... ] } ] } }链接路径规范每个link必须以/开头指向站点根目录下的真实文件路径。如果链接以斜杠结尾如/guide/则渲染的是该目录下的index.md页面export default { themeConfig: { sidebar: [ { text: 指南, items: [ // 这会显示 /guide/index.md 页面 { text: 介绍, link: /guide/ } ] } ] } }需要说明的是link必须指向站内路径若需指向外部 URL同样可以写入渲染层会通过isExternal判断但base路径前缀不会作用于外部链接。多级嵌套从根层级算起最多 6 层侧边栏条目支持递归嵌套从根层级算起最多可以嵌套6 层超过 6 层的嵌套条目会被忽略不会显示在侧边栏中export default { themeConfig: { sidebar: [ { text: 第 1 层, items: [ { text: 第 2 层, items: [ { text: 第 3 层, items: [ // ... ] } ] } ] } ] } }这一限制在渲染组件 VPSidebarItem.vue 中得到了印证组件仅在depth 5时才会继续递归渲染子列表而depth从 0 开始计数因此实际可渲染 05 共 6 个层级。多侧边栏按页面路径切换不同页面路径可以展示不同的侧边栏。例如文档站通常会把指南和参考分成两个独立的内容区块各配一套侧边栏。首先把页面按分区整理到不同目录. ├─ guide/ │ ├─ index.md │ ├─ one.md │ └─ two.md └─ config/ ├─ index.md ├─ three.md └─ four.md然后修改配置文件为每个分区定义各自的侧边栏。此时需要把sidebar从数组改为对象对象的键是目录路径前缀export default { themeConfig: { sidebar: { // 当用户位于 guide 目录时显示该侧边栏 /guide/: [ { text: 指南, items: [ { text: 概览, link: /guide/ }, { text: 一, link: /guide/one }, { text: 二, link: /guide/two } ] } ], // 当用户位于 config 目录时显示该侧边栏 /config/: [ { text: 配置, items: [ { text: 概览, link: /config/ }, { text: 三, link: /config/three }, { text: 四, link: /config/four } ] } ] } } }路径匹配规则源码视角多侧边栏的匹配逻辑位于 src/client/theme-default/support/sidebar.ts 的getSidebar函数若sidebar是数组直接返回并应用base处理若为对象则取当前页面相对路径遍历对象的键键会先按路径段数量从多到少排序b.split(/).length - a.split(/).length再取第一个path.startsWith(dir)的匹配项——也就是说更具体更深的路径前缀优先匹配例如同时配置了/guide/与/guide/advanced/时位于 advanced 目录下的页面会优先命中后者若匹配到的值本身是对象含items与base则按{ items, base }结构取出并应用base。在运行时layout.ts 中的registerWatchers会监听page.relativePath与theme.sidebar的变化实时调用getSidebar重新计算当前页面的侧边栏因此切换路由时侧边栏会自动刷新。可折叠的侧边栏分组collapsed 选项在侧边栏分组上添加collapsed选项即可为每个分区显示一个展开/折叠的切换按钮export default { themeConfig: { sidebar: [ { text: 分区标题 A, collapsed: false, items: [/* ... */] } ] } }collapsed有三种取值语义与 types/default-theme.d.ts 中的注释一致取值行为未设置分组不可折叠不显示切换按钮false可折叠默认展开true可折叠首次加载页面时默认收起export default { themeConfig: { sidebar: [ { text: 分区标题 A, collapsed: true, items: [/* ... */] } ] } }折叠行为背后的实现细节折叠状态由 src/client/theme-default/composables/sidebar.ts 中的useSidebarItemControl管理值得注意的细节包括collapsible计算属性判断item.collapsed ! null因此只有显式设置collapsed的分组才会渲染切换按钮当当前链接处于激活状态、或子项中存在激活链接时分组会被自动展开nextTick(() (collapsed.value false))确保用户进入某章节时始终能看到当前所在位置渲染组件 VPSidebarItem.vue 为切换按钮设置了aria-expanded与aria-labeltoggle section并通过折叠时transform: rotate(0)翻转箭头图标。仓库中的端到端测试tests/e2e/sidebar.test.ts 对这一交互做了完整验证测试断言可折叠分组渲染出唯一的BUTTON切换控件、初始aria-expanded为true并且通过键盘 Enter、Space 以及鼠标点击均能切换折叠状态点击后aria-expanded同步变为false这保证了折叠功能在真实浏览器环境中的可用性与可访问性。base为子条目批量添加路径前缀当文档目录很深、或多个分组位于同一个子目录下时可以给每个link重复书写相同的前缀十分繁琐。此时可以使用base选项自动为分组内所有嵌套items的链接拼接路径前缀。base同时支持多侧边栏配置和嵌套分组两种场景。在多侧边栏中使用 basebase可以定义在侧边栏分区配置的根部export default { themeConfig: { sidebar: { /guide/: { base: /guide/, items: [ // 该链接会被解析为 /guide/introduction { text: 介绍, link: introduction }, // 该链接会被解析为 /guide/getting-started { text: 快速开始, link: getting-started } ] } } } }注意此时link不再以/开头由base负责补全。在嵌套分组中使用 basebase也可以用在嵌套的侧边栏分组内作用于该分组的直接子条目嵌套的base会覆盖父级的前缀export default { themeConfig: { sidebar: [ { text: 参考, base: /reference/, items: [ // 该链接会被解析为 /reference/site-config { text: 站点配置, link: site-config }, { text: 默认主题, // 嵌套 base 覆盖父级路径前缀 base: /reference/default-theme-, items: [ // 该链接会被解析为 /reference/default-theme-nav { text: 导航栏, link: nav }, // 该链接会被解析为 /reference/default-theme-sidebar { text: 侧边栏, link: sidebar } ] } ] } ] } }base 的实现原理base的处理集中在 src/client/theme-default/support/sidebar.ts 的addBase函数中function addBase(items: SidebarItem[], _base?: string): SidebarItem[] { return [...items].map((_item) { const item { ..._item } const base item.base || _base // 子级 base 优先实现嵌套覆盖父级 if (base item.link !isExternal(item.link)) item.link base item.link.replace(/^\//, base.endsWith(/) ? : /) if (item.items) item.items addBase(item.items, base) return item }) }从源码可以确认两个关键行为子条目的base优先于父级baseitem.base || _base外部链接isExternal为真不会被拼接前缀。同时getSidebar中无论数组形态还是对象形态最终都会调用addBase保证了base在两种配置形态下行为一致。与侧边栏相关的其他配置与能力页面级开关frontmatter 中的 sidebar侧边栏并非只能全局配置。在单个页面的 frontmatter 中设置sidebar: false可以在该页面隐藏侧边栏见 docs/ko/reference/frontmatter-config.md--- sidebar: false ---该开关在 layout.ts 的hasSidebar计算属性中生效只有frontmatter.sidebar ! false、sidebar配置非空且页面不是首页时侧边栏才会渲染。此外在窄屏移动端下侧边栏会收起为抽屉式菜单themeConfig.sidebarMenuLabel默认Menu用于自定义移动端侧边栏的菜单标签详见 docs/ko/reference/default-theme-config.md。页脚翻页链接docFooterText每个SidebarItem还支持docFooterText字段用于自定义该页在文档底部上一页/下一页翻页链接中显示的文本此外rel与target会原样透传到渲染出的a标签上见 getFlatSideBarLinks 与 VPSidebarItem.vue适合在链接需要新窗口打开或添加noopener等场景使用。从配置到渲染完整调用链一览把上述内容串起来一条themeConfig.sidebar配置从定义到最终渲染的完整链路如下类型定义Sidebar/SidebarMulti/SidebarItem定义在 types/default-theme.d.ts运行时解析layout.ts 监听路由与配置变化调用getSidebar按路径前缀匹配出当前侧边栏并应用basesupport/sidebar.ts分组归并getSidebarGroups把无items的孤立条目归入最近的上一个分组保证渲染结构合法状态管理useSidebarItemControlcomposables/sidebar.ts负责折叠状态、激活链接检测与自动展开渲染输出VPSidebarItem.vue 递归渲染条目控制 6 层嵌套上限、折叠按钮与 ARIA 语义测试保障tests/e2e/sidebar.test.ts 通过 Playwright 端到端验证折叠交互的可访问性与正确性。掌握了sidebar的数组/对象两种形态、collapsed的三态语义、base的批量前缀以及 6 层嵌套限制你就能像 VitePress 官方文档站一样为不同章节配置各自独立、可折叠、自动定位到当前页面的专业侧边栏导航。【免费下载链接】vitepressVite Vue powered static site generator.项目地址: https://gitcode.com/gh_mirrors/vi/vitepress创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考