flit-directives

Vue2/Vue3 通用指令集合。使用 Rolldown 构建并提供 ESM 产物与类型文件。

安装

npm i flit-directives

需在项目中安装 vue（>=2.6.0 或 >=3.x）。

使用

Vue 3 安装

import { createApp } from 'vue'
import FlitDirectives from 'flit-directives'

createApp(App).use(FlitDirectives).mount('#app')

Vue 2 安装

import Vue from 'vue'
import FlitDirectives from 'flit-directives'

Vue.use(FlitDirectives)

按需使用

import { inputLimit, permission, longPress, noCopy, noPaste, copy, paste, autosize, clickOutside, textGradient } from 'flit-directives'

指令列表

• v-input-limit
• v-permission
• v-longpress / v-long-press
• v-nocopy / v-no-copy
• v-nopaste / v-no-paste
• v-copy
• v-paste
• v-autosize / v-auto-resize
• v-click-outside
• v-text-gradient

指令详解

v-input-limit

限制并清洗输入，自动处理 input/paste/blur。

支持类型：text | integer | number | alpha | alphanum | phone | email | idcard | cn | slug | hex | bankcard | postal | url | ipv4 | uuid | mac

选项表：

| 参数 | 类型 | 默认值 | 说明 | 示例 | | --- | --- | --- | --- | --- | | type | string | 'text' | 处理类型 | v-input-limit="'number'" | | allowNegative | boolean | false | 允许负数（整数/小数） | { allowNegative: true } | | decimalPlaces | number | undefined | 最大小数位（仅 number） | { decimalPlaces: 2 } | | maxLength | number | undefined | 最大字符长度（裁剪） | { maxLength: 10 } | | trim | boolean | false | 去除首尾空白 | { trim: true } | | pattern | RegExp | undefined | 白名单逐字符过滤（去掉 g） | { pattern: /[A-Za-z0-9-]/ } | | min/max | number | undefined | 失焦/粘贴时落界（非过渡态） | { min: 0, max: 100 } | | case | 'upper' \| 'lower' | undefined | 大小写统一（alpha/alphanum/slug/uuid） | { case: 'upper' } | | allowSpace | boolean | false | 允许空格（alpha/alphanum/cn） | { allowSpace: true } | | inputmode | string | undefined | 键盘提示覆盖 | { inputmode: 'numeric' } | | allowLeadingZero | boolean | true | 整数是否允许前导零 | { allowLeadingZero: false } | | normalizeDotLeading | boolean | true | '.' 归一为 0.（仅 number） | { normalizeDotLeading: true } | | normalizeFullWidth | boolean | false | 全角转半角（空格/ASCII） | { normalizeFullWidth: true } | | allowChars | string|string[] | undefined | 白名单字符（优先生效） | { allowChars: 'ABC-_' } | | disallowChars | string|string[] | undefined | 黑名单字符 | { disallowChars: ['$', '%'] } | | formatOnBlur | 'thousand' \| 'mac' | undefined | 失焦格式化数字千分位或 MAC 分段 | { formatOnBlur: 'thousand' } | | allowPaste | boolean | true | 是否允许粘贴 | { allowPaste: false } |

示例：

<!-- 最简：类型字符串（数字） -->
<input v-input-limit="'number'" />

<!-- 整数：允许负数，禁止前导零，范围 -100 ~ 100 -->
<input v-input-limit="{ type: 'integer', allowNegative: true, allowLeadingZero: false, min: -100, max: 100 }" />

<!-- 文本：裁剪 + 去空白 + 正则过滤（仅保留英数与短横） -->
<input v-input-limit="{ type: 'text', maxLength: 20, trim: true, pattern: /[A-Za-z0-9-]/ }" />

<!-- 小数：最多 3 位小数，'.' 归一为 '0.' -->
<input v-input-limit="{ type: 'number', decimalPlaces: 3, normalizeDotLeading: true }" />

<!-- 字母：统一大写 -->
<input v-input-limit="{ type: 'alpha', case: 'upper' }" />

<!-- 字母数字：允许空格 -->
<input v-input-limit="{ type: 'alphanum', allowSpace: true }" />

<!-- 中文：允许空格 -->
<input v-input-limit="{ type: 'cn', allowSpace: true }" />

<!-- 邮箱 -->
<input v-input-limit="'email'" />

<!-- 手机号 -->
<input v-input-limit="'phone'" />

<!-- 身份证号 -->
<input v-input-limit="'idcard'" />

<!-- 银行卡号（仅数字） -->
<input v-input-limit="'bankcard'" />

<!-- 邮政编码（仅数字，输入法提示 numeric） -->
<input v-input-limit="{ type: 'postal', inputmode: 'numeric' }" />

<!-- HEX 十六进制 -->
<input v-input-limit="'hex'" />

<!-- URL 链接 -->
<input v-input-limit="'url'" />

<!-- IPv4 地址 -->
<input v-input-limit="'ipv4'" />

<!-- UUID（统一小写） -->
<input v-input-limit="{ type: 'uuid', case: 'lower' }" />

<!-- MAC 地址（失焦自动分段） -->
<input v-input-limit="{ type: 'mac', formatOnBlur: 'mac' }" />

<!-- slug（统一小写，保留短横） -->
<input v-input-limit="{ type: 'slug', case: 'lower' }" />

v-permission

值为 false 时禁用元素（disabled、禁止点击、降低透明度）。

选项表：

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | value | boolean | - | false 禁用，其他视为允许 |

示例：

<button v-permission="false">操作</button>

v-longpress / v-long-press

长按触发回调，支持触摸与鼠标。

选项表：

| 参数 | 类型 | 默认值 | 说明 | 示例 | | --- | --- | --- | --- | --- | | duration | number | 500 | 触发长按的最短时长（ms） | { duration: 800 } | | preventDefault | boolean | true | 是否阻止默认行为 | { preventDefault: false } | | stopPropagation | boolean | false | 是否阻止事件冒泡 | { stopPropagation: true } | | movementTolerance | number | 10 | 触摸/鼠标移动容差 | { movementTolerance: 12 } | | mouse | boolean | true | 是否启用鼠标识别 | { mouse: false } | | onPress | (e,el)=>void | undefined | 长按触发回调 | { onPress: fn } |

示例：

<div v-longpress="{ duration: 800, onPress: (e, el) => console.log('press', el) }">长按我</div>

v-nocopy / v-no-copy

禁止复制事件，可选禁用选择。

选项表：

| 参数 | 类型 | 默认值 | 说明 | 示例 | | --- | --- | --- | --- | --- | | preventDefault | boolean | true | 阻止复制默认行为 | { preventDefault: true } | | stopPropagation | boolean | false | 阻止事件冒泡 | { stopPropagation: true } | | disableSelection | boolean | false | 禁用文本选择（user-select: none） | { disableSelection: true } |

示例：

<div v-nocopy="{ disableSelection: true }">禁止复制</div>

v-nopaste / v-no-paste

禁止粘贴事件。

选项表：

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | preventDefault | boolean | true | 阻止粘贴默认行为 | | stopPropagation | boolean | false | 阻止事件冒泡 |

示例：

<input v-nopaste />

v-copy

点击拷贝文本，支持 Clipboard API 与回退方案。

选项表：

| 参数 | 类型 | 默认值 | 说明 | 示例 | | --- | --- | --- | --- | --- | | text | string | undefined | 固定拷贝文本（优先级最高） | v-copy="'Hello'" | | targetSelector | string | undefined | 从目标选择器元素取值 | { targetSelector: '#id' } | | useClipboardAPI | boolean | true | 优先 navigator.clipboard.writeText | { useClipboardAPI: false } | | onSuccess | (payload,el)=>void | undefined | 成功回调 | { onSuccess: fn } | | onError | (payload,el)=>void | undefined | 失败回调 | { onError: fn } |

示例：

<button v-copy="'Hello'">复制固定文本</button>
<button v-copy="{ targetSelector: '#inp' }">复制输入框</button>
<input id="inp" />

v-paste

监听粘贴文本，可选过滤与写入输入框。

选项表：

| 参数 | 类型 | 默认值 | 说明 | 示例 | | --- | --- | --- | --- | --- | | preventDefault | boolean | false | 阻止默认并写入输入框 | { preventDefault: true } | | stopPropagation | boolean | false | 阻止事件冒泡 | { stopPropagation: true } | | filter | (text)=>string | undefined | 文本过滤函数 | { filter: (t)=>t.trim() } | | onSuccess | (payload,el)=>void | undefined | 成功回调 | { onSuccess: fn } | | onError | (payload,el)=>void | undefined | 失败回调 | { onError: fn } |

示例：

<input v-paste="{ preventDefault: true, filter: t => t.replace(/\s+/g, '') }" />

v-autosize / v-auto-resize

根据内容自动调整高度（常用于 textarea）。

选项表：

| 参数 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | minRows | number | 1 | 最小行数 | | maxRows | number | undefined | 最大行数（undefined 不限制） | | debounce | number | 0 | 防抖毫秒 | | observe | boolean | false | 是否使用 ResizeObserver 监听 |

示例：

<textarea v-autosize="{ minRows: 2, maxRows: 6, debounce: 50 }"></textarea>

v-click-outside

侦测元素外点击，支持包含/忽略节点与事件类型。

选项表：

| 参数 | 类型 | 默认值 | 说明 | 示例 | | --- | --- | --- | --- | --- | | enabled | boolean | true | 是否启用 | { enabled: false } | | trigger | 'click' \| 'mousedown' \| 'touchstart' | 'click' | 触发事件类型 | { trigger: 'mousedown' } | | useCapture | boolean | true | 捕获阶段监听 | { useCapture: false } | | include | string|HTMLElement|(string|HTMLElement)[] | undefined | 包含的元素或选择器（视为内部） | { include: ['.dropdown'] } | | ignore | string|HTMLElement|(string|HTMLElement)[] | undefined | 忽略的元素或选择器 | { ignore: ['.actions'] } | | onOutside | (e,el)=>void | undefined | 外部点击回调 | { onOutside: close } |

示例：

<div v-click-outside="{ onOutside: () => close() }">弹层</div>

v-text-gradient

为文本应用渐变效果（逐字符着色）。

选项表：

| 参数 | 类型 | 默认值 | 说明 | 示例 | | --- | --- | --- | --- | --- | | colors | string[] | [] | 颜色数组（支持 #RRGGBB、rgb()） | ['#f00','#0f0'] |

示例：

<p v-text-gradient="['#f00', '#0f0', '#00f']">渐变文本</p>