覆盖方式
在项目的组件目录(如 app/components/)中创建同名组件即可覆盖 Layer 的默认实现。组件名只由文件名决定,app/components/HeaderLogo.vue 与 app/components/header/HeaderLogo.vue 都注册为 HeaderLogo。
覆盖组件时通常会用到以下组合式函数,它们在 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 |
各组件的默认实现位于 layer/app/components,覆盖前建议先阅读对应源码。
页头
Header
页头整体容器,组合 Logo、主导航、搜索、主题面板、颜色模式与语言切换。覆盖 Header 会替换以下所有页头子组件的挂载方式,只在需要完全不同的页头结构时使用。


<template>
<UHeader>
<template #left>
<HeaderLogo />
</template>
<HeaderCenter />
<template #right>
<UContentSearchButton />
<UColorModeButton />
</template>
<template #body>
<HeaderBody />
</template>
</UHeader>
</template>
HeaderLogo
显示 header.avatar 与站点标题,点击跳转到 header.to。


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


<script setup lang="ts">
const { desktopLinks } = useHeader()
</script>
<template>
<UNavigationMenu :items="desktopLinks" variant="link" />
</template>
HeaderCTA
页头右侧的行动号召区域。默认在启用 AI Chat 时显示 AI 入口,未启用时为空。


<template>
<UButton label="开始使用" to="/docs/getting-started" size="sm" class="hidden md:inline-flex" />
</template>
HeaderBody
移动端导航抽屉的内容:编号的 header.mobileNav 链接,文档页下方追加侧栏导航。


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


<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
启用 国际化 且有多个语言时显示的语言切换器。


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


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


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


<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
左侧栏主体:按栏目分组的文档导航,当前项左侧的指示条随路由滑动。


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


<template>
<UPageLinks
title="社区"
:links="[{ label: '讨论区', icon: 'i-lucide-messages-square', to: 'https://github.com/my/repo/discussions', target: '_blank' }]"
/>
</template>
页脚
Footer
页脚容器,左右两侧分别挂载 FooterLeft 与 FooterRight。


<template>
<UFooter>
<template #left>
<FooterLeft />
</template>
<template #right>
<FooterRight />
</template>
</UFooter>
</template>
FooterLeft
默认按 MDC 渲染 footer.credits。


<template>
<p class="text-sm text-muted">
© 2026 My Team · Released under the MIT License
</p>
</template>
FooterRight
默认渲染 footer.socials 中的图标按钮。


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