模板

原始檔
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 選項生成。
options選項false要傳遞給模板的選項。
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-expect-error - virtual file
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 選項生成。
options選項false要傳遞給模板的選項。
getContents(data: Options) => string | Promise<string>false一個將使用 options 物件呼叫的函式。它應該返回一個字串或解析為字串的 Promise。如果提供了 src，此函式將被忽略。

context：可以傳遞可選的上下文物件以控制新增型別的位置。如果省略，型別將僅新增到 Nuxt 上下文。此物件支援以下屬性：

屬性型別必需描述
nuxtbooleanfalse如果設定為 true，則該型別將新增到 Nuxt 上下文。
nitrobooleanfalse如果設定為 true，則該型別將新增到 Nitro 上下文。

示例

將型別模板新增到 Nitro 上下文

預設情況下，－－僅將型別宣告新增到 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',
  }

  // do something with the user

  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'),
    ]
    // watch and rebuild routes template list when one of the pages changes
    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，則所有模板都將重新生成。