---
title: "布局"
description: "Nuxt Kit 提供了一组实用工具，帮助你处理布局。"
canonical_url: "https://nuxt.zhcndoc.com/docs/3.x/api/kit/layout"
---
# 布局

> Nuxt Kit 提供了一组实用工具，帮助你处理布局。

布局用于作为页面的包装器。它可以用来将页面包裹在公共组件中，例如页头和页脚。布局可以通过 `addLayout` 实用工具注册。

## `addLayout`

将模板注册为布局并添加到布局列表中。

::note
在 Nuxt 2 中，也可以使用此实用工具注册 `error` 布局。在 Nuxt 3+ 中，项目根目录中的 `error.vue` 页面取代了 `error` 布局[链接](https://nuxt.zhcndoc.com/docs/3.x/getting-started/error-handling#error-page)。
::

### 用法

```ts twoslash
import { addLayout, createResolver, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    const { resolve } = createResolver(import.meta.url)

    addLayout({
      src: resolve('templates/custom-layout.ts'),
      filename: 'custom-layout.ts',
    }, 'custom')
  },
})
```

### 类型

```ts
function addLayout (layout: NuxtTemplate | string, name: string): void
```

### 参数

**`layout`**：模板对象或者模板路径字符串。如果提供的是字符串，则会被转换成模板对象，`src` 属性设为该字符串值。如果提供的是模板对象，则必须包含以下属性：

| 属性            | 类型                                               | 必需      | 说明                                                                  |
| ------------- | ------------------------------------------------ | ------- | ------------------------------------------------------------------- |
| `src`         | `string`                                         | `false` | 模板路径。如果没有提供 `src`，则必须提供 `getContents`。                              |
| `filename`    | `string`                                         | `false` | 模板文件名。如果没有提供 `filename`，则会从 `src` 路径生成。在此情况下，必须提供 `src`。            |
| `dst`         | `string`                                         | `false` | 目标文件路径。如果没有提供 `dst`，则会从 `filename` 路径及 Nuxt 的 `buildDir` 选项生成。      |
| `options`     | `Record<string, any>`{lang="ts"}                 | `false` | 传递给模板的选项。                                                           |
| `getContents` | `(data) => string \| Promise<string>`{lang="ts"} | `false` | 一个函数，接收 `options` 对象作为参数。应返回字符串或返回字符串的 Promise。如果提供了 `src`，此函数会被忽略。 |
| `write`       | `boolean`                                        | `false` | 如果设为 `true`，模板将写入目标文件。否则，模板仅在虚拟文件系统中使用。                             |

**`name`**：注册布局时使用的名称（例如 `default`、`custom` 等）。

### 示例

这将注册一个名为 `custom` 的布局，用页头和页脚包裹页面。

```ts twoslash
import { addLayout, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addLayout({
      write: true,
      filename: 'my-layout.vue',
      getContents: () => `<template>
  <div>
    <header>My Header</header>
    <slot />
    <footer>My Footer</footer>
  </div>
</template>`,
    }, 'custom')
  },
})
```

你可以在页面中使用这个布局：

```vue [pages/about.vue]
<script setup lang="ts">
definePageMeta({
  layout: 'custom',
})
</script>

<template>
  <div>关于页面</div>
</template>
```

::warning
由于 `@vitejs/plugin-vue` 不支持虚拟 `.vue` 文件，你可以通过给 `addLayout` 的第一个参数传入 `write: true` 来绕过此限制。
::

---

- [源码](https://github.com/nuxt/nuxt/blob/main/packages/kit/src/layout.ts)


## Sitemap

See the full [sitemap](https://nuxt.zhcndoc.com/sitemap.md) for all pages.