插件
Nuxt Kit 提供了一组工具来帮助您创建和使用插件。您可以使用这些功能将插件或插件模板添加到您的模块中。
插件是自包含的代码,通常向 Vue 添加应用级功能。在 Nuxt 中,插件会自动从 plugins
目录中导入。但是,如果您需要将插件与模块一起发布,Nuxt Kit 提供了 addPlugin
和 addPluginTemplate
方法。这些工具允许您自定义插件配置,以更好地满足您的需求。
addPlugin
注册一个 Nuxt 插件并添加到插件数组中。
类型
function addPlugin (plugin: NuxtPlugin | string, options: AddPluginOptions): NuxtPlugin
interface NuxtPlugin {
src: string
mode?: 'all' | 'server' | 'client'
order?: number
}
interface AddPluginOptions { append?: boolean }
参数
plugin
类型: NuxtPlugin | string
必需: true
一个插件对象或包含插件路径的字符串。如果提供的是字符串,它将被转换为一个插件对象,并将 src
设置为字符串值。如果提供的是插件对象,它必须具有以下属性:
src
(必需)
类型:string
插件的路径。mode
(可选)
类型:'all' | 'server' | 'client'
默认:'all'
如果设置为'all'
,插件将同时包含在客户端和服务器包中。如果设置为'server'
,插件将仅包含在服务器包中。如果设置为'client'
,插件将仅包含在客户端包中。在指定src
选项时,您还可以使用.client
和.server
修饰符,仅在客户端或服务器端使用插件。order
(可选)
类型:number
默认:0
插件的顺序。这允许更细粒度地控制插件的顺序,并且只应由高级用户使用。较小的数字先运行,用户插件默认为0
。建议将order
设置为介于-20
(pre
插件,在 Nuxt 插件之前运行)和20
(post
插件,在 Nuxt 插件之后运行)之间的数字。
在您知道自己在做什么之前,请勿使用
order
。对于大多数插件,默认的 order
值 0
已足够。要将插件附加到插件数组的末尾,请使用 append
选项。options
类型: AddPluginOptions
默认: {}
传递给插件的选项。如果 append
设置为 true
,则插件将附加到插件数组的末尾,而不是提前。
示例
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 插件。这对于在构建时需要生成代码的插件很有用。
类型
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
}
参数
pluginOptions
类型: NuxtPluginTemplate
必需: true
一个插件模板对象,具有以下属性:
src
(可选)
类型:string
模板的路径。如果未提供src
,则必须提供getContents
。filename
(可选)
类型:string
模板的文件名。如果未提供filename
,将根据src
路径生成。在这种情况下,src
选项是必需的。dst
(可选)
类型:string
目标文件的路径。如果未提供dst
,将根据filename
路径和 nuxt 的buildDir
选项生成。mode
(可选)
类型:'all' | 'server' | 'client'
默认:'all'
如果设置为'all'
,插件将同时包含在客户端和服务器包中。如果设置为'server'
,插件将仅包含在服务器包中。如果设置为'client'
,插件将仅包含在客户端包中。在指定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 插件之后运行)之间的数字。
在您知道自己在做什么之前,请勿使用
order
。对于大多数插件,默认的 order
值 0
已足够。要将插件附加到插件数组的末尾,请使用 append
选项。options
类型: AddPluginOptions
默认: {}
传递给插件的选项。如果 append
设置为 true
,则插件将附加到插件数组的末尾,而不是提前。
示例
// https://github.com/vuejs/vuefire
import { createResolver, defineNuxtModule, addPluginTemplate } from '@nuxt/kit'
export default defineNuxtModule({
setup() {
const resolver = createResolver(import.meta.url)
addPluginTemplate({
src: resolve(templatesDir, 'plugin.ejs'),
filename: 'plugin.mjs',
options: {
...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)
}
<% } %>
})