---
title: "useNavigation"
description: "把文档导航树加工成侧栏需要的形态：取出顶层栏目、把当前栏目的页面按 docs.categories 分组，并为任意路径生成面包屑。自定义侧栏或目录组件时用它保持与默认实现一致的分组规则。"
canonical_url: "https://docs.mhaibaraai.cn/docs/reference/composables/use-navigation"
---
# useNavigation

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

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

## 用法

```vue [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>
```

## 签名

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

## 参数

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `navigation` | `Ref<ContentNavigationItem[] \| undefined>` | 文档导航树，通常来自 [`useDocsNavigation()`](https://docs.mhaibaraai.cn/docs/reference/composables/use-docs-navigation) |

## 返回值

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `rootNavigation` | `ComputedRef<ContentNavigationItem[]>` | 文档根下的顶层栏目，页头栏目条使用它 |
| `navigationByCategory` | `ComputedRef<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` 不会显示。

```ts [app/app.config.ts]
export default defineAppConfig({
  docs: {
    categories: {
      guide: [
        { id: 'basics', title: { 'zh-CN': '基础', 'en': 'Basics' }, icon: 'i-lucide-settings' }
      ]
    }
  }
})
```

```md [content/docs/2.guide/1.configuration.md]
---
title: 配置
category: basics
---
```

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

## 相关

- [导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation)
- [useCategory](https://docs.mhaibaraai.cn/docs/reference/composables/use-category)

## 更新日志

See commit history for [layer/app/composables/useNavigation.ts](https://github.com/mhaibaraai/movk-nuxt-docs/commits/main/layer/app/composables/useNavigation.ts).

---

- [GitHub](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/composables/useNavigation.ts)


## Sitemap

See the full [sitemap](https://docs.mhaibaraai.cn/sitemap.md) for all pages.
