defineNuxtPlugin

源码
defineNuxtPlugin() 是一个用于创建 Nuxt 插件的辅助函数。

defineNuxtPlugin 是一个用于创建 Nuxt 插件的辅助函数，提供增强的功能和类型安全。该工具将不同的插件格式规范化为一个一致的结构，可以无缝地在 Nuxt 的插件系统中工作。

plugins/hello.ts
export default defineNuxtPlugin((nuxtApp) => {
  // 使用 nuxtApp 做一些操作
})
Read more in Docs > Guide > Directory Structure > Plugins#creating Plugins.

类型

defineNuxtPlugin<T extends Record<string, unknown>>(plugin: Plugin<T> | ObjectPlugin<T>): Plugin<T> & ObjectPlugin<T>

type Plugin<T> = (nuxt: [NuxtApp](/docs/guide/going-further/internals#the-nuxtapp-interface)) => Promise<void> | Promise<{ provide?: T }> | void | { provide?: T }

interface ObjectPlugin<T> {
  name?: string
  enforce?: 'pre' | 'default' | 'post'
  dependsOn?: string[]
  order?: number
  parallel?: boolean
  setup?: Plugin<T>
  hooks?: Partial<[RuntimeNuxtHooks](/docs/api/advanced/hooks#app-hooks-runtime)>
  env?: {
    islands?: boolean
  }
}

参数

plugin：插件可通过两种方式定义：

  1. 函数插件：一个接收 NuxtApp 实例的函数，可以返回一个 Promise，里面包含可能带有 provide 属性的对象，如果你想要为 NuxtApp 实例提供一个助手函数。
  2. 对象插件：一个包含多种属性的对象，用于配置插件的行为，例如 name、enforce、dependsOn、order、parallel、setup、hooks 和 env。
属性名类型是否必需描述
namestring否插件的可选名称，有助于调试和依赖管理。
enforce'pre' | 'default' | 'post'否控制插件相对于其他插件的运行时机。
dependsOnstring[]否当前插件依赖的其他插件名称数组。确保执行顺序正确。
ordernumber否允许对插件顺序进行更细粒度的控制，仅供高级用户使用。它会覆盖 enforce 的值，并用于插件排序。
parallelboolean否是否与其他并行插件同时执行。
setupPlugin<T>否主要的插件函数，相当于函数插件。
hooksPartial<RuntimeNuxtHooks>否直接注册的 Nuxt 应用运行时钩子。
env{ islands?: boolean }否如果不希望插件在仅服务端渲染或 island 组件渲染时执行，可将此值设为 false。

示例

基本用法

以下示例展示了一个简单的插件，添加了全局功能：

plugins/hello.ts
export default defineNuxtPlugin((nuxtApp) => {
  // 添加全局方法
  return {
    provide: {
      hello: (name: string) => `Hello ${name}!`
    }
  }
})

对象语法插件

以下示例展示了带有高级配置的对象语法写法：

plugins/advanced.ts
export default defineNuxtPlugin({
  name: 'my-plugin',
  enforce: 'pre',
  async setup (nuxtApp) {
    // 插件的设置逻辑
    const data = await $fetch('/api/config')
    
    return {
      provide: {
        config: data
      }
    }
  },
  hooks: {
    'app:created'() {
      console.log('App created!')
    }
  },
})