useDocsShell

app.vue 与 error.vue 共用的站点外壳:按当前语言加载导航树与搜索索引,注入 html 语言、方向、字体与颗粒属性,并向组件树提供导航。只有在项目中完全重写 app.vue 或 error.vue 时才需要直接调用它。

layer 的 app.vue 与 error.vue 都以 await useDocsShell() 开头。如果你在项目中覆盖了它们,必须同样调用,否则 useDocsNavigation、页头栏目条和侧栏都拿不到导航数据。

用法

app/app.vue
<script setup lang="ts">
const { nuxtUiLocale, rootNavigation, files } = await useDocsShell()
</script>

<template>
  <UApp :locale="nuxtUiLocale">
    <Header />
    <NuxtLayout>
      <NuxtPage />
    </NuxtLayout>
    <Footer />

    <ClientOnly>
      <UContentSearch :files="files" :navigation="rootNavigation" />
    </ClientOnly>
  </UApp>
</template>

上例只保留了外壳的最小结构。layer 的 app.vue 还挂载了 AI Chat 面板、⌘K 最近访问分组与 useLocaleSeo(),重写时请以它为起点复制后修改。

签名

function useDocsShell(): Promise<{
  nuxtUiLocale: ComputedRef<Locale>
  rootNavigation: ComputedRef<ContentNavigationItem[]>
  files: Ref<ContentSearchSection[] | undefined>
}>

返回值

名称类型说明
nuxtUiLocaleComputedRef<Locale>当前语言对应的 @nuxt/ui/locale 语言包,找不到时回退为 en;传给 UApp 的 locale
rootNavigationComputedRef<ContentNavigationItem[]>顶层栏目导航,同时以 'navigation' 为 key 提供给组件树
filesRef<ContentSearchSection[] | undefined>当前语言的全文搜索索引,仅在客户端懒加载,传给 UContentSearch

副作用

调用后会注册:

  • 按语言区分 key 的导航请求(docs-navigation-{locale}),查询时带上页面的 category 与 description 字段。
  • <html> 的 lang、dir,theme.font 为 sans 时的 data-font="sans",theme.grain 开启时的 data-grain。
  • viewport 与 theme-color meta,以及 useTheme 生成的圆角、黑色主色样式。

注意事项

  • 必须在 <script setup> 顶层 await。函数内部在唯一的 await 之前完成 provide 与 useHead,调用方不要在它之前插入其他 await。
  • 多语言 SEO 不在外壳内,需要另外调用 useLocaleSeo()。

更新日志

No recent changes
Copyright © 2024 - 2026