QXS-BNS

Appearance

本页导航

Directives ​

@qxs-bns/directives 提供一组兼容 Vue 2.7.16+ 和 Vue 3.5.12+ 的自定义指令，用于复制、防抖、懒加载、波纹效果和富文本安全渲染等场景。

全局注册指令 ​

指令库最常见的接入方式是在应用入口统一注册。
这样页面里只需要写 v-copy、v-debounce 这类模板语法，不用每个组件单独重复声明。

loading

内容渲染指令 ​

如果你的项目会接外部 HTML、Markdown 或富文本输出，再继续看安全渲染类指令。
这类能力更适合在确认全局注册方式以后再接入具体业务内容。

loading

安装 ​

bash
pnpm add @qxs-bns/directives

Vue 3 导入 ​

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

const app = createApp(App)
app.directive('copy', vCopy)
app.directive('debounce', vDebounce)

Vue 2.7 导入 ​

ts
import Vue from 'vue'
import { vCopy, vDebounce, vRichOverflow, vSafeHtml } from '@qxs-bns/directives'

Vue.directive('copy', vCopy)
Vue.directive('debounce', vDebounce)
Vue.directive('richOverflow', vRichOverflow)
Vue.directive('safeHtml', vSafeHtml)

Vue 2 工程应直接注册完整指令，不再手动将 mounted 映射为 inserted。包内已同时提供两套生命周期钩子，包括内容更新和卸载清理。Vue 3 的 <script setup> 导入用法保持不变。

复制、懒加载与波纹指令已由函数形式改为带生命周期的对象，模板注册方式不变；不要在普通 JavaScript 中直接把 vCopy、vLazyLoad 或 vWaves 当函数调用。vSafeHtml 仍是两个版本均支持的函数指令。

input/img 的波纹应绑定到模板中显式声明的外层，例如 <span v-waves.button><input /></span>。直接在 input/img 上使用会跳过初始化，避免 node-waves 自动包裹元素破坏 Vue 的条件渲染；源码开发时会给出警告，生产构建会移除日志。button 等容器元素仍可直接使用。

推荐在应用入口处进行全局注册；也可以在单个组件中局部引入后使用。注册完成后，模板里使用的是 v-copy、v-debounce 这类 kebab-case 形式。

可用能力 ​

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

常见场景 ​

  • 需要统一处理复制、防重复点击、波纹效果的按钮类交互。
  • 需要安全渲染 HTML 或实现富文本截断的内容场景。
  • 需要图片懒加载、元素入场动画等 DOM 增强能力的 Vue 项目。

注意事项 ​

  • 指令库适合在应用入口统一注册，避免页面内重复声明。
  • 涉及 DOM 交互和第三方库的指令，建议先在真实业务页面里确认 SSR 或异步渲染行为。
  • 如果你还需要配套 UI 组件，可搭配 @qxs-bns/components 一起使用。

下一步 ​