# vue-directives-kit

**Repository Path**: cbTest/vue-directives-kit

## Basic Information

- **Project Name**: vue-directives-kit
- **Description**: Vue 自定义指令集合，帮助开发者轻松实现常见交互需求，提升开发效率
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-18
- **Last Updated**: 2026-06-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue Directives Kit

一个功能丰富的 Vue 3 自定义指令库，提供实用的指令功能，支持完整的 TypeScript 类型提示和编辑器跳转。

## ✨ 特性

- 🚀 **Vue 3 原生支持** - 基于 Vue 3 Composition API
- 📚 **完整的 TypeScript 支持** - 提供完整的类型定义
- 🔧 **编辑器智能提示** - 支持 VSCode 跳转到定义
- 🎨 **丰富的指令功能** - 提供多种实用指令
- 📱 **响应式设计** - 适配各种屏幕尺寸
- 🔒 **错误处理完善** - 提供详细的错误信息和回调

## 📦 安装

```bash
npm install vue3-directives-kit
# 或
yarn add vue3-directives-kit
# 或
pnpm add vue3-directives-kit
```

## 🚀 快速开始

### 全局注册

```typescript
import { createApp } from 'vue';
import VueDirectivesKit from 'vue3-directives-kit';
import 'vue3-directives-kit/dist/vue3-directives-kit.css'; // 导入样式
import App from './App.vue';

const app = createApp(App);
app.use(VueDirectivesKit);
app.mount('#app');
```

### 按需引入

```typescript
import { createApp } from 'vue';
import { tooltip, copy, watermark, formatNumber, enter, esc, download } from 'vue3-directives-kit';
import 'vue3-directives-kit/dist/vue3-directives-kit.css'; // 导入样式
import App from './App.vue';

const app = createApp(App);
app.directive('tooltip', tooltip);
app.directive('copy', copy);
app.directive('watermark', watermark);
app.directive('formatNumber', formatNumber);
app.directive('enter', enter);
app.directive('esc', esc);
app.directive('download', download);
app.mount('#app');
```

## 📋 可用指令

### 1. v-tooltip - 工具提示指令

在元素上显示美观的工具提示。

#### 基础用法

```vue
<button v-tooltip="'这是一个提示信息'">悬停查看提示</button>
```

#### 定位方向

```vue
<button v-tooltip="{ content: '顶部提示', placement: 'top' }">顶部</button>
<button v-tooltip="{ content: '右侧提示', placement: 'right' }">右侧</button>
<button v-tooltip="{ content: '底部提示', placement: 'bottom' }">底部</button>
<button v-tooltip="{ content: '左侧提示', placement: 'left' }">左侧</button>
```

#### HTML 内容支持

```vue
<button
    v-tooltip="{
        content: '<b>粗体文本</b><br><i>斜体文本</i><br><span style=\'color: red\'>红色文本</span>',
        html: true,
    }"
>
    HTML 内容
</button>
```

#### 动态内容

```vue
<script setup>
const dynamicContent = ref('动态内容');
</script>

<template>
    <button v-tooltip="dynamicContent">动态提示</button>
</template>
```

### 2. v-copy - 点击复制指令

增强版的点击复制功能，支持多种配置选项。

#### 基础用法

```vue
<button v-copy="'要复制的文本'">复制文本</button>
```

#### 带回调的用法

```vue
<script setup>
const onCopySuccess = text => {
    console.log('复制成功:', text);
};

const onCopyError = error => {
    console.error('复制失败:', error);
};
</script>

<template>
    <button
        v-copy="{
            text: '要复制的文本',
            options: {
                onSuccess: onCopySuccess,
                onError: onCopyError,
            },
        }"
    >
        复制文本
    </button>
</template>
```

#### 富文本复制

```vue
<button
    v-copy="{
        text: '<b>粗体文本</b> <i>斜体文本</i>',
        options: { type: 'html' },
    }"
>
    复制富文本
</button>
```

### 3. v-watermark - 水印指令

为页面或元素添加水印，保护内容版权。

#### 基础文本水印

```vue
<div
    v-watermark="{
        text: '机密文件',
        fontSize: 16,
        color: 'rgba(0, 0, 0, 0.1)',
    }"
    class="watermark-container"
>
    <!-- 内容区域 -->
</div>
```

#### 多行水印

```vue
<div
    v-watermark="{
        text: ['公司名称', '机密文件', '请勿外传'],
        fontSize: 14,
        color: 'rgba(255, 0, 0, 0.15)',
        gap: [100, 100],
    }"
    class="watermark-container"
>
    <!-- 内容区域 -->
</div>
```

#### 图片水印

```vue
<div
    v-watermark="{
        image: 'data:image/svg+xml;base64,...',
        width: 80,
        height: 80,
    }"
    class="watermark-container"
>
    <!-- 内容区域 -->
</div>
```

#### 旋转水印

```vue
<div
    v-watermark="{
        text: '旋转水印',
        fontSize: 18,
        color: 'rgba(0, 100, 0, 0.1)',
        rotate: -45,
        zIndex: 999,
    }"
    class="watermark-container"
>
    <!-- 内容区域 -->
</div>
```

### 4. v-format-number - 数字格式化指令

用于格式化数字输入，支持千位分隔符、小数位数限制、负数处理等功能。

#### 基础用法（金额输入）

```vue
<input
    v-model="amount"
    v-format-number="{
        decimalPlaces: 2,
        thousandSeparator: true,
        onFormat: handleFormat,
        onInvalid: handleInvalid,
    }"
    placeholder="请输入金额"
/>
```

#### 价格输入（不允许负数）

```vue
<input
    v-model="price"
    v-format-number="{
        decimalPlaces: 2,
        thousandSeparator: true,
        allowNegative: false,
    }"
    placeholder="请输入价格"
/>
```

#### 工资输入（只允许整数）

```vue
<input
    v-model="salary"
    v-format-number="{
        decimalPlaces: 0,
        thousandSeparator: true,
        allowNegative: false,
    }"
    placeholder="请输入月薪"
/>
```

#### 百分比输入

```vue
<input
    v-model="percentage"
    v-format-number="{
        decimalPlaces: 2,
        thousandSeparator: false,
        allowNegative: false,
        maxValue: 100,
    }"
    placeholder="请输入百分比"
/>
```

### 5. v-enter - Enter 键监听指令

用于监听元素上的 Enter 键按下事件，特别适合表单提交场景。

#### 登录表单示例

```vue
<script setup>
const loginForm = ref({
    username: '',
    password: '',
});

const handleLogin = () => {
    if (loginForm.value.username && loginForm.value.password) {
        alert('登录成功！');
    }
};
</script>

<template>
    <div>
        <input v-model="loginForm.username" placeholder="用户名" />
        <input type="password" v-model="loginForm.password" v-enter="handleLogin" placeholder="密码（按 Enter 登录）" />
        <button @click="handleLogin">登录</button>
    </div>
</template>
```

#### 搜索框示例

```vue
<script setup>
const searchQuery = ref('');

const handleSearch = () => {
    if (searchQuery.value.trim()) {
        console.log('搜索关键词:', searchQuery.value);
    }
};
</script>

<template>
    <input v-model="searchQuery" v-enter="handleSearch" placeholder="输入关键词并按 Enter 搜索" />
    <button @click="handleSearch">搜索</button>
</template>
```

#### 聊天输入框

```vue
<script setup>
const message = ref('');

const handleSendMessage = () => {
    if (message.value.trim()) {
        console.log('发送消息:', message.value);
        message.value = '';
    }
};
</script>

<template>
    <textarea v-model="message" v-enter="handleSendMessage" placeholder="输入消息并按 Enter 发送" rows="4"></textarea>
    <button @click="handleSendMessage">发送</button>
</template>
```

### 6. v-esc - Escape 键监听指令

用于监听元素上的 Escape 键按下事件，特别适合模态框和弹出层。

#### 模态框示例

```vue
<script setup>
const modalVisible = ref(false);

const openModal = () => {
    modalVisible.value = true;
};

const closeModal = () => {
    modalVisible.value = false;
};
</script>

<template>
    <div>
        <button @click="openModal">打开模态框</button>
        <div v-if="modalVisible" class="modal-overlay" v-esc="closeModal">
            <div class="modal">
                <h3>模态框标题</h3>
                <p>按 ESC 键可以关闭</p>
                <button @click="closeModal">关闭</button>
            </div>
        </div>
    </div>
</template>
```

#### 搜索框取消

```vue
<script setup>
const searchInput = ref('');

const clearSearch = () => {
    if (searchInput.value.trim()) {
        console.log('搜索已取消，原内容:', searchInput.value);
        searchInput.value = '';
    }
};
</script>

<template>
    <input v-model="searchInput" v-esc="clearSearch" placeholder="输入内容后按 ESC 取消" />
</template>
```

#### 编辑模式退出

```vue
<script setup>
const isEditing = ref(false);
const editContent = ref('这是一段可编辑的内容');
const originalContent = ref('');

const startEditing = () => {
    isEditing.value = true;
    originalContent.value = editContent.value;
};

const saveEditing = () => {
    isEditing.value = false;
};

const cancelEditing = () => {
    if (isEditing.value) {
        editContent.value = originalContent.value;
        isEditing.value = false;
    }
};
</script>

<template>
    <div v-if="!isEditing" class="view-mode">
        <p>当前内容: {{ editContent }}</p>
        <button @click="startEditing">进入编辑模式</button>
    </div>
    <div v-else class="edit-mode">
        <textarea
            v-model="editContent"
            v-esc="cancelEditing"
            placeholder="编辑内容，按 ESC 取消编辑"
            rows="3"
        ></textarea>
        <div class="edit-actions">
            <button @click="saveEditing">保存</button>
            <button @click="cancelEditing">取消</button>
        </div>
    </div>
</template>
```

### 7. v-download - 文件下载指令

用于触发文件下载操作，支持文本、JSON、CSV等多种格式。

#### 文本文件下载

```vue
<button
    v-download="{
        data: '这是一个文本文件的内容\n第二行内容\n第三行内容',
        filename: 'example.txt',
        onSuccess: () => console.log('文本文件下载成功！'),
    }"
>
    下载文本文件
</button>
```

#### JSON 文件下载

```vue
<button
    v-download="{
        data: JSON.stringify(
            {
                name: '张三',
                age: 25,
                email: 'zhangsan@example.com',
                hobbies: ['阅读', '运动', '音乐'],
            },
            null,
            2
        ),
        filename: 'user-data.json',
        mimeType: 'application/json',
        onSuccess: () => console.log('JSON文件下载成功！'),
    }"
>
    下载JSON文件
</button>
```

#### CSV 文件下载

```vue
<button
    v-download="{
        data: '姓名,年龄,城市\n张三,25,北京\n李四,30,上海\n王五,28,广州',
        filename: 'data.csv',
        mimeType: 'text/csv',
        onSuccess: () => console.log('CSV文件下载成功！'),
    }"
>
    下载CSV文件
</button>
```

#### 简化用法

```vue
<button v-download="'这是简化用法的文件内容，直接传入字符串即可下载'">
    简化下载
</button>
```

#### 自定义数据下载

```vue
<script setup>
const customData = ref('');
const customFilename = ref('');
</script>

<template>
    <textarea v-model="customData" placeholder="输入自定义数据" rows="3"></textarea>
    <input v-model="customFilename" placeholder="输入文件名" />
    <button
        v-download="{
            data: customData,
            filename: customFilename || 'custom.txt',
            onSuccess: () => console.log('自定义文件下载成功！'),
            onError: error => console.log('下载失败：' + error.message),
        }"
    >
        下载自定义文件
    </button>
</template>
```

## 🔧 API 参考

### v-format-number 配置选项

| 参数              | 类型     | 默认值    | 描述               |
| ----------------- | -------- | --------- | ------------------ |
| decimalPlaces     | number   | 2         | 小数位数           |
| thousandSeparator | boolean  | true      | 是否添加千位分隔符 |
| allowNegative     | boolean  | true      | 是否允许负数       |
| maxValue          | number   | undefined | 最大值限制         |
| onFormat          | function | undefined | 格式化完成回调     |
| onInvalid         | function | undefined | 无效输入回调       |

### v-enter / v-esc 回调函数

```typescript
// 回调函数接收 KeyboardEvent 参数
const handleKeyEvent = (event: KeyboardEvent) => {
    console.log('按键事件:', event);
};
```

### v-download 配置选项

| 参数      | 类型                          | 默认值         | 描述           |
| --------- | ----------------------------- | -------------- | -------------- |
| data      | string \| Blob \| ArrayBuffer | -              | 文件内容或数据 |
| filename  | string                        | 'download.txt' | 文件名         |
| mimeType  | string                        | 'text/plain'   | MIME 类型      |
| onSuccess | function                      | undefined      | 下载成功回调   |
| onError   | function                      | undefined      | 下载失败回调   |

## 🎯 演示

项目包含完整的演示页面，展示所有指令的功能和用法。

### 运行演示

```bash
# 克隆项目
git clone https://gitee.com/Gitfubobo/vue-directives-kit.git

# 安装依赖
cd vue-directives-kit
npm install

# 启动开发服务器
npm run dev
```

访问 http://localhost:5173 查看演示效果。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

## � 联系方式

- 项目地址: [https://gitee.com/Gitfubobo/vue-directives-kit](https://gitee.com/Gitfubobo/vue-directives-kit)
- 作者: fubobo