Plugins

Nuxt Kit 提供了一系列工具，帮助你创建和使用插件。你可以使用这些函数向你的模块添加插件或插件模板。

插件是独立的代码，通常会为 Vue 添加应用级的功能。在 Nuxt 中，插件会自动从 app/plugins/ 目录导入。然而，如果你需要随你的模块一起发布一个插件，Nuxt Kit 提供了 addPlugin 和 addPluginTemplate 方法。这些工具允许你自定义插件配置，以更好地满足你的需求。

`addPlugin`

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

观看 Vue School 关于 addPlugin 的视频。 :

用法

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'`，插件会被包含在客户端和服务端 bundle 中。如果设为 `'server'`，插件只会包含在服务端 bundle 中。如果设为 `'client'`，插件只会包含在客户端 bundle 中。你也可以在指定 `src` 选项时使用 `.client` 和 `.server` 修饰符，让插件只在客户端或服务端使用。
`order`	`number`	`false`	插件的顺序。这允许对插件顺序进行更细粒度的控制，应仅由高级用户使用。数字越小越先运行，用户插件的默认顺序为 `0`。建议将 `order` 设为 `-20` 到 `20` 之间的数字，其中 `-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 插件。这对于需要在构建时生成代码的插件很有用。

观看 Vue School 关于 addPluginTemplate 的视频。 :

用法

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("Plugin install")' : ''}
  }
})`,
    })
  },
})

类型

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'`，插件会被包含在客户端和服务端 bundle 中。如果设为 `'server'`，插件只会包含在服务端 bundle 中。如果设为 `'client'`，插件只会包含在客户端 bundle 中。你也可以在指定 `src` 选项时使用 `.client` 和 `.server` 修饰符，让插件只在客户端或服务端使用。
`options`	`Record<string, any>`	`false`	传给模板的选项。
`getContents`	`(data: Record<string, any>) => string \| Promise<string>`	`false`	一个会接收 `options` 对象的函数。它应返回一个字符串，或解析为字符串的 promise。如果提供了 `src`，该函数会被忽略。
`write`	`boolean`	`false`	如果设为 `true`，模板会被写入目标文件。否则，模板仅用于虚拟文件系统。
`order`	`number`	`false`	插件的顺序。这允许对插件顺序进行更细粒度的控制，应仅由高级用户使用。数字越小越先运行，用户插件的默认顺序为 `0`。建议将 `order` 设为 `-20` 到 `20` 之间的数字，其中 `-20` 对应 `pre`-插件（在 Nuxt 插件之前运行），`20` 对应 `post`-插件（在 Nuxt 插件之后运行）。

优先使用 getContents 进行动态插件生成。除非必要，避免使用 order。 :

options：可选对象，包含以下属性：

属性	类型	必填	描述
`append`	`boolean`	`false`	如果为 `true`，插件会被追加到插件数组。如果为 `false`，它会被前置。默认为 `false`。

示例

用不同选项生成插件模板

当你需要在构建时动态生成插件代码时，使用 addPluginTemplate。这允许你根据传给它的选项生成不同的插件内容。例如，Nuxt 内部使用这个函数来生成 Vue app 配置。

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'
  },
})