v3
GitHub

模块

源码
Nuxt Kit 提供了一组实用工具，帮助你创建和使用模块。你可以使用这些工具来创建自己的模块，也可以复用现有模块。

模块是 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：模块定义对象或模块函数。模块定义对象应包含以下属性：

属性类型必须说明
metaModuleMetafalse模块的元数据。定义模块名称、版本、配置键和兼容性。
defaultsT | ((nuxt: Nuxt) => T)false模块的默认选项。如果传入函数，将以 Nuxt 实例作为第一个参数调用该函数。
schemaTfalse模块选项的 schema。如果提供，选项将应用于该 schema。
hooksPartial<NuxtHooks>false要安装的模块钩子。如果提供，模块将安装这些钩子。
setup(this: void, resolvedOptions: T, nuxt: Nuxt) => Awaitable<void | false | ModuleSetupInstallResult>false模块的 setup 函数。如果提供，模块会调用该 setup 函数。

示例

使用 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 模块并且使用的 API 只支持特定 Nuxt 版本，强烈建议包含 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)

参数

属性类型必须说明
moduleToInstallstring | NuxtModuletrue要安装的模块。可以是模块名称的字符串，或模块对象本身。
inlineOptionsanyfalse一个包含传递给模块 setup 函数的模块选项的对象。
nuxtNuxtfalseNuxt 实例。如果未提供，将通过调用 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',
        }
      ]
    })
  }
})