不灭的焱

革命尚未成功，同志仍须努力 下载Go 下载Java

【vue3】app.use() 插件开发及使用教程 举例
作者：AlbertWen  添加时间：2026-02-03 11:31:23  修改时间：2026-02-04 22:33:18  分类：06.前端/Vue/Node.js  编辑

Vue3 插件是扩展应用全局能力的核心方式，可实现全局组件、指令(即事件，如onfocus)、原型方法、全局属性等功能的封装，一次注册全应用生效。本文从插件开发规范、2 类核心实战案例、完整使用流程、进阶技巧四个维度讲解，兼顾基础与实用，案例可直接复用。

一、Vue3 插件核心规范

Vue3 插件必须满足以下任一格式（app.use() 会自动识别执行），核心是通过 install 方法完成插件初始化，该方法会在 app.use() 调用时执行：

  1. 对象格式（推荐）：包含 install 方法，方法接收两个参数：app（Vue3 应用实例）、options（插件使用时传入的配置参数，可选）。
  2. 函数格式：函数本身直接作为 install 方法，参数与上述一致（适合简单插件）。

核心原则：插件的所有全局能力，都要在 install 方法中通过 app 实例注册，确保挂载后全应用可用。

二、实战案例 1：基础通用插件（封装全局指令 + 全局属性）

开发一个基础插件 myPlugin，实现两个常用功能：

  • 全局指令 v-focus：页面加载时自动聚焦输入框；
  • 全局属性 $sayHello：全应用可调用的通用方法，支持自定义问候语。

步骤 1：开发插件（新建文件 src/plugins/myPlugin.js）

// 定义Vue3插件（对象格式，推荐）
const myPlugin = {
  // 核心install方法：注册插件的所有全局能力
  install(app, options) {
    // 1. 注册全局指令 v-focus：自动聚焦输入框
    app.directive('focus', {
      // 指令的mounted钩子：元素挂载后执行
      mounted(el) {
        // 只对输入框/文本域生效
        if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
          el.focus()
        }
      }
    })

    // 2. 注册全局属性 $sayHello：全应用组件可通过this.$sayHello调用（选项式API）
    // options是插件使用时传入的配置，可自定义默认值
    const defaultName = options?.defaultName || 'Vue开发者'
    app.config.globalProperties.$sayHello = (name = defaultName) => {
      console.log(`你好，${name}！这是Vue3插件的全局方法~`)
      alert(`你好，${name}！这是Vue3插件的全局方法~`)
    }
  }
}

// 导出插件，供应用注册使用
export default myPlugin

步骤 2：在 Vue3 应用中注册插件（入口文件 src/main.js）

插件注册必须在 app.mount('#app') 之前完成，否则全局能力无法生效，这是 Vue3 插件使用的核心顺序要求。

import { createApp } from 'vue'
import App from './App.vue'
// 导入自定义插件
import myPlugin from './plugins/myPlugin'

// 创建Vue3应用实例
const app = createApp(App)

// 注册插件：app.use(插件名, 配置参数)
// 第二个参数是自定义配置，会传递给插件的install方法的options参数
app.use(myPlugin, {
  defaultName: 'Vue3插件学习者' // 自定义全局方法的默认问候名
})

// 最后挂载应用（必须在插件注册之后）
app.mount('#app')

步骤 3：在组件中使用插件的全局能力

支持选项式 API和组合式 API（<script setup>） 两种方式，覆盖 Vue3 主流开发场景。

方式 1：选项式 API 组件（src/components/TestPlugin1.vue）

<template>
  <div>
    <!-- 使用插件的全局指令 v-focus -->
    <input v-focus type="text" placeholder="自动聚焦的输入框" />
    <button @click="callGlobalMethod">调用插件的全局方法</button>
  </div>
</template>

<script>
export default {
  methods: {
    callGlobalMethod() {
      // 调用插件注册的全局属性 $sayHello
      this.$sayHello() // 使用插件配置的默认名
      // this.$sayHello('张三') // 自定义名称
    }
  }
}
</script>

方式 2：组合式 API（<script setup>，src/components/TestPlugin2.vue）

组合式 API 中无法直接通过 this 访问全局属性，需通过 Vue3 提供的 getCurrentInstance 方法获取应用实例，进而调用全局属性。

<template>
  <div>
    <input v-focus type="text" placeholder="组合式API-自动聚焦" />
    <button @click="callGlobalMethod">组合式API-调用全局方法</button>
  </div>
</template>

<script setup>
// 导入组合式API的实例获取方法
import { getCurrentInstance } from 'vue'

// 获取当前组件的应用实例（proxy是代理对象，避免直接操作实例）
const { proxy } = getCurrentInstance()

// 调用插件的全局方法
const callGlobalMethod = () => {
  proxy.$sayHello('组合式API使用者')
}
</script>

三、实战案例 2：实用插件（封装全局组件 + 原型方法）

开发一个更实用的插件 uiPlugin，封装全局通用组件（如全局按钮 MyButton）和全局原型方法（如时间格式化 $formatTime），适合项目中通用 UI 和工具方法的封装。

步骤 1：开发插件（新建目录 src/plugins/uiPlugin/，分文件管理更规范）

子步骤 1.1：开发全局组件（src/plugins/uiPlugin/MyButton.vue）

<template>
  <button 
    class="my-button" 
    :style="{ backgroundColor: color, padding: '8px 16px', border: 'none', color: '#fff', borderRadius: '4px' }"
    @click="$emit('click')"
  >
    <slot></slot> <!-- 插槽支持自定义按钮文本 -->
  </button>
</template>

<script setup>
// 定义组件props，支持外部传参
defineProps({
  color: {
    type: String,
    default: '#42b983' // Vue默认主题色
  }
})
// 定义组件事件
defineEmits(['click'])
</script>

子步骤 1.2：编写插件核心逻辑（src/plugins/uiPlugin/index.js）

// 导入要封装的全局组件
import MyButton from './MyButton.vue'

// 定义实用插件（对象格式）
const uiPlugin = {
  install(app, options) {
    // 1. 注册全局组件：app.component(组件名, 组件对象)，全应用可直接使用<MyButton/>
    app.component('MyButton', MyButton)

    // 2. 注册全局原型方法：$formatTime 时间格式化（默认YYYY-MM-DD，支持自定义格式）
    app.config.globalProperties.$formatTime = (time, format = 'YYYY-MM-DD') => {
      if (!time) return ''
      const date = new Date(time)
      const year = date.getFullYear()
      const month = String(date.getMonth() + 1).padStart(2, '0')
      const day = String(date.getDate()).padStart(2, '0')
      const hours = String(date.getHours()).padStart(2, '0')
      const minutes = String(date.getMinutes()).padStart(2, '0')
      
      // 根据传入的格式返回对应结果
      if (format === 'YYYY-MM-DD HH:mm') {
        return `${year}-${month}-${day} ${hours}:${minutes}`
      }
      return `${year}-${month}-${day}`
    }
  }
}

// 导出插件
export default uiPlugin

步骤 2：注册插件（入口文件 src/main.js，可同时注册多个插件）

import { createApp } from 'vue'
import App from './App.vue'
import myPlugin from './plugins/myPlugin'
// 导入新的实用插件
import uiPlugin from './plugins/uiPlugin'

const app = createApp(App)

// 注册第一个插件
app.use(myPlugin, { defaultName: 'Vue3插件学习者' })
// 注册第二个插件（无配置参数可省略第二个参数）
app.use(uiPlugin)

// 挂载应用（始终在最后）
app.mount('#app')

步骤 3：在组件中使用实用插件的能力

<template>
  <div class="plugin-demo">
    <!-- 1. 使用插件的全局组件 MyButton，支持传参color -->
    <MyButton color="#2196f3" @click="handleButtonClick">全局组件-蓝色按钮</MyButton>
    <MyButton style="margin-left: 10px" @click="formatCurrentTime">格式化时间</MyButton>

    <!-- 2. 同时使用第一个插件的全局指令 -->
    <input v-focus type="text" placeholder="同时使用多个插件的能力" style="margin-top: 20px" />
  </div>
</template>

<script setup>
import { getCurrentInstance } from 'vue'
const { proxy } = getCurrentInstance()

// 点击全局组件按钮
const handleButtonClick = () => {
  // 调用第一个插件的全局方法
  proxy.$sayHello('全局组件使用者')
}

// 格式化当前时间
const formatCurrentTime = () => {
  // 调用第二个插件的时间格式化方法
  const now = proxy.$formatTime(new Date(), 'YYYY-MM-DD HH:mm')
  alert(`当前时间：${now}`)
  console.log(`当前时间：${now}`)
}
</script>

四、插件使用的核心注意事项

  1. 注册顺序：所有插件的 app.use() 必须在 app.mount('#app') 之前执行，否则插件的全局能力（指令、组件、属性）无法被 Vue 应用识别，导致失效。
  2. 全局属性访问：
    • 选项式 API：直接通过 this.$xxx 调用（如 this.$sayHello）；
    • 组合式 API（<script setup>）：需通过 getCurrentInstance().proxy.$xxx 调用，禁止直接操作 getCurrentInstance() 返回的原始实例（避免跨版本兼容问题）。
  3. 配置参数传递：app.use(plugin, options) 的第二个参数 options 会直接传递给插件的 install(app, options) 方法，可用于插件的个性化配置（如默认值、开关等）。
  4. 插件复用性：插件内部不要依赖项目具体业务逻辑，保持通用性（如工具方法、通用 UI、全局指令），这样可在多个 Vue3 项目中复用。

五、进阶技巧：函数式插件（适合简单场景）

对于功能简单的插件，可直接使用函数格式（函数本身作为 install 方法），省略对象包裹，简化代码。

示例：开发一个简单的防抖插件 debouncePlugin.js

// 函数式插件：直接将函数作为install方法
export default function (app) {
  // 注册全局防抖方法 $debounce
  app.config.globalProperties.$debounce = (fn, delay = 300) => {
    let timer = null
    return (...args) => {
      clearTimeout(timer)
      timer = setTimeout(() => {
        fn.apply(this, args)
      }, delay)
    }
  }
}

注册与使用：

// main.js 注册
import debouncePlugin from './plugins/debouncePlugin'
app.use(debouncePlugin)

// 组件中使用（组合式API）
const { proxy } = getCurrentInstance()
const search = proxy.$debounce((keyword) => {
  console.log('搜索：', keyword)
}, 500)

六、完整流程总结

插件开发流程

  1. 新建插件文件 / 目录，按对象格式（推荐） 或函数格式定义插件；
  2. 在 install 方法中通过 app 实例注册全局能力（app.directive/app.component/app.config.globalProperties）；
  3. 导出插件对象 / 函数。

插件使用流程

  1. 在入口文件 main.js 中导入插件；
  2. 调用 app.use(插件名, 配置参数) 注册插件（必须在 app.mount() 之前）；
  3. 在任意组件中直接使用插件提供的全局指令、组件、方法 / 属性。

七、扩展：Vue3 常用内置注册方法（插件开发必备）

在插件的 install 方法中，通过 app 实例可注册以下全局能力，覆盖绝大多数插件开发场景：

方法 作用 示例
app.directive(name, directive) 注册全局指令 app.directive('focus', { mounted: el => el.focus() })
app.component(name, component) 注册全局组件 app.component('MyButton', MyButton)
app.config.globalProperties.$xxx 注册全局属性 / 方法 app.config.globalProperties.$formatTime = () => {}
app.provide(key, value) 全局依赖注入 app.provide('theme', 'light')（组件中用 inject 获取）

通过以上教程，你可以轻松开发 Vue3 自定义插件，实现项目的全局能力封装与复用，提升开发效率和代码可维护性。上述案例均可直接复制到 Vue3 项目中运行，根据实际业务需求修改即可。

Copyright © 2012-2035 不灭的焱 版权所有 粤ICP备17073848号