Vue IMask 集成指南：组件、指令与 Composable 三种方式实现输入掩码-北京尧图网络

前端UI组件【免费下载链接】imaskjsvanilla javascript input mask项目地址https://gitcode.com/gh_mirrors/im/imaskjs点击查看免费下载导读本指南以vue-imaskIMask 的 Vue 官方适配包版本 7.6.1为核心系统讲解在 Vue 2 与 Vue 3 项目中接入输入掩码Input Mask的三种官方方式IMaskComponent组件、IMaskDirective指令、以及面向 Vue 3 的useIMaskComposable。读完本文你将掌握 v-model 双向绑定的数据形态masked / unmasked / typed、accept/complete事件体系、全部 mask 参数数字、日期、模式、枚举、动态掩码等的传法并能直接照着示例在项目中落地电话、日期、金额、手机号等格式化输入场景。文中涉及的全部实现细节均可对照本仓库 vue-imask 源码与 imask 核心源码验证。安装与环境适配npm i vue-imaskvue-imask通过 vue-demi 中的isVue3 ? Component3 : Component2判断。其依赖声明为vue 2.7见 package.json 的 peerDependencies因此 Vue 2 项目需要确保版本不低于 2.7。Vue 2 补充安装如果使用 Vue 2还需要额外安装 Composition API 桥接包npm i -D vue/composition-apiNuxtJSVue 2补充配置如果使用 NuxtJS 且基于 Vue 2还需要安装 Nuxt 版的 Composition API 模块npm i -D nuxtjs/composition-api然后在nuxt.config.js的buildModules中加入nuxtjs/composition-api/moduleexport default { buildModules: [ // ... nuxtjs/composition-api/module ] }方式一imask-input组件IMaskComponent在内部渲染一个原生input所有 mask 参数与原生 input 属性如placeholder可以直接写在组件上。组件同时支持 Vue 2 的 Options API 与 Vue 3 的 Composition API 实现Vue 3 走 component3-composition.tsVue 2 走 component2.ts另有 Options API 版 component3-options.ts。Vue 2 示例数字掩码template imask-input v-modelnumberModel :maskNumber radix. :unmasktrue acceptonAccept !-- 其余 mask 参数见下文参数总表 -- placeholderEnter number here / /template script import { IMaskComponent } from vue-imask; export default { data () { return { numberModel: , onAccept (value) { console.log(value); } } }, components: { imask-input: IMaskComponent } } /script需要特别留意unmask与accept回调第一个参数的对应关系README 官方说明unmaskfalse时accept的第一个参数是value带掩码的显示值unmasktrue时第一个参数是unmaskedValue去掉掩码后的纯值unmasktyped时第一个参数是typedValue类型化后的值例如Number掩码下是数字而非字符串。Vue 2 组件内部通过_maskValue()实现这一映射component2.ts当unmask typed返回maskRef.typedValue为真时返回unmaskedValue否则返回value_onAccept会同时向外派发input与accept事件component2.ts。Vue 3 示例typed 双向绑定与细分事件Vue 3 组件支持多种 v-model 写法README 明确指出v-model等价于v-model:value、v-model:masked和v-model:unmasked此外还有独立的v-model:typedtemplate imask-input v-model:typednumberModel :maskNumber radix. accept:maskedonAccept accept:unmaskedonAcceptUnmasked !-- accept:typedonAcceptTyped complete:typedonCompleteTyped -- placeholderEnter number here / /template script import { IMaskComponent } from vue-imask; export default { data () { return { numberModel: , onAccept (value) { console.log({ value }); }, onAcceptUnmasked (unmaskedValue) { console.log({ unmaskedValue }); } } }, components: { imask-input: IMaskComponent } } /scriptVue 3 组件对外派发的事件全表见 component3-composition.ts 的 emits 声明事件说明accept/accept:value/accept:masked接受输入时派发参数为带掩码的显示值accept:unmasked接受输入时派发参数为去掩码值accept:typed接受输入时派发参数为类型化值complete/complete:value/complete:masked输入完整达到掩码完整长度时派发complete:unmasked/complete:typed输入完整时派发对应的 unmasked / typed 值update:modelValue/update:value/update:masked组件内部维护显示值同步供 v-model 使用update:unmasked/update:typed同步 unmasked / typed 值供v-model:unmasked/v-model:typed使用从源码看accept与complete的派发逻辑并不相同onAccept会一次性把masked、unmasked、typed三种形态全部派发出去component3-composition.ts而onComplete只额外派发complete:value同complete:maskedcomplete:unmasked与complete:typed则由useIMask内部完整派发见 composable.ts。这意味着 Vue 3 的组件与 Composable 两套 API 在事件细分上由同一套核心逻辑支撑。数值型 v-model 的值优先级VALUE_PROPS数组[typed, unmasked, value, modelValue]component3-composition.ts定义了同步优先级同时传入多个值时typed优先其次unmasked、value、modelValue。初始化时组件按此优先级取初始值写入掩码component3-composition.ts。可以推断业务中推荐只绑定一种值形态通常是最符合业务语义的typed或unmasked避免多值同时写入导致互相覆盖。方式二v-imask指令指令适合对既有input或 contenteditable 元素直接施加掩码无需替换成组件。README 特别提醒指令场景下v-model绑定可能不生效应通过accept或complete事件手动更新值。指令派发的是原生 CustomEvent事件对象上的e.detail即 mask 实例引用见 directive.ts 的fireEvent实现从中可读取value、unmaskedValue、typedValue等属性。template input :valuevalue v-imaskmask acceptonAccept completeonComplete /template script import { IMaskDirective } from vue-imask; export default { data () { return { value: , mask: { mask: {8}000000, lazy: false }, }, }, methods: { onAccept (e) { const maskRef e.detail; this.value maskRef.value; console.log(accept, maskRef.value); }, onComplete (e) { const maskRef e.detail; console.log(complete, maskRef.unmaskedValue); }, }, directives: { imask: IMaskDirective } } /script上例的{8}000000是模式掩码{8}为固定文本必须原样输入80为数字占位符。因为设置了lazy: false输入过程中会即时显示_占位。指令的生命周期映射directive.tsVue 3 的beforeMount/ Vue 2 的bind挂载时调用initMask创建掩码updated/update当指令绑定的 options 变化时调用maskRef.updateOptions()热更新掩码配置若 options 变为空值则销毁掩码可用来实现启用/禁用掩码切换unmounted/unbind销毁掩码并解绑事件。仓库自带的 example.html 中就有Disable/Enable mask按钮通过把v-imask绑定的对象置空来开关日期掩码的完整示例。方式三useIMaskComposableVue 3Composable 适合在script setup/ Composition API 场景下把掩码绑定到任意元素 ref 上是三者中与原生模板结构耦合最低的方式template input refel /template script import { useIMask } from vue-imask; export default { setup (props) { const { el, masked } useIMask({ mask: Number, radix: ., }, /* 可选参数 { emit, onAccept, onComplete, defaultValue, defaultUnmaskedValue, defaultTypedValue, } */); return { el }; } } /scriptuseIMask的完整签名与返回值composable.ts第一参数掩码配置FactoryOpts也可以是RefFactoryOpts因此配置可随 ref 响应式更新第二参数可选ComposableParams包含emit、onAccept、onComplete回调以及defaultValue、defaultUnmaskedValue、defaultTypedValue三个默认值注入点返回值el元素 ref绑定到模板、mask只读的 mask 实例 ref、masked/unmasked/typed三种数据形态的响应式 ref。useIMask的内部机制值得展开它通过onMounted创建掩码、onUnmounted销毁composable.ts并watch元素与配置元素变化时自动重建、配置变化时调用updateOptions热更新composable.ts。三个响应式 ref 与 mask 实例之间是双向同步的外部写入 ref 会写回 mask 实例并触发 accept 重放mask 内部变化又会回写 refstoreLastAcceptedValues与三个update*Valuewatch 共同完成这一闭环见 composable.ts。README 注释中标出的可选参数emit值得注意组件正是把emit注入useIMask后才统一获得了accept:masked/accept:typed/complete:unmasked等全套细分事件能力见 composable.ts 的_onAccept/_onComplete。也就是说组件 API 实际上是 Composable API 的薄封装——理解了useIMask就理解了组件的事件模型。Mask 参数总表组件 / 指令 / Composable 通用所有 mask 配置均来自 imask 核心的FactoryOpts类型factory.tsvue-imask 将其展开为组件 propsprops.ts。按掩码类型分组如下通用参数所有掩码类型参数类型说明maskstring \| RegExp \| Number \| Date \| Array \| Function \| Masked 实例/类掩码定义决定掩码类型见下文映射表prepareFunction在掩码处理前整体转换值如大小写、去空格prepareCharFunction对输入值逐字符转换如把小写字母转大写validateFunction自定义校验函数返回false则拒绝输入commitFunction编辑结束时对值做额外处理如补零、四舍五入overwriteboolean \| shift允许覆盖输入shift表示右移覆盖eagerboolean \| append \| remove是否即时显示完整占位append/remove控制光标方向props 层校验见 props.tsskipInvalidboolean是否跳过非法输入核心默认值为true见 base.tsautofixboolean \| pad编辑结束时自动修正日期掩码下pad表示补齐位数模式掩码mask 为字符串参数说明placeholderChar空输入的占位字符默认_pattern.tsdisplayChar已填充字符的显示字符用于密码类场景统一显示为•等lazy是否仅在有需要时显示占位默认truedefinitions自定义占位符定义如{ #: /[0-9]/ }blocks模式中的块配置如日期掩码中d/m/Y各块的取值范围模式掩码的占位符语义0数字、a字母、*任意字符\转义、为停止字符{固定文本}表示必须原样出现的文本pattern.ts。自定义 definitions 时键值为单个字符值为正则、字符串或 Masked 类/实例pattern.ts。数字掩码mask 为Number参数默认值说明radix,小数点分隔符thousandsSeparator千分位分隔符mapToRadix[.]输入时可映射为小数点的字符集合默认支持英文句点scale2小数点后位数minNumber.MIN_SAFE_INTEGER最小值maxNumber.MAX_SAFE_INTEGER最大值normalizeZerostrue编辑结束时是否去除前导/尾随零padFractionalZerosfalse编辑结束时是否补齐小数位零以上默认值均来自 number.ts 的MaskedNumber.DEFAULTS。README 示例中的radix.即为指定小数点显示与输入均为英文句点。日期掩码mask 为Date参数说明pattern日期模式默认d{.}m{.}Y即dd.mm.yyyy见 date.tsformat/parse自定义格式/解析函数提供自定义 pattern 时必填见 date.ts 的RequiredDateOptionsmin/max允许的最小/最大日期Date或可解析值autofix是否在编辑结束时自动补齐/修正日期日期掩码默认块d取值 1-312 位、m取值 1-122 位、Y取值 1900-9999date.ts均为MaskedRange实现。枚举 / 范围 / 动态掩码掩码类型mask 值关键参数枚举数组如[张三, 李四]enum候选列表、可选matchValueenum.ts范围数值区间from/to/maxLength见 range.ts 与 props.ts动态Array构造器或掩码数组dispatch根据输入动态选择掩码dynamic.ts此外mask还可为RegExp正则掩码或函数自定义函数掩码。mask 类型到 Masked 类的完整映射逻辑在 factory.ts 的maskedClass中字符串 →MaskedPattern、Number→MaskedNumber、Date→MaskedDate、数组/Array→MaskedDynamic、RegExp→MaskedRegExp、函数 →MaskedFunction。参数透传与优先级细节组件的 mask 参数通过extractOptionsFromPropsutils.ts从 props 中抽取该函数会剔除值为undefined的 prop以及value/unmask等绑定专用 prop避免把 Vue 的绑定值误当作掩码配置传给 imask。Vue 3 组件还通过VALUE_PROPS过滤出绑定专用 propcomponent3-composition.ts。这意味着未传的 mask 参数会落入 imask 核心默认值传入的才生效——在排查参数没生效问题时应优先检查 props 拼写与绑定值是否为undefined。常见业务场景速查以下三个场景可组合上文参数直接使用手机号/固定文本前缀模式掩码imask-input v-modelphone :mask{ mask: {7}00000000000, lazy: false } /金额输入数字掩码保留 2 位小数、千分位imask-input v-model:typedamount :maskNumber radix. thousands-separator, scale2 pad-fractional-zeros /注Vue 模板中thousandsSeparator等驼峰 prop 需写作thousands-separatorpadFractionalZeros可写作pad-fractional-zeros。日期输入Vue 3 组合式 APItemplate input refdateEl / /template script setup import { useIMask } from vue-imask; const { el: dateEl, typed } useIMask({ mask: Date, pattern: d{.}m{.}Y, autofix: pad }, { defaultTypedValue: new Date() }); /script与 imask 核心的关系vue-imask只是 imask 的 Vue 绑定层核心掩码引擎位于 packages/imaskvue-imask的三种 API 最终都会调用核心IMask(element, opts)工厂创建掩码实例组件在 component2.ts / component3-options.ts、指令在 directive.ts、Composable 在 composable.ts并订阅实例的accept/complete事件。因此核心 imask 的所有能力模式、数字、日期、动态、枚举、范围、正则、函数掩码都通过这三个 API 暴露给 Vue 应用。vue-imask 的导出面index.ts包括IMaskComponent、IMaskDirective、useIMask含ComposableParams等类型与IMaskProps。若需要在 Vue 中直接操作 Masked 实例的底层 API如masked.value的精细读取与写入也可从同一入口导出IMask核心对象使用。更完整的掩码语义说明各 Masked 类的行为与全部选项可参考根目录 README.md 及 docs/guide.html 中关于 imask 核心的指南部分。赞分享前端UI组件【免费下载链接】imaskjsvanilla javascript input mask项目地址https://gitcode.com/gh_mirrors/im/imaskjs点击查看免费下载相关推荐React IMask 使用指南为 React 输入框集成 imask 掩码组件React IMask 使用指南为 React 输入框集成 imask 掩码组件本文基于 imaskjs 仓库中的 react imask 插件文档系统讲前端UI组件在 Grok Build 中使用 PinchTab 浏览器自动化插件安装、配置与 CLI/MCP 双通道实战在 Grok Build 中使用 PinchTab 浏览器自动化插件安装、配置与 CLI/MCP 双通道实战 PinchTab 为 Grok Build 提供前端UI组件imask/svelte 使用指南在 Svelte 项目中接入 IMask 输入掩码imask/svelte 使用指南在 Svelte 项目中接入 IMask 输入掩码导读 imask/svelte 是 imaskjs 仓库vanil前端UI组件上一篇Tactile 开源项目教程下一篇Himotoki 开源项目教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Vue IMask 集成指南：组件、指令与 Composable 三种方式实现输入掩码

相关推荐

Python使用FastApi项目开发-项目搭建及打包简介

AnyPS5实战：用开源面板统一管理PS5游戏库与远程串流

多AI Provider架构设计：从统一接口到动态路由的接入层重构

更多资讯

数据库课程设计实战：从建库到事务闭环的完整指南

ai-agent-book：从入门到 Agent 工程实践（一）

【PMSM滤波代码2】PMSM未知负载转矩观测EKF。MATLAB例程（负载增广EKF与实际仿真结果）。订阅专栏后可查看完整代码

MySQL 8.4课程设计实战：从教科书模型到生产级数据库

解Bug之路-隔离故障点后业务不恢复?-热点Key处理与亚稳态故障

PostGIS 3.5.0 + PostgreSQL 17 Windows二进制捆绑包详解

今日更新

声子晶体仿真：三角晶格与六角晶格的能带计算实战

度假村安保定岗定编：岗位梳理、编制测算与排班设计

COMSOL等离子体模块实战：氩气双层DBD仿真建模全解析

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？