---
title: "useHeader"
description: "提供页头桌面端与移动端导航链接。推荐直接在 app.config 的 header.nav 与 header.mobileNav 中声明；需要按运行时状态动态生成链接时，再在项目中创建同名 composable 覆盖它。"
canonical_url: "https://docs.mhaibaraai.cn/docs/reference/composables/use-header"
---
# useHeader

> 提供页头桌面端与移动端导航链接。推荐直接在 app.config 的 header.nav 与 header.mobileNav 中声明；需要按运行时状态动态生成链接时，再在项目中创建同名 composable 覆盖它。

`useHeader()` 把 `app.config` 的 `header.nav` / `header.mobileNav` 解析为当前语言下可直接渲染的链接。`HeaderCenter` 渲染 `desktopLinks`，移动端抽屉 `HeaderBody` 渲染 `mobileLinks`。

## 推荐：在 app.config 中声明

大多数站点不需要接触这个函数，在 `app.config` 中声明即可，写法见 [导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation)：

```ts [app/app.config.ts]
export default defineAppConfig({
  header: {
    nav: [
      { label: { 'zh-CN': '文档', 'en': 'Docs' }, to: '/docs/getting-started', activeMatch: '/docs' },
      { label: 'GitHub', to: 'https://github.com/owner/repo' }
    ]
  }
})
```

## 签名

```ts
function useHeader(): {
  desktopLinks: ComputedRef<NavLink[]>
  mobileLinks: ComputedRef<NavLink[]>
}

interface NavLink {
  label: string
  to: string
  icon?: string
  target?: '_blank' | '_self'
  active: boolean
}
```

## 返回值

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `desktopLinks` | `ComputedRef<NavLink[]>` | 由 `header.nav` 解析的桌面端链接 |
| `mobileLinks` | `ComputedRef<NavLink[]>` | 由 `header.mobileNav` 解析的移动端链接；`mobileNav` 为空时沿用 `header.nav` |

解析规则：

- `label` 为按语言区分的对象时，依次取当前语言、默认语言、第一个值。
- 站内链接经 `localePath` 加语言前缀；外链保持原样，未指定 `target` 时为 `_blank`。
- `active` 显式设置时直接使用；否则站内链接在当前路径以 `activeMatch`（缺省为 `to`）开头时激活，外链始终不激活。

## 覆盖

需要根据登录状态、远程数据等动态生成导航时，在项目中创建同名文件。项目内的 composable 会覆盖 layer 的同名自动导入：

```ts [app/composables/useHeader.ts]
export function useHeader() {
  const route = useRoute()
  const { localePath } = useMovkI18n()

  const desktopLinks = computed(() => [
    { label: 'Docs', to: localePath('/docs/getting-started'), active: route.path.startsWith(localePath('/docs')) },
    { label: 'Blog', to: 'https://example.com/blog', target: '_blank' as const, active: false }
  ])

  return {
    desktopLinks,
    mobileLinks: desktopLinks
  }
}
```

覆盖时必须同时返回 `desktopLinks` 与 `mobileLinks`，元素结构与 `NavLink` 一致。覆盖后 `header.nav` / `header.mobileNav` 不再生效。

## 相关

- [导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation)
- [app.config 参考](https://docs.mhaibaraai.cn/docs/reference/app-config)

## 更新日志

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

---

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


## Sitemap

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