v3.17
Nuxt on GitHub

模板

源代码
Nuxt Kit 提供了一组实用工具，帮助您处理模板。这些函数允许您在开发和构建时生成额外的文件。

模板允许在开发和构建时生成额外的文件。这些文件将在虚拟文件系统中可用，并可用于插件、布局、组件等。addTemplate 和 addTypeTemplate 允许您向 Nuxt 应用添加模板。updateTemplates 允许您重新生成与过滤器匹配的模板。

addTemplate

在构建期间将给定的模板渲染到虚拟文件系统中，并可选地在项目 buildDir 中写入磁盘。

使用

import { addTemplate, defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup(options, nuxt) {
    const globalMeta = defu(nuxt.options.app.head, {
      charset: options.charset,
      viewport: options.viewport
    })

    addTemplate({
      filename: 'meta.config.mjs',
      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' })
    })
  }
})

类型

function addTemplate (template: NuxtTemplate | string): ResolvedNuxtTemplate

参数

template: 模板对象或包含模板路径的字符串。如果提供字符串，将转换为模板对象，并将 src 设置为该字符串值。如果提供模板对象，则必须具有以下属性：

属性类型必需描述
srcstringfalse模板的路径。如果未提供 src，则必须提供 getContents。
filenamestringfalse模板的文件名。如果未提供 filename，将根据 src 路径生成。在这种情况下，src 选项是必需的。
dststringfalse目标文件的路径。如果未提供 dst，将根据 filename 路径和 Nuxt 的 buildDir 选项生成。
optionsOptionsfalse传递给模板的选项。
getContents(data: Options) => string | Promise<string>false一个函数，将接收 options 对象作为参数。它应返回字符串或解析为字符串的 Promise。如果提供了 src，此函数将被忽略。
writebooleanfalse如果设置为 true，模板将被写入目标文件。否则，模板仅在虚拟文件系统中使用。

示例

为运行时插件创建虚拟文件

在此示例中，我们在模块中合并一个对象，并在运行时插件中使用结果。

module.ts
import { addTemplate, defineNuxtModule } from '@nuxt/kit'
import { defu } from 'defu'

export default defineNuxtModule({
  setup (options, nuxt) {
    const globalMeta = defu(nuxt.options.app.head, {
      charset: options.charset,
      viewport: options.viewport,
    })

    addTemplate({
      filename: 'meta.config.mjs',
      getContents: () => 'export default ' + JSON.stringify({ globalMeta, mixinKey: 'setup' }),
    })
  },
})

在上面的模块中，我们生成了一个名为 meta.config.mjs 的虚拟文件。在运行时插件中，我们可以使用 #build 别名导入它：

runtime/plugin.ts
import { createHead as createServerHead } from '@unhead/vue/server'
import { createHead as createClientHead } from '@unhead/vue/client'
import { defineNuxtPlugin } from '#imports'
// @ts-ignore
import metaConfig from '#build/meta.config.mjs'

export default defineNuxtPlugin((nuxtApp) => {
  const createHead = import.meta.server ? createServerHead : createClientHead
  const head = createHead()
  head.push(metaConfig.globalMeta)

  nuxtApp.vueApp.use(head)
})

addTypeTemplate

在构建期间将给定的模板渲染到项目 buildDir 中，然后将其注册为类型。

使用

import { addTypeTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addTypeTemplate({
      filename: 'types/markdown.d.ts',
      getContents: () => `declare module '*.md' {
  import type { ComponentOptions } from 'vue'
  const Component: ComponentOptions
  export default Component
}`,
    })
  },
})

类型

function addTypeTemplate (template: NuxtTypeTemplate | string, context?: { nitro?: boolean, nuxt?: boolean }): ResolvedNuxtTemplate

参数

template: 模板对象或包含模板路径的字符串。如果提供字符串，将转换为模板对象，并将 src 设置为该字符串值。如果提供模板对象，则必须具有以下属性：

属性类型必需描述
srcstringfalse模板的路径。如果未提供 src，则必须提供 getContents。
filenamestringfalse模板的文件名。如果未提供 filename，将根据 src 路径生成。在这种情况下，src 选项是必需的。
dststringfalse目标文件的路径。如果未提供 dst，将根据 filename 路径和 Nuxt 的 buildDir 选项生成。
optionsOptionsfalse传递给模板的选项。
getContents(data: Options) => string | Promise<string>false一个函数，将接收 options 对象作为参数。它应返回字符串或解析为字符串的 Promise。如果提供了 src，此函数将被忽略。

context: 可选的上下文对象，用于控制类型的添加位置。如果省略，类型将仅添加到 Nuxt 上下文中。此对象支持以下属性：

属性类型必需描述
nuxtbooleanfalse如果设置为 true，类型将添加到 Nuxt 上下文中。
nitrobooleanfalse如果设置为 true，类型将添加到 Nitro 上下文中。

示例

将类型模板添加到 Nitro 上下文

默认情况下，addTypeTemplate 仅将类型声明添加到 Nuxt 上下文中。要同时将它们添加到 Nitro 上下文中，请将 nitro 设置为 true。

import { addTypeTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addTypeTemplate({
      filename: 'types/auth.d.ts',
      getContents: () => `declare module '#auth-utils' {
  interface User {
    id: string;
    name: string;
  }

}`,
    }, {
      nitro: true,
    })
  },
})

这允许在 Nitro 上下文中使用 #auth-utils 模块。

server/api/auth.ts
import type { User } from '#auth-utils'

export default eventHandler(() => {
  const user: User = {
    id: '123',
    name: 'John Doe',
  }

  // 对用户进行某些操作

  return user
})

addServerTemplate

添加一个可在 Nuxt Nitro 服务器构建中使用的虚拟文件。

使用

import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addServerTemplate({
      filename: '#my-module/test.mjs',
      getContents () {
        return 'export const test = 123'
      },
    })
  },
})

类型

function addServerTemplate (template: NuxtServerTemplate): NuxtServerTemplate

参数

template: 模板对象，必须具有以下属性：

属性类型必需描述
filenamestringtrue模板的文件名。
getContents() => string | Promise<string>true一个函数，将接收 options 对象作为参数。它应返回字符串或解析为字符串的 Promise。

示例

为 Nitro 创建虚拟文件

在此示例中，我们创建了一个可在 Nuxt Nitro 服务器构建中使用的虚拟文件。

import { addServerTemplate, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addServerTemplate({
      filename: '#my-module/test.mjs',
      getContents () {
        return 'export const test = 123'
      },
    })
  },
})

然后在运行时文件中：

server/api/test.ts
import { test } from '#my-module/test.js'

export default eventHandler(() => {
  return test
})

updateTemplates

重新生成与过滤器匹配的模板。如果未提供过滤器，将重新生成所有模板。

使用

import { defineNuxtModule, updateTemplates } from '@nuxt/kit'
import { resolve } from 'pathe'

export default defineNuxtModule({
  setup (options, nuxt) {
    const updateTemplatePaths = [
      resolve(nuxt.options.srcDir, 'pages'),
    ]
    // 当页面发生更改时，监听并重新构建路由模板列表
    nuxt.hook('builder:watch', async (event, relativePath) => {
      if (event === 'change') { return }

      const path = resolve(nuxt.options.srcDir, relativePath)
      if (updateTemplatePaths.some(dir => path.startsWith(dir))) {
        await updateTemplates({
          filter: template => template.filename === 'routes.mjs',
        })
      }
    })
  },
})

类型

async function updateTemplates (options: UpdateTemplatesOptions): void

参数

options: 传递给模板的选项。此对象可以具有以下属性：

属性类型必需描述
filter(template: ResolvedNuxtTemplate) => booleanfalse一个函数，将接收 template 对象作为参数。它应返回一个布尔值，指示是否应重新生成该模板。如果未提供 filter，将重新生成所有模板。