---
title: "自定义"
description: "在项目组件目录中创建与内置组件同名的 Vue 文件，即可替换页头、侧栏、页脚等界面区域。本页列出 v3 承诺稳定的可覆盖组件、各自的挂载位置，并为每个组件给出最小覆盖示例。"
canonical_url: "https://docs.mhaibaraai.cn/docs/guide/customization"
---
# 自定义

> 在项目组件目录中创建与内置组件同名的 Vue 文件，即可替换页头、侧栏、页脚等界面区域。本页列出 v3 承诺稳定的可覆盖组件、各自的挂载位置，并为每个组件给出最小覆盖示例。

## 覆盖方式

在项目的组件目录（如 `app/components/`）中创建同名组件即可覆盖 Layer 的默认实现。组件名只由文件名决定，`app/components/HeaderLogo.vue` 与 `app/components/header/HeaderLogo.vue` 都注册为 `HeaderLogo`。

> [!TIP]
> 
> 只想调整导航、文案或颜色时优先使用 
> 
> app.config
> 
> （如 
> 
> header.nav
> 
> 、
> 
> footer.credits
> 
> 、
> 
> ui.colors
> 
> ），不必覆盖组件，见
> 
> 配置总览
> 
> 。

覆盖组件时通常会用到以下组合式函数，它们在 Layer 内自动导入：

| 函数 | 用途 |
| --- | --- |
| `useAppConfig()` | 读取站点配置，如 `header.title`、`footer.socials` |
| `useMovkI18n()` | 当前语言、内置文案 `t()`、带语言前缀的 `localePath()` |
| `useHeader()` | 解析后的页头导航 `desktopLinks` / `mobileLinks` |
| `useDocsNavigation()` | 当前语言的文档导航树 |

## 覆盖契约

下表是 v3 起承诺的可覆盖组件：组件名、挂载位置与 props 在 v3.x 内保持稳定，均不接收 props。未列出的组件（如 `ThemePickerButton`、`HeaderToggleButton`）属于内部实现，可能随版本调整，不建议覆盖。

| 组件 | 挂载位置 |
| --- | --- |
| `Header` | 每个页面顶部；路由 `meta.header` 为 `false` 或路径以 `/examples` 开头时不渲染 |
| `HeaderLogo` | 页头左侧 |
| `HeaderCenter` | 页头中间，仅桌面端 |
| `HeaderCTA` | 页头右侧，搜索框之后 |
| `HeaderBody` | 移动端导航抽屉 |
| `HeaderBottom` | 页头下方，仅文档页 |
| `LanguageSwitcher` | 页头右侧，启用国际化且语言数大于 1 时 |
| `ThemePicker` | 页头右侧 |
| `PageHeaderLinks` | 文档页导语下方的元信息行右端 |
| `DocsAsideLeftTop` | 文档页左侧栏顶部，仅在导航过滤框显示时 |
| `DocsAsideLeftBody` | 文档页左侧栏主体，以及移动端抽屉中的文档导航 |
| `DocsAsideRightBottom` | 文档页右侧目录下方，仅桌面端 |
| `Footer` | 每个页面底部；路由 `meta.footer` 为 `false` 或路径以 `/examples` 开头时不渲染 |
| `FooterLeft` | 页脚左侧 |
| `FooterRight` | 页脚右侧 |
| `ComponentExampleExtras` | `ComponentExample` 与 `ComponentCode` 的示例容器，需开启 `movkNuxtDocs.componentDocs`，见 [ComponentExample](https://docs.mhaibaraai.cn/docs/components/component-example#componentexampleextras) |

各组件的默认实现位于 [layer/app/components](https://github.com/mhaibaraai/movk-nuxt-docs/tree/main/layer/app/components)，覆盖前建议先阅读对应源码。

## 页头

### `Header`

页头整体容器，组合 Logo、主导航、搜索、主题面板、颜色模式与语言切换。覆盖 `Header` 会替换以下所有页头子组件的挂载方式，只在需要完全不同的页头结构时使用。

::u-color-mode-image{alt="Header" class="rounded-md border border-default" dark="/screenshots/component-Header-dark.png" light="/screenshots/component-Header-light.png"}
::

```vue [app/components/Header.vue]
<template>
  <UHeader>
    <template #left>
      <HeaderLogo />
    </template>

    <HeaderCenter />

    <template #right>
      <UContentSearchButton />
      <UColorModeButton />
    </template>

    <template #body>
      <HeaderBody />
    </template>
  </UHeader>
</template>
```

### `HeaderLogo`

显示 `header.avatar` 与站点标题，点击跳转到 `header.to`。

::u-color-mode-image{alt="HeaderLogo" class="rounded-md border border-default" dark="/screenshots/component-HeaderLogo-dark.png" light="/screenshots/component-HeaderLogo-light.png"}
::

```vue [app/components/HeaderLogo.vue]
<script setup lang="ts">
const { localePath } = useMovkI18n()
</script>

<template>
  <NuxtLink :to="localePath('/')" class="flex items-center gap-2">
    <img src="/logo.svg" alt="" class="size-6">
    <span class="font-display text-xl font-bold">My Docs</span>
  </NuxtLink>
</template>
```

### `HeaderCenter`

桌面端主导航，渲染 `header.nav`。

::u-color-mode-image{alt="HeaderCenter" class="rounded-md border border-default" dark="/screenshots/component-HeaderCenter-dark.png" light="/screenshots/component-HeaderCenter-light.png"}
::

```vue [app/components/HeaderCenter.vue]
<script setup lang="ts">
const { desktopLinks } = useHeader()
</script>

<template>
  <UNavigationMenu :items="desktopLinks" variant="link" />
</template>
```

### `HeaderCTA`

页头右侧的行动号召区域。默认在启用 AI Chat 时显示 AI 入口，未启用时为空。

::u-color-mode-image{alt="HeaderCTA" class="rounded-md border border-default" dark="/screenshots/component-HeaderCTA-dark.png" light="/screenshots/component-HeaderCTA-light.png"}
::

```vue [app/components/HeaderCTA.vue]
<template>
  <UButton label="开始使用" to="/docs/getting-started" size="sm" class="hidden md:inline-flex" />
</template>
```

### `HeaderBody`

移动端导航抽屉的内容：编号的 `header.mobileNav` 链接，文档页下方追加侧栏导航。

::u-color-mode-image{alt="HeaderBody" class="mx-auto max-w-sm rounded-md border border-default" dark="/screenshots/component-HeaderBody-dark.png" light="/screenshots/component-HeaderBody-light.png"}
::

```vue [app/components/HeaderBody.vue]
<script setup lang="ts">
const { mobileLinks } = useHeader()
const isDocsRoute = useDocsRoute()
</script>

<template>
  <UNavigationMenu :items="mobileLinks" orientation="vertical" />

  <DocsAsideLeftBody v-if="isDocsRoute" class="mt-6" />
</template>
```

### `HeaderBottom`

文档页页头下方的编号栏目条，底线同时显示阅读进度。覆盖后阅读进度条需要自行实现。

::u-color-mode-image{alt="HeaderBottom" class="rounded-md border border-default" dark="/screenshots/component-HeaderBottom-dark.png" light="/screenshots/component-HeaderBottom-light.png"}
::

```vue [app/components/HeaderBottom.vue]
<script setup lang="ts">
const navigation = useDocsNavigation()
</script>

<template>
  <UContainer class="hidden lg:flex gap-6 h-12 items-center border-t border-default">
    <ULink v-for="item in navigation" :key="item.path" :to="item.path" class="text-sm">
      {{ item.title }}
    </ULink>
  </UContainer>
</template>
```

### `LanguageSwitcher`

启用 [国际化](https://docs.mhaibaraai.cn/docs/guide/i18n) 且有多个语言时显示的语言切换器。

::u-color-mode-image{alt="LanguageSwitcher" class="rounded-md border border-default" dark="/screenshots/component-LanguageSwitcher-dark.png" light="/screenshots/component-LanguageSwitcher-light.png"}
::

```vue [app/components/LanguageSwitcher.vue]
<script setup lang="ts">
const { locale, locales, switchLocalePath } = useMovkI18n()
</script>

<template>
  <div class="flex gap-2 text-sm">
    <NuxtLink
      v-for="item in locales"
      :key="item.code"
      :to="switchLocalePath(item.code)"
      :class="item.code === locale ? 'text-highlighted' : 'text-muted'"
    >
      {{ item.name }}
    </NuxtLink>
  </div>
</template>
```

### `ThemePicker`

访客主题面板，可调整主色、中性色、圆角、图标集与颜色模式，并导出配置，见[主题与字体](https://docs.mhaibaraai.cn/docs/guide/theme#%E4%B8%BB%E9%A2%98%E9%9D%A2%E6%9D%BF)。不需要该功能时可以用空组件覆盖：

::u-color-mode-image{alt="ThemePicker" class="rounded-md border border-default" dark="/screenshots/component-ThemePicker-dark.png" light="/screenshots/component-ThemePicker-light.png"}
::

```vue [app/components/ThemePicker.vue]
<template>
  <span class="hidden" />
</template>
```

## 文档页

### `PageHeaderLinks`

文档页元信息行右端的「复制页面」按钮及下拉菜单：复制 Markdown 链接、以 Markdown 查看、在 ChatGPT 或 Claude 中打开，启用 MCP 时还包括复制 MCP 地址与添加到 VS Code、Cursor。

::u-color-mode-image{alt="PageHeaderLinks" class="rounded-md border border-default" dark="/screenshots/component-PageHeaderLinks-dark.png" light="/screenshots/component-PageHeaderLinks-light.png"}
::

```vue [app/components/PageHeaderLinks.vue]
<script setup lang="ts">
const route = useRoute()
</script>

<template>
  <UButton
    :to="`/raw${route.path}.md`"
    target="_blank"
    label="Markdown"
    icon="i-lucide-file-text"
    size="xs"
    variant="link"
    color="neutral"
  />
</template>
```

### `DocsAsideLeftTop`

左侧栏顶部区域，默认是导航过滤框，只在 `aside.filter.enabled` 开启且当前栏目条目数达到阈值时渲染，见[导航与分类](https://docs.mhaibaraai.cn/docs/guide/navigation#%E5%AF%BC%E8%88%AA%E8%BF%87%E6%BB%A4)。

::u-color-mode-image{alt="DocsAsideLeftTop" class="rounded-md border border-default" dark="/screenshots/component-DocsAsideLeftTop-dark.png" light="/screenshots/component-DocsAsideLeftTop-light.png"}
::

```vue [app/components/DocsAsideLeftTop.vue]
<script setup lang="ts">
const searchTerm = inject<Ref<string>>('docsFilterSearch', ref(''))
</script>

<template>
  <UInput v-model="searchTerm" icon="i-lucide-search" placeholder="过滤..." class="w-full" />
</template>
```

`docsFilterSearch` 是侧栏布局提供的过滤词，`DocsAsideLeftBody` 据此过滤导航。

### `DocsAsideLeftBody`

左侧栏主体：按栏目分组的文档导航，当前项左侧的指示条随路由滑动。

::u-color-mode-image{alt="DocsAsideLeftBody" class="rounded-md border border-default" dark="/screenshots/component-DocsAsideLeftBody-dark.png" light="/screenshots/component-DocsAsideLeftBody-light.png"}
::

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

<template>
  <div v-for="group in navigationByCategory" :key="group.path" class="mb-6">
    <p class="mb-2 text-sm font-semibold">
      {{ group.title }}
    </p>
    <UContentNavigation :navigation="group.children" :collapsible="false" />
  </div>
</template>
```

### `DocsAsideRightBottom`

右侧目录下方的区域。启用 AI Chat 时默认显示「用 AI 解释」按钮。

::u-color-mode-image{alt="DocsAsideRightBottom" class="rounded-md border border-default" dark="/screenshots/component-DocsAsideRightBottom-dark.png" light="/screenshots/component-DocsAsideRightBottom-light.png"}
::

```vue [app/components/DocsAsideRightBottom.vue]
<template>
  <UPageLinks
    title="社区"
    :links="[{ label: '讨论区', icon: 'i-lucide-messages-square', to: 'https://github.com/my/repo/discussions', target: '_blank' }]"
  />
</template>
```

## 页脚

### `Footer`

页脚容器，左右两侧分别挂载 `FooterLeft` 与 `FooterRight`。

::u-color-mode-image{alt="Footer" class="rounded-md border border-default" dark="/screenshots/component-Footer-dark.png" light="/screenshots/component-Footer-light.png"}
::

```vue [app/components/Footer.vue]
<template>
  <UFooter>
    <template #left>
      <FooterLeft />
    </template>

    <template #right>
      <FooterRight />
    </template>
  </UFooter>
</template>
```

### `FooterLeft`

默认按 MDC 渲染 `footer.credits`。

::u-color-mode-image{alt="FooterLeft" class="rounded-md border border-default" dark="/screenshots/component-FooterLeft-dark.png" light="/screenshots/component-FooterLeft-light.png"}
::

```vue [app/components/FooterLeft.vue]
<template>
  <p class="text-sm text-muted">
    © 2026 My Team · Released under the MIT License
  </p>
</template>
```

### `FooterRight`

默认渲染 `footer.socials` 中的图标按钮。

::u-color-mode-image{alt="FooterRight" class="rounded-md border border-default" dark="/screenshots/component-FooterRight-dark.png" light="/screenshots/component-FooterRight-light.png"}
::

```vue [app/components/FooterRight.vue]
<script setup lang="ts">
const { footer } = useAppConfig()
</script>

<template>
  <div class="flex gap-1">
    <UButton
      v-for="link in footer.socials"
      :key="link.to"
      v-bind="link"
      color="neutral"
      variant="ghost"
    />
  </div>
</template>
```


## Sitemap

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