@yeepay/vue-directive-lib

一个专为 Vue 2 和 Vue 3 设计的实用指令库，提供常用的 Vue 自定义指令，帮助开发者提高开发效率。

✨ 特性

• 🚀 双版本支持 - 同时支持 Vue 2 和 Vue 3
• 🔧 自动检测 - 自动检测 Vue 版本并使用对应的安装方式
• 📦 按需引入 - 支持全量引入和按需引入
• 🎯 类型安全 - 提供完整的 TypeScript 支持
• 🛠️ 易于使用 - 简洁的 API 设计，开箱即用
• 🌐 广泛兼容 - 支持 IE9+ 和所有现代浏览器

📦 安装

npm install @yeepay/vue-directive-lib

🚀 快速开始

全量引入

import VueDirectiveLib from '@yeepay/vue-directive-lib'

// Vue 2 - 使用默认配置
Vue.use(VueDirectiveLib)

// Vue 2 - 自定义默认配置
Vue.use(VueDirectiveLib, {
  // 全局配置
  global: {
    // 全局级别的配置
  },
  // 指令特定配置
  debounce: {
    debounceTime: 300,  // 默认防抖时间300ms
    immediate: true     // 默认立即执行
  }
})

// Vue 3 - 使用默认配置
app.use(VueDirectiveLib)

// Vue 3 - 自定义默认配置
app.use(VueDirectiveLib, {
  // 全局配置
  global: {
    // 全局级别的配置
  },
  // 指令特定配置
  debounce: {
    debounceTime: 300,  // 默认防抖时间300ms
    immediate: true     // 默认立即执行
  }
})

注意：库会自动检测 Vue 版本并使用对应的安装方式，无需手动指定版本。

按需引入

import { vDebounce } from '@yeepay/vue-directive-lib'

// Vue 2
Vue.directive('debounce', vDebounce)

// Vue 3
app.directive('debounce', vDebounce)

📚 指令文档

v-debounce 防抖指令

防抖指令用于限制函数的执行频率，避免在短时间内重复触发事件。

基本用法

<template>
  <!-- 基本防抖（默认立即执行） -->
  <button v-debounce:click="handleClick">提交</button>
  
  <!-- 自定义防抖时间 -->
  <input v-debounce:input="handleInput" debounce-time="300">
  
  <!-- 延迟执行模式 -->
  <button v-debounce:click="{ handler: handleClick, immediate: false }">延迟执行</button>
</template>

<script>
export default {
  data() {
    return {
      clickCount: 0
    }
  },
  methods: {
    handleClick() {
      this.clickCount++;
      console.log('按钮被点击，当前次数:', this.clickCount)
    },
    handleInput(event) {
      console.log('输入内容:', event.target.value)
    }
  }
}
</script>

重要提醒：函数传参

⚠️ 注意：如果需要在调用函数时传递参数，必须使用箭头函数包裹，否则函数会立即执行！

<template>
  <!-- ❌ 错误用法：函数会立即执行 -->
  <button v-debounce:click="handleClick('param')">错误示例</button>
  
  <!-- ✅ 正确用法：使用箭头函数包裹 -->
  <button v-debounce:click="() => handleClick('param')">正确示例</button>
  
  <!-- ✅ 正确用法：使用配置对象 -->
  <button v-debounce:click="{ handler: () => handleClick('param') }">配置对象方式</button>
  
  <!-- ✅ 正确用法：传递事件对象 -->
  <button v-debounce:click="(event) => handleClick('param', event)">传递事件对象</button>
</template>

<script>
export default {
  methods: {
    handleClick(param, event) {
      console.log('参数:', param)
      console.log('事件对象:', event)
    }
  }
}
</script>

参数说明

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | event | String | 'click' | 要防抖的事件类型 | | debounce-time | Number | 300 | 防抖时间（毫秒） |

修饰符

| 修饰符 | 说明 | |--------|------| | .数字 | 自定义防抖时间（数字修饰符，如 .300 表示300毫秒） |

高级用法

<template>
  <!-- 对象配置方式 -->
  <button v-debounce:click="{ handler: handleClick, time: 1000 }">
    长防抖按钮
  </button>
  
  <!-- 延迟执行模式 -->
  <button v-debounce:click="{ handler: handleClick, immediate: false }">
    延迟执行按钮
  </button>
  
  <!-- 数据属性配置 -->
  <input 
    v-debounce:input="handleInput" 
    debounce-time="200"
    placeholder="快速输入"
  >
  
  <!-- 带参数的函数调用 -->
  <button v-debounce:click="{ handler: () => handleClick('user', 123), time: 500 }">
    带参数的长防抖按钮
  </button>
  
  <!-- 动态参数传递 -->
  <button 
    v-for="item in items" 
    :key="item.id"
    v-debounce:click="() => handleItemClick(item.id, item.name)"
  >
    {{ item.name }}
  </button>
</template>

<script>
export default {
  data() {
    return {
      items: [
        { id: 1, name: '项目1' },
        { id: 2, name: '项目2' }
      ]
    }
  },
  methods: {
    handleClick(user, id) {
      console.log('用户:', user, 'ID:', id)
    },
    handleInput(event) {
      // 处理输入事件
    },
    handleItemClick(id, name) {
      console.log('点击了项目:', id, name)
    }
  }
}
</script>

配置选项

// 指令值可以是函数或配置对象
v-debounce:click="handleClick"                    // 函数（默认立即执行）
v-debounce:click="{ handler: handleClick }"       // 配置对象（默认立即执行）
v-debounce:click="{ handler: handleClick, time: 1000 }"  // 自定义时间
v-debounce:click="{ handler: handleClick, immediate: false }"  // 延迟执行模式

// 需要传参时，必须使用箭头函数包裹
v-debounce:click="() => handleClick('param')"     // ✅ 正确：箭头函数包裹
v-debounce:click="() => handleClick('param', event)"  // ✅ 正确：传递事件对象
v-debounce:click="{ handler: () => handleClick('param') }"  // ✅ 正确：配置对象中的箭头函数

// ❌ 错误用法：会立即执行
v-debounce:click="handleClick('param')"           // 错误：函数立即执行

执行模式

• 默认模式：立即执行，防抖期间阻止重复触发
• 延迟执行模式：通过 { immediate: false } 配置，延迟到防抖时间结束后执行

防抖时间优先级

防抖时间的设置优先级如下（从高到低）：

1. 数字修饰符 - 如 v-debounce:click.300
2. 配置对象time - 如 v-debounce:click="{ handler: handleClick, time: 1000 }"
3. debounce-time 属性 - 如 debounce-time="300"
4. 指令默认值 - 通过 use() 配置的 debounce.debounceTime
5. 硬编码默认值 - 300毫秒

生命周期

指令会自动处理以下生命周期：

• 绑定/挂载 - 创建防抖处理函数并添加事件监听器
• 更新 - 重新创建防抖处理函数（当配置改变时）
• 解绑/卸载 - 清理事件监听器和定时器

🔧 配置选项

全局配置

// Vue 2
Vue.use(VueDirectiveLib, {
  // 全局配置
  global: {
    // 全局级别的配置，适用于所有指令
  },
  // 指令特定配置
  debounce: {
    debounceTime: 300,    // debounce指令的默认防抖时间
    immediate: true       // debounce指令的默认执行模式
  },
  // 未来其他指令的配置
  // throttle: { ... },
  // clickOutside: { ... }
})

// Vue 3
app.use(VueDirectiveLib, {
  // 全局配置
  global: {
    // 全局级别的配置，适用于所有指令
  },
  // 指令特定配置
  debounce: {
    debounceTime: 300,    // debounce指令的默认防抖时间
    immediate: true       // debounce指令的默认执行模式
  }
})

配置参数说明

全局配置 (global)

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | 待定 | - | - | 全局级别的配置参数 |

debounce 指令配置

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | debounceTime | Number | 300 | 默认防抖时间（毫秒） | | immediate | Boolean | true | 默认执行模式（true为立即执行，false为延迟执行） |

📋 兼容性

Vue 版本支持

| Vue 版本 | 支持状态 | |----------|----------| | Vue 2.x | ✅ 完全支持 | | Vue 3.x | ✅ 完全支持 |

浏览器兼容性

| 浏览器 | 最低版本 | 支持状态 | |--------|----------|----------| | Chrome | 5+ | ✅ 完全支持 | | Firefox | 3.6+ | ✅ 完全支持 | | Safari | 5+ | ✅ 完全支持 | | Edge | 12+ | ✅ 完全支持 | | IE | 9+ | ✅ 完全支持 |

注意：本库使用 Babel 转译，确保在现代浏览器和旧版本浏览器中都能正常运行。所有现代 JavaScript 语法（如可选链操作符、展开运算符等）都会被自动转译为兼容的 ES5 代码。源代码使用现代语法，构建后自动兼容旧版本环境。

🛠️ 开发

构建

npm run build

开发模式

npm run dev

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请通过以下方式联系：

• 提交 Issue
• 发送邮件至：[[email protected]]

注意：本库为 peer dependency，需要项目中已安装 Vue 2.x 或 Vue 3.x。