useNavigation

把文档导航树加工成侧栏需要的形态:取出顶层栏目、把当前栏目的页面按 docs.categories 分组,并为任意路径生成面包屑。自定义侧栏或目录组件时用它保持与默认实现一致的分组规则。

useNavigation() 接收导航树,返回三种派生数据。默认侧栏 DocsAsideLeftBody 与文档页面包屑都基于它实现。

用法

app/components/DocsAsideLeftBody.vue
<script setup lang="ts">
const navigation = useDocsNavigation()
const { navigationByCategory } = useNavigation(navigation)
</script>

<template>
  <section v-for="group in navigationByCategory" :key="group.title">
    <p>{{ group.title }}</p>
    <UContentNavigation :navigation="group.children" />
  </section>
</template>

签名

function useNavigation(navigation: Ref<ContentNavigationItem[] | undefined>): {
  rootNavigation: ComputedRef<ContentNavigationItem[]>
  navigationByCategory: ComputedRef<ContentNavigationItem[]>
  findBreadcrumb: (path: string) => BreadcrumbItem[]
}

参数

名称类型说明
navigationRef<ContentNavigationItem[] | undefined>文档导航树,通常来自 useDocsNavigation()

返回值

名称类型说明
rootNavigationComputedRef<ContentNavigationItem[]>文档根下的顶层栏目,页头栏目条使用它
navigationByCategoryComputedRef<ContentNavigationItem[]>当前路由所在栏目的页面分组,规则见下文
findBreadcrumb(path: string) => BreadcrumbItem[]返回从栏目到指定路径的面包屑,每项为 { label, to } 形式的链接(不含图标),可直接传给 UBreadcrumb(BreadcrumbItem 来自 @nuxt/ui)

分组规则

navigationByCategory 以路由的第一段 slug 确定当前栏目,把栏目内页面分为三类,按以下顺序输出:

  1. 没有 category、也没有子目录的页面,归入「概览」分组(文案来自内置翻译 docs.overview)。
  2. 子目录,每个子目录成为一个分组,例如参考区的「组合式函数」。
  3. 带 category 的页面,按 app.config 中 docs.categories[栏目 slug] 声明的顺序分组;未声明的 category 不会显示。
app/app.config.ts
export default defineAppConfig({
  docs: {
    categories: {
      guide: [
        { id: 'basics', title: { 'zh-CN': '基础', 'en': 'Basics' }, icon: 'i-lucide-settings' }
      ]
    }
  }
})
content/docs/2.guide/1.configuration.md
---
title: 配置
category: basics
---

切换语言的瞬间,如果导航数据仍属于上一个语言,navigationByCategory 返回空数组,避免用错误语言的树渲染当前页。

相关

更新日志

No recent changes
Copyright © 2024 - 2026