插件

Nuxt Kit 提供了一组实用程序来帮助你创建和使用插件。你可以使用这些函数向模块添加插件或插件模板。

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

¥Plugins are self-contained code that usually add app-level functionality to Vue. In Nuxt, plugins are automatically imported from the plugins directory. However, if you need to ship a plugin with your module, Nuxt Kit provides the addPlugin and addPluginTemplate methods. These utils allow you to customize the plugin configuration to better suit your needs.

`addPlugin`

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

¥Registers a Nuxt plugin and to the plugins array.

观看 Vue School 视频，了解 addPlugin。¥Watch Vue School video about addPlugin.

类型

¥Type

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

interface NuxtPlugin {
  src: string
  mode?: 'all' | 'server' | 'client'
  order?: number
}

interface AddPluginOptions { append?: boolean }

参数

¥Parameters

`plugin`

类型：NuxtPlugin | string

¥Type: NuxtPlugin | string

必需：true

¥Required: true

插件对象或包含插件路径的字符串。如果提供了字符串，它将被转换为插件对象，并将 src 设置为该字符串值。如果提供了插件对象，它必须具有以下属性：

¥A plugin object or a string with the path to the plugin. If a string is provided, it will be converted to a plugin object with src set to the string value. If a plugin object is provided, it must have the following properties:

src(必需)
类型：string
插件的路径。
mode（可选）
类型：'all' | 'server' | 'client'
默认：'all'
如果设置为 'all'，该插件将同时包含在客户端和服务器 bundles 中。如果设置为 'server'，该插件将仅包含在服务器 bundles 中。如果设置为 'client'，该插件将仅包含在客户端 bundles 中。在指定 src 选项时，你还可以使用 .client 和 .server 修饰符，以便仅在客户端或服务器端使用插件。
order（可选）
类型：number
默认：0
插件的顺序。这允许对插件顺序进行更精细的控制，仅供高级用户使用。数字较小的优先运行，用户插件默认使用 0。建议将 order 设置为介于 -20（对于 pre 插件，在 Nuxt 插件之前运行）和 20（对于 post 插件，在 Nuxt 插件之后运行）之间的数字。

除非你清楚自己在做什么，否则不要使用 order。目前，你需要在每个选择 Nuxt 4 行为的层中定义兼容版本。要将插件附加到插件数组的末尾，请改用 append 选项。¥Don't use order unless you know what you're doing. For most plugins, the default order of 0 is sufficient. To append a plugin to the end of the plugins array, use the append option instead.

`options`

类型：AddPluginOptions

¥Type: AddPluginOptions

默认：{}

¥Default: {}

传递给插件的选项。如果将 append 设置为 true，则插件将被附加到插件数组中，而不是添加到前面。

¥Options to pass to the plugin. If append is set to true, the plugin will be appended to the plugins array instead of prepended.

示例

¥Examples

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

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

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

// https://github.com/nuxt/nuxters
export default defineNuxtPlugin((nuxtApp) => {
  const colorMode = useColorMode()

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

`addPluginTemplate`

添加模板并注册为 Nuxt 插件。这对于需要在构建时生成代码的插件很有用。

¥Adds a template and registers as a nuxt plugin. This is useful for plugins that need to generate code at build time.

观看 Vue School 的视频，了解如何使用 addPluginTemplate。¥Watch Vue School video about addPluginTemplate.

类型

¥Type

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

interface NuxtPluginTemplate<Options = Record<string, any>> {
  src?: string,
  filename?: string,
  dst?: string,
  mode?: 'all' | 'server' | 'client',
  options?: Options,
  getContents?: (data: Options) => string | Promise<string>,
  write?: boolean,
  order?: number
}

interface AddPluginOptions { append?: boolean }

interface NuxtPlugin {
  src: string
  mode?: 'all' | 'server' | 'client'
  order?: number
}

参数

¥Parameters

`pluginOptions`

类型：NuxtPluginTemplate

¥Type: NuxtPluginTemplate

必需：true

¥Required: true

具有以下属性的插件模板对象：

¥A plugin template object with the following properties:

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