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

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

布局（Layouts）用于作为页面的包装器。它可以用来将页面包裹在一些通用组件中，例如页头和页脚。布局可以通过 `addLayout` 工具进行注册。

## `addLayout`

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

::note
在 Nuxt 2 中，也可以使用此工具注册 `error` 布局。在 Nuxt 3+ 中，`error` 布局已被项目根目录中的 `error.vue` 页面[取代](https://nuxt.zhcndoc.com/docs/4.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 [app/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.