插件

Nuxt Kit 提供了一组工具来帮助您创建和使用插件。您可以使用这些功能将插件或插件模板添加到您的模块中。

插件是自足的代码，通常为 Vue 应用程序添加应用级功能。在 Nuxt 中，插件会从 plugins/ 目录自动导入。不过，如果您需要将插件与模块一起发布，Nuxt Kit 提供了 addPlugin 和 addPluginTemplate 方法。这些工具可以让您自定义插件配置，以更好地满足您的需求。

`addPlugin`

注册一个 Nuxt 插件并将其添加到插件数组中。

观看关于 addPlugin 的 Vue School 视频。

用法

import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

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

    addPlugin({
      src: resolve('runtime/plugin.js'),
      mode: 'client',
    })
  },
})

类型

function addPlugin(plugin: NuxtPlugin | string, options?: AddPluginOptions): NuxtPlugin

参数

plugin: 插件对象或包含插件路径的字符串。如果提供一个字符串，它将被转换为一个插件对象，src 设置为字符串值。

如果提供一个插件对象，则必须具有以下属性：

属性	类型	是否必需	描述
`src`	`string`	`true`	插件文件的路径。
`mode`	`'all' \| 'server' \| 'client'`	`false`	如果设置为 `'all'`，插件将包含在客户端和服务器的打包中。如果设置为 `'server'`，插件将仅包含在服务器打包中。如果设置为 `'client'`，插件将仅包含在客户端打包中。您还可以在指定 `src` 选项时使用 `.client` 和 `.server` 修饰符，仅在客户端或服务器端使用插件。
`order`	`number`	`false`	插件的顺序。这允许更精细地控制插件的顺序，并应仅由高级用户使用。较小的数字优先运行，用户插件默认值为 `0`。建议将 `order` 设置为 `-20` 范围的数字用于 `pre`-插件（在 Nuxt 插件之前运行的插件）和 `20` 范围的数字用于 `post`-插件（在 Nuxt 插件之后运行的插件）。

避免不必要地使用 order。如果您只是需要在 Nuxt 默认值后注册插件，请使用 append。

options: 可选对象，具有以下属性：

属性	类型	是否必需	描述
`append`	`boolean`	`false`	如果为 `true`，插件将附加到插件数组中。如果为 `false`，则插件将被预置。默认值为 `false`。

示例

import { addPlugin, createResolver, defineNuxtModule } from '@nuxt/kit'

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

    addPlugin({
      src: resolve('runtime/plugin.js'),
      mode: 'client',
    })
  },
})

export default defineNuxtPlugin((nuxtApp) => {
  const colorMode = useColorMode()

  nuxtApp.hook('app:mounted', () => {
    if (colorMode.preference !== 'dark') {
      colorMode.preference = 'dark'
    }
  })
})

`addPluginTemplate`

添加一个模板并将其注册为 Nuxt 插件。这对于构建时需要生成代码的插件非常有用。

观看关于 addPluginTemplate 的 Vue School 视频。

用法

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

export default defineNuxtModule({
  setup (options) {
    addPluginTemplate({
      filename: 'module-plugin.mjs',
      getContents: () => `import { defineNuxtPlugin } from '#app/nuxt'
export default defineNuxtPlugin({
  name: 'module-plugin',
  setup (nuxtApp) {
    ${options.log ? 'console.log("插件安装")' : ''}
  }
})`,
    })
  },
})

类型

function addPluginTemplate(pluginOptions: NuxtPluginTemplate, options?: AddPluginOptions): NuxtPlugin

参数

pluginOptions: 插件模板对象，具有以下属性：

属性	类型	是否必需	描述
`src`	`string`	`false`	模板的路径。如果未提供 `src`，则必须提供 `getContents`。
`filename`	`string`	`false`	模板的文件名。如果未提供 `filename`，则将根据 `src` 路径生成。在这种情况下，`src` 选项是必需的。
`dst`	`string`	`false`	目标文件的路径。如果未提供 `dst`，则将根据 `filename` 路径和 nuxt `buildDir` 选项生成。
`mode`	`'all' \| 'server' \| 'client'`	`false`	如果设置为 `'all'`，插件将包含在客户端和服务器的打包中。如果设置为 `'server'`，插件将仅包含在服务器打包中。如果设置为 `'client'`，插件将仅包含在客户端打包中。您还可以在指定 `src` 选项时使用 `.client` 和 `.server` 修饰符，仅在客户端或服务器端使用插件。
`options`	`Record<string, any>`	`false`	传递给模板的选项。
`getContents`	`(data: Record<string, any>) => string \| Promise<string>`	`false`	一个将使用 `options` 对象调用的函数。它应返回一个字符串或一个解析为字符串的承诺。如果提供了 `src`，则此函数将被忽略。
`write`	`boolean`	`false`	如果设置为 `true`，模板将写入目标文件。否则，模板仅将在虚拟文件系统中使用。
`order`	`number`	`false`	插件的顺序。这允许更精细地控制插件的顺序，并应仅由高级用户使用。较小的数字优先运行，用户插件默认值为 `0`。建议将 `order` 设置为 `-20` 范围的数字用于 `pre`-插件（在 Nuxt 插件之前运行的插件）和 `20` 范围的数字用于 `post`-插件（在 Nuxt 插件之后运行的插件）。

优先使用 getContents 进行动态插件生成。避免不必要地设置 order。

options: 可选对象，具有以下属性：

属性	类型	是否必需	描述
`append`	`boolean`	`false`	如果为 `true`，插件将附加到插件数组中。如果为 `false`，则插件将预置。默认值为 `false`。

示例

生成具有不同选项的插件模板

当您需要在构建时动态生成插件代码时，请使用 addPluginTemplate。这允许您根据传递给它的选项生成不同的插件内容。例如，Nuxt 内部使用此功能来生成 Vue 应用程序配置。

module.ts

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

export default defineNuxtModule({
  setup (_, nuxt) {
    if (nuxt.options.vue.config && Object.values(nuxt.options.vue.config).some(v => v !== null && v !== undefined)) {
      addPluginTemplate({
        filename: 'vue-app-config.mjs',
        write: true,
        getContents: () => `import { defineNuxtPlugin } from '#app/nuxt'
export default defineNuxtPlugin({
  name: 'nuxt:vue-app-config',
  enforce: 'pre',
  setup (nuxtApp) {
    ${Object.keys(nuxt.options.vue.config!)
        .map(k => `nuxtApp.vueApp.config[${JSON.stringify(k)}] = ${JSON.stringify(nuxt.options.vue.config![k as 'idPrefix'])}`)
        .join('\n')
    }
  }
})`,
      })
    }
  },
})

这将根据提供的配置生成不同的插件代码。

export default defineNuxtConfig({
  vue: {
    config: {
      idPrefix: 'nuxt',
    },
  },
})

import { defineNuxtPlugin } from '#app/nuxt'
export default defineNuxtPlugin({
  name: 'nuxt:vue-app-config',
  enforce: 'pre',
  setup (nuxtApp) {
    nuxtApp.vueApp.config["idPrefix"] = "nuxt"
  }
})

使用 EJS 模板生成插件

您还可以使用 EJS 模板生成您的插件。选项可以通过 options 属性传递，然后在 EJS 模板内使用，以生成插件内容。

import { addPluginTemplate, createResolver, defineNuxtModule } from '@nuxt/kit'

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

    addPluginTemplate({
      src: resolve('templates/plugin.ejs'),
      filename: 'plugin.mjs',
      options: {
        ssr: nuxt.options.ssr,
      },
    })
  },
})

import { VueFire, useSSRInitialState } from 'vuefire'
import { defineNuxtPlugin } from '#imports'

export default defineNuxtPlugin((nuxtApp) => {
  const firebaseApp = nuxtApp.$firebaseApp
  nuxtApp.vueApp.use(VueFire, { firebaseApp })

  <% if(options.ssr) { %>
  if (import.meta.server) {
    nuxtApp.payload.vuefire = useSSRInitialState(undefined, firebaseApp)
  } else if (nuxtApp.payload?.vuefire) {
    useSSRInitialState(nuxtApp.payload.vuefire, firebaseApp)
  }
  <% } %>
})

如果您将 compatibilityVersion 设置为 4，Nuxt 默认将不再使用 lodash.template 来编译模板。您仍然可以通过 experimental.compileTemplate 选项启用它，但对 EJS 模板的支持将在下一个主要版本中完全移除。

报告问题或者在 GitHub 上编辑此页面

布局

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

生命周期钩子

Nuxt 提供了一个强大的钩子系统，通过钩子来扩展几乎每一个方面。