插件
Nuxt Kit 提供了一组实用工具,帮助您创建和使用插件。您可以使用这些函数向模块添加插件或插件模板。
插件是自包含的代码,通常为 Vue 添加应用级功能。在 Nuxt 中,插件会自动从 plugins/
目录导入。然而,如果您需要随模块一起提供插件,Nuxt Kit 提供了 addPlugin
和 addPluginTemplate
方法。这些实用工具允许您自定义插件配置以更好地满足您的需求。
addPlugin
注册一个 Nuxt 插件并将其添加到插件数组中。
使用
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 (用于在 Nuxt 插件之前运行的 pre 插件)到 20 (用于在 Nuxt 插件之后运行的 post 插件)之间的数字。 |
除非必要,避免使用
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 插件。这对于需要在构建时生成代码的插件非常有用。
使用
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' ,插件将包含在客户端和服务端捆绑包中。如果设置为 'server' ,插件仅包含在服务端捆绑包中。如果设置为 'client' ,插件仅包含在客户端捆绑包中。您还可以在指定 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 (用于在 Nuxt 插件之前运行的 pre 插件)到 20 (用于在 Nuxt 插件之后运行的 post 插件)之间的数字。 |
优先使用
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 模板的支持将在下一个主要版本中完全移除。