自定义

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

覆盖方式

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

只想调整导航、文案或颜色时优先使用 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页脚右侧
ComponentExampleExtrasComponentExample 与 ComponentCode 的示例容器,需开启 movkNuxtDocs.componentDocs,见 ComponentExample

各组件的默认实现位于 layer/app/components,覆盖前建议先阅读对应源码。

页头

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

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

    <HeaderCenter />

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

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

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

HeaderLogo
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。

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

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

HeaderCTA

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

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

HeaderBody

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

HeaderBody
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

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

HeaderBottom
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

启用 国际化 且有多个语言时显示的语言切换器。

LanguageSwitcher
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

访客主题面板,可调整主色、中性色、圆角、图标集与颜色模式,并导出配置,见主题与字体。不需要该功能时可以用空组件覆盖:

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

文档页

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

PageHeaderLinks
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 开启且当前栏目条目数达到阈值时渲染,见导航与分类。

DocsAsideLeftTop
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

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

DocsAsideLeftBody
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 解释」按钮。

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

页脚

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

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

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

FooterLeft

默认按 MDC 渲染 footer.credits。

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

FooterRight

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

FooterRight
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>
Copyright © 2024 - 2026