插件

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

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

addPlugin

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

观看关于 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 会设置为该字符串值。

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

属性类型必需描述
srcstringtrue插件文件的路径。
mode'all' | 'server' | 'client'false如果设置为 'all'，插件将包含在客户端和服务端包中。如果设置为 'server'，插件只会包含在服务端包中。如果设置为 'client'，插件只会包含在客户端包中。你也可以在指定 src 时使用 .client 和 .server 修饰符以仅在客户端或服务端使用插件。
ordernumberfalse插件的顺序。此属性允许对插件顺序进行更细粒度的控制，仅应由高级用户使用。较小的数字先运行，用户插件的默认值为 0。建议将 order 设置在 -20（用于 pre 插件，先于 Nuxt 插件运行）到 20（用于 post 插件，晚于 Nuxt 插件运行）之间的数字。
除非必要，否则避免使用 order。如果你只是需要在 Nuxt 默认插件之后注册插件，请使用 append。

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

属性类型必需描述
appendbooleanfalse如果为 true，插件将被追加到 plugins 数组。若为 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',
    })
  },
})

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

类型

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

参数

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

属性类型必需描述
srcstringfalse模板的路径。如果未提供 src，则必须提供 getContents。
filenamestringfalse模板的文件名。如果未提供 filename，它将从 src 路径生成。在这种情况下，src 选项是必需的。
dststringfalse目标文件的路径。如果未提供 dst，它将从 filename 路径和 Nuxt 的 buildDir 选项生成。
mode'all' | 'server' | 'client'false如果设置为 'all'，插件将包含在客户端和服务端包中。如果设置为 'server'，插件只会包含在服务端包中。如果设置为 'client'，插件只会包含在客户端包中。你也可以在指定 src 时使用 .client 和 .server 修饰符以仅在客户端或服务端使用插件。
optionsRecord<string, any>false传递给模板的选项。
getContents(data: Record<string, any>) => string | Promise<string>false一个将使用 options 对象调用的函数。它应该返回一个字符串或返回字符串的 Promise。如果提供了 src，此函数将被忽略。
writebooleanfalse如果设置为 true，模板将被写入目标文件。否则，模板将只用于虚拟文件系统。
ordernumberfalse插件的顺序。此属性允许对插件顺序进行更细粒度的控制，仅应由高级用户使用。较小的数字先运行，用户插件的默认值为 0。建议将 order 设置在 -20（用于 pre 插件，先于 Nuxt 插件运行）到 20（用于 post 插件，晚于 Nuxt 插件运行）之间的数字。
优先使用 getContents 来动态生成插件。除非必要，否则避免设置 order。

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

属性类型必需描述
appendbooleanfalse如果为 true，插件将被追加到 plugins 数组。若为 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',
    },
  },
})