Modules
title: "模块"\ndescription: Nuxt Kit 提供了一组工具,帮助你创建和使用模块。你可以使用这些工具来创建自己的模块或重用现有的模块。\nlinks:
title: "模块" description: Nuxt Kit 提供了一组工具,帮助你创建和使用模块。你可以使用这些工具来创建自己的模块或重用现有的模块。 links:
- label: 源代码 icon: i-simple-icons-github to: https://github.com/nuxt/nuxt/blob/main/packages/kit/src/module size: xs
模块是 Nuxt 的构建基石。Kit 提供了一组工具,帮助你创建和使用模块。你可以使用这些工具来创建自己的模块或重用现有的模块。例如,你可以使用 defineNuxtModule
函数来定义一个模块,以及 installModule
函数以编程方式安装模块。
defineNuxtModule
定义一个 Nuxt 模块,自动将默认值与用户提供的选项合并,安装提供的任何钩子,并调用可选的 setup 函数以实现完全控制。
用法
import { defineNuxtModule } from '@nuxt/kit'
export default defineNuxtModule({
meta: {
name: 'my-module',
configKey: 'myModule'
},
defaults: {
enabled: true
},
setup (options) {
if (options.enabled) {
console.log('我的 Nuxt 模块已启用!')
}
}
})
类型
export function defineNuxtModule<TOptions extends ModuleOptions> (
definition?: ModuleDefinition<TOptions, Partial<TOptions>, false> | NuxtModule<TOptions, Partial<TOptions>, false>,
): NuxtModule<TOptions, TOptions, false>
参数
definition: 模块定义对象或模块函数。模块定义对象应包含以下属性:
属性 | 类型 | 是否必须 | 描述 |
---|---|---|---|
meta | ModuleMeta | false | 模块的元数据。定义模块名称、版本、配置键和兼容性。 |
defaults | T | ((nuxt: Nuxt) => T) | false | 模块的默认选项。如果提供的是函数,则会以 Nuxt 实例作为第一个参数调用该函数。 |
schema | T | false | 模块选项的模式。如果提供,选项将应用于该模式。 |
hooks | Partial<NuxtHooks> | false | 为模块安装的钩子。如果提供,模块将安装这些钩子。 |
setup | (this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupInstallResult> | false | 模块的设置函数。如果提供,模块将调用该设置函数。 |
示例
使用 configKey
使模块可配置
在定义 Nuxt 模块时,你可以设置一个 configKey
来指定用户在 nuxt.config
中如何配置该模块。
import { defineNuxtModule } from '@nuxt/kit'
export default defineNuxtModule({
meta: {
name: 'my-module',
configKey: 'myModule'
},
defaults: {
// 模块选项
enabled: true
},
setup (options) {
if (options.enabled) {
console.log('我的 Nuxt 模块已启用!')
}
}
})
用户可以在 nuxt.config
中使用对应的键为该模块提供选项。
export default defineNuxtConfig({
myModule: {
enabled: false
}
})
定义模块兼容性要求
如果你正在开发一个 Nuxt 模块并使用仅在特定 Nuxt 版本中支持的 API,强烈建议包含 compatibility.nuxt
。
export default defineNuxtModule({
meta: {
name: '@nuxt/icon',
configKey: 'icon',
compatibility: {
// 所需的 Nuxt 版本,采用 semver 格式
nuxt: '>=3.0.0', // 或使用 '^3.0.0'
},
},
async setup() {
const resolver = createResolver(import.meta.url)
// 实现
},
})
如果用户尝试使用与 Nuxt 版本不兼容的模块,他们将在控制台中收到警告。
WARN 由于兼容性问题,模块 @nuxt/icon 已被禁用:
- [nuxt] 需要 Nuxt 版本 ^3.1.0,但当前使用的是 3.0.0
installModule
以编程方式安装指定的 Nuxt 模块。当你的模块依赖其他模块时,这非常有用。你可以将模块选项作为对象传递给 inlineOptions
,它们将被传递到模块的 setup
函数。
用法
import { defineNuxtModule, installModule } from '@nuxt/kit'
export default defineNuxtModule({
async setup () {
// 将安装 @nuxtjs/fontaine,带有 Roboto 字体和 Impact 回退
await installModule('@nuxtjs/fontaine', {
// 模块配置
fonts: [
{
family: 'Roboto',
fallbacks: ['Impact'],
fallbackName: 'fallback-a',
}
]
})
}
})
类型
async function installModule (moduleToInstall: string | NuxtModule, inlineOptions?: any, nuxt?: Nuxt)
参数
属性 | 类型 | 是否必须 | 描述 |
---|---|---|---|
moduleToInstall | string | NuxtModule | true | 要安装的模块。可以是模块名称的字符串或模块对象本身。 |
inlineOptions | any | false | 传递给模块 setup 函数的模块选项对象。 |
nuxt | Nuxt | false | Nuxt 实例。如果未提供,将通过 useNuxt() 调用从上下文中获取。 |
示例
import { defineNuxtModule, installModule } from '@nuxt/kit'
export default defineNuxtModule({
async setup (options, nuxt) {
// 将安装 @nuxtjs/fontaine,带有 Roboto 字体和 Impact 回退
await installModule('@nuxtjs/fontaine', {
// 模块配置
fonts: [
{
family: 'Roboto',
fallbacks: ['Impact'],
fallbackName: 'fallback-a',
}
]
})
}
})