@dong-pack/directives

Vue3 指令库

安装

pnpm add @dong-pack/directives

使用

全局安装

import { createApp } from 'vue'
import DDirectives from '@dong-pack/directives'
import App from './App.vue'

const app = createApp(App)
app.use(DDirectives)
app.mount('#app')

按需注册指令

import { createApp } from 'vue'
import App from './App.vue'
import {
  vExample,
  vCopyText,
  vDisabledMask,
  vEllipsisTooltip,
  vBgProgressive,
} from '@dong-pack/directives'

const app = createApp(App)

app.directive('example', vExample)
app.directive('copyText', vCopyText)
app.directive('disabledMask', vDisabledMask)
app.directive('ellipsisTooltip', vEllipsisTooltip)
app.directive('bgProgressive', vBgProgressive)

app.mount('#app')

指令列表与用法

v-example

示例指令（内部仅打印绑定值，一般用于示例或调试）。

<template>
  <div v-example="'hello'">示例指令</div>
</template>

v-copyText

点击元素复制文本到剪贴板。

<template>
  <!-- 方式一：直接复制固定文本 -->
  <button v-copyText="'要复制的文本'">复制文本</button>

  <!-- 方式二：设置复制成功回调 -->
  <button
    v-copyText="'要复制的文本'"
    v-copyText:callback="handleCopySuccess"
  >
    复制并提示
  </button>
</template>

<script setup lang="ts">
function handleCopySuccess(text: string) {
  console.log('复制成功：', text)
}
</script>

v-disabledMask

在元素上添加禁用遮罩层，可用于加载中或禁止操作状态。

<template>
  <!-- 简单用法：只传文案 -->
  <div v-disabledMask="'加载中...'">
    内容区域
  </div>

  <!-- 高级用法：完整配置 -->
  <div
    v-disabledMask="{
      text: '加载中...',
      bgColor: 'rgba(0, 0, 0, 0.5)',
      color: '#fff',
      fontSize: '16px'
    }"
  >
    内容区域
  </div>

  <!-- 动态控制开关 -->
  <div v-disabledMask="isLoading ? '加载中...' : false">
    内容区域
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const isLoading = ref(true)
</script>

v-ellipsisTooltip

当文本溢出时自动显示 Tooltip，需配合 CSS 省略号使用。

<template>
  <!-- 绑定 Tooltip 文案 -->
  <div
    v-ellipsisTooltip="tooltipText"
    class="ellipsis"
  >
    {{ content }}
  </div>

  <!-- 不传值时，默认使用元素文本作为 Tooltip 内容 -->
  <div
    v-ellipsisTooltip
    class="ellipsis"
  >
    {{ content }}
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const content = ref('这是一段可能会溢出的很长很长的文本...')
const tooltipText = ref('自定义的 Tooltip 文案')
</script>

<style scoped>
.ellipsis {
  max-width: 200px;
  white-space: nowrap;
  overflow: hidden;
  text-overflow: ellipsis;
}
</style>

v-bg-progressive

渐进式背景图加载指令：先显示低清占位图，加载完成后无闪烁地切换为高清图。

<template>
  <div
    class="banner"
    v-bg-progressive="{
      src: 'https://example.com/real-image.jpg',
      placeholder: 'https://example.com/blur-placeholder.jpg'
    }"
  ></div>

  <div
    class="banner"
    v-bg-progressive="{
      src: originImage,
      placeholder: placeholderImage
    }"
  ></div>
</template>

<script setup lang="ts">

import placeholderImage from '@/assets/images/placeholderImage.jpg'
import originImagefrom '@/assets/images/originImage.jpg'
</script>

<style scoped>
.banner {
  width: 100%;
  height: 300px;
  background-size: cover;
  background-position: center;
  transition: background-image 0.3s ease;
}

.bg-progressive--loaded {
  /* 可选：加载完成时的额外效果 */
}
</style>