---
title: "useDocsShell"
description: "app.vue 与 error.vue 共用的站点外壳：按当前语言加载导航树与搜索索引，注入 html 语言、方向、字体与颗粒属性，并向组件树提供导航。只有在项目中完全重写 app.vue 或 error.vue 时才需要直接调用它。"
canonical_url: "https://docs.mhaibaraai.cn/docs/reference/composables/use-docs-shell"
---
# useDocsShell

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

layer 的 `app.vue` 与 `error.vue` 都以 `await useDocsShell()` 开头。如果你在项目中覆盖了它们，必须同样调用，否则 [`useDocsNavigation`](https://docs.mhaibaraai.cn/docs/reference/composables/use-docs-navigation)、页头栏目条和侧栏都拿不到导航数据。

## 用法

```vue [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`](https://github.com/mhaibaraai/movk-nuxt-docs/blob/main/layer/app/app.vue) 还挂载了 AI Chat 面板、⌘K 最近访问分组与 `useLocaleSeo()`，重写时请以它为起点复制后修改。

## 签名

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

## 返回值

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| `nuxtUiLocale` | `ComputedRef<Locale>` | 当前语言对应的 `@nuxt/ui/locale` 语言包，找不到时回退为 `en`；传给 `UApp` 的 `locale` |
| `rootNavigation` | `ComputedRef<ContentNavigationItem[]>` | 顶层栏目导航，同时以 `'navigation'` 为 key 提供给组件树 |
| `files` | `Ref<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`](https://docs.mhaibaraai.cn/docs/reference/composables/use-theme) 生成的圆角、黑色主色样式。

## 注意事项

- 必须在 `<script setup>` 顶层 `await`。函数内部在唯一的 `await` 之前完成 `provide` 与 `useHead`，调用方不要在它之前插入其他 `await`。
- 多语言 SEO 不在外壳内，需要另外调用 [`useLocaleSeo()`](https://docs.mhaibaraai.cn/docs/reference/composables/use-locale-seo)。

## 更新日志

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

---

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


## Sitemap

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