directives

QXS-BNS 提供了实用的 Vue 3 自定义指令，本指南将帮助你快速上手使用这些指令。

📦 安装

# 安装指令包
pnpm add @qxs-bns/directives

🚀 使用方式

全局注册（推荐）

import { createApp } from 'vue'
import { vDebounce, vWaves, vCopy } from '@qxs-bns/directives'

const app = createApp(App)

// 注册指令
app.directive('debounce', vDebounce)
app.directive('waves', vWaves)
app.directive('copy', vCopy)

局部使用

<script setup lang="ts">
import { vDebounce, vWaves } from '@qxs-bns/directives'
</script>

<template>
  <button v-debounce="handleClick" v-waves>
    点击按钮
  </button>
</template>

🚀 快速开始

全局注册

import { createApp } from 'vue'
import { vDebounce, vWaves, vCopy } from '@qxs-bns/directives'

const app = createApp(App)

// 注册指令
app.directive('debounce', vDebounce)
app.directive('waves', vWaves)
app.directive('copy', vCopy)

局部使用

<script setup lang="ts">
import { vDebounce, vWaves } from '@qxs-bns/directives'
</script>

<template>
  <button v-debounce="handleClick" v-waves>
    点击按钮
  </button>
</template>

💡 使用示例

防抖按钮

<template>
  <!-- 防止用户快速点击 -->
  <button v-debounce="{ handler: handleSubmit, delay: 1000 }">
    提交表单
  </button>

  <!-- 简化写法 -->
  <button v-debounce="handleSubmit">
    默认防抖
  </button>
</template>

<script setup lang="ts">
import { vDebounce } from '@qxs-bns/directives'

const handleSubmit = () => {
  console.log('表单提交')
}
</script>

波纹效果

<template>
  <!-- 默认波纹效果 -->
  <button v-waves class="btn-primary">
    主要按钮
  </button>

  <!-- 自定义波纹颜色 -->
  <button v-waves="{ color: '#ff6b6b' }" class="btn-danger">
    危险按钮
  </button>
</template>

<script setup lang="ts">
import { vWaves } from '@qxs-bns/directives'
</script>

一键复制

<template>
  <!-- 复制指定文本 -->
  <button v-copy="'Hello World!'" @copy-success="onCopySuccess">
    复制文本
  </button>

  <!-- 复制输入框内容 -->
  <div>
    <input v-model="text" placeholder="输入要复制的内容" />
    <button v-copy="text">复制</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { vCopy } from '@qxs-bns/directives'

const text = ref('')

const onCopySuccess = () => {
  console.log('复制成功！')
}
</script>

📋 可用指令

指令名	说明	文档
v-debounce	防抖指令	✅
v-waves	波纹效果	✅
v-copy	一键复制	✅
v-slide-in	滑入动画	✅
v-lazy-load	懒加载	✅
v-rich-overflow	富文本溢出	✅
v-safe-html	安全 HTML	✅

🎯 使用示例

防抖按钮

<template>
  <!-- 防止用户快速点击 -->
  <button v-debounce="{ handler: handleSubmit, delay: 1000 }">
    提交表单
  </button>
  
  <!-- 简化写法 -->
  <button v-debounce="handleSubmit">
    默认防抖
  </button>
</template>

<script setup lang="ts">
import { vDebounce } from '@qxs-bns/directives'

const handleSubmit = () => {
  console.log('表单提交')
}
</script>

波纹效果

<template>
  <!-- 默认波纹效果 -->
  <button v-waves class="btn-primary">
    主要按钮
  </button>
  
  <!-- 自定义波纹颜色 -->
  <button v-waves="{ color: '#ff6b6b' }" class="btn-danger">
    危险按钮
  </button>
</template>

<script setup lang="ts">
import { vWaves } from '@qxs-bns/directives'
</script>

<style>
.btn-primary {
  background: #409eff;
  color: white;
  border: none;
  padding: 8px 16px;
  border-radius: 4px;
}
</style>

一键复制

<template>
  <!-- 复制指定文本 -->
  <button v-copy="'Hello World!'" @copy-success="onCopySuccess">
    复制文本
  </button>
  
  <!-- 复制输入框内容 -->
  <div>
    <input v-model="text" placeholder="输入要复制的内容" />
    <button v-copy="text">复制</button>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { vCopy } from '@qxs-bns/directives'

const text = ref('')

const onCopySuccess = () => {
  console.log('复制成功！')
}
</script>

懒加载图片

<template>
  <div class="image-gallery">
    <img 
      v-for="src in imageSrcs" 
      :key="src"
      v-lazy-load="src"
      :src="placeholderSrc"
      alt="懒加载图片"
    />
  </div>
</template>

<script setup lang="ts">
import { vLazyLoad } from '@qxs-bns/directives'

const imageSrcs = [
  'https://example.com/image1.jpg',
  'https://example.com/image2.jpg',
  // ...
]

const placeholderSrc = 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzAwIiBoZWlnaHQ9IjIwMCI+PC9zdmc+'
</script>

🔧 自定义指令开发

创建指令

import type { Directive } from 'vue'

export const vCustom: Directive = {
  mounted(el, binding) {
    // 指令绑定到元素时
    console.log('指令挂载', el, binding.value)
  },
  
  updated(el, binding) {
    // 指令值更新时
    if (binding.value !== binding.oldValue) {
      console.log('指令更新', binding.value)
    }
  },
  
  unmounted(el) {
    // 指令解绑时
    console.log('指令卸载', el)
  }
}

指令参数

<template>
  <!-- 传递对象参数 -->
  <div v-custom="{ option1: 'value1', option2: 'value2' }">
    内容
  </div>
  
  <!-- 传递修饰符 -->
  <div v-custom.modifier="value">
    内容
  </div>
  
  <!-- 传递参数 -->
  <div v-custom:arg="value">
    内容
  </div>
</template>

TypeScript 支持

interface CustomDirectiveOptions {
  option1?: string
  option2?: number
}

export const vCustom: Directive<HTMLElement, CustomDirectiveOptions> = {
  mounted(el, binding) {
    const options = binding.value
    // TypeScript 会提供完整的类型提示
  }
}

📚 相关资源

• Vue 3 自定义指令
• 组件库
• Vue Hooks
• 工具函数

🤝 贡献

欢迎贡献新的指令！请参考：

• 开发指南
• 代码规范
• 测试规范

💡 最佳实践

1. 合理使用：只在必要时使用指令，避免过度封装
2. 性能考虑：注意指令的性能影响，及时清理事件监听器
3. 类型安全：使用 TypeScript 确保指令参数的类型安全
4. 文档完善：为自定义指令编写清晰的使用文档