Alpine.js Mask 插件完全指南x-mask 与 $money 输入格式化实战【免费下载链接】alpineA rugged, minimal framework for composing JavaScript behavior in your markup.项目地址: https://gitcode.com/gh_mirrors/al/alpineMask 是 Alpine.js 官方插件之一用于在用户输入时自动将文本字段格式化为预定格式适用于电话号码、信用卡号、金额、账号、日期等输入场景。本文以仓库中 Mask 插件官方文档 为骨架结合 插件源码 与 Cypress 集成测试 深入讲解安装、通配符语法、动态掩码、金额格式化及与x-model的协作原理读完即可在生产项目中直接落地使用。插件简介Alpine 的 Mask 插件让你无需手写任何 JavaScript仅通过一个x-mask指令即可为input文本输入框提供边输入边格式化的能力。它的适用场景非常典型电话号码(999) 999-9999信用卡号9999 9999 9999 9999金额1,234,567.89账号9999-9999-9999日期99/99/9999该插件以alpinejs/mask为包名独立发布仓库中对应 packages/mask版本号见 package.json通过 Alpine 的插件机制注册mask指令核心实现仅一个 index.js 文件约 240 行轻量且无外部依赖。安装与 Alpine 其他官方插件一致Mask 支持 CDN 和 NPM 两种引入方式。通过 CDN 引入使用script标签引入 CDN 构建产物务必放在 Alpine 核心 JS 文件之前!-- Alpine Plugins -- script defer srchttps://cdn.jsdelivr.net/npm/alpinejs/mask3.x.x/dist/cdn.min.js/script !-- Alpine Core -- script defer srchttps://cdn.jsdelivr.net/npm/alpinejs3.x.x/dist/cdn.min.js/scriptCDN 构建产物仓库内对应 packages/mask/builds/cdn.js内部实现很简洁监听alpine:init事件在 Alpine 初始化时自动调用window.Alpine.plugin(mask)完成注册因此无需额外编写初始化代码。通过 NPM 安装在项目内使用打包器如 Webpack、Vite时优先采用 NPM 方式npm install alpinejs/mask然后在入口文件中初始化插件import Alpine from alpinejs import mask from alpinejs/mask Alpine.plugin(mask) // ... 其余 Alpine 初始化代码若使用 ES Module 构建产物packages/mask/builds/module.js 还额外导出了stripDown等底层工具函数便于高级用户直接复用内部格式化逻辑。x-mask 指令基础用法x-mask是该插件的核心 API。看一个最简单的日期输入示例input x-mask99/99/9999 placeholderMM/DD/YYYY用户输入时输入框内的内容必须逐步符合x-mask提供的格式9通配符位置只能输入数字而/这类字面量字符即便用户没有手动输入也会在满足前置条件时被自动补全。例如用户依次输入0、1、2、5输入框会依次呈现0、01、01/2、01/25。支持的三种通配符通配符描述*任意字符a仅字母字符a-z, A-Z9仅数字字符0-9三种通配符在源码 stripDown 函数 中对应着三个正则let regexes { 9: /[0-9]/, a: /[a-zA-Z]/, *: /[a-zA-Z0-9]/, }注意*的实际含义是字母或数字即[a-zA-Z0-9]并非字面意义上的任意字符——严格来说它不允许空格、标点等符号。如果你的掩码中包含不在上述三种通配符内的普通字符如b、-、空格它们会被当作字面量处理由插件自动插入且不会被用户输入覆盖。这一点在 mask.spec.js 的ba9*b测试用例 中有直接验证模板ba9*b中用户输入a后值变为ba首字符b由插件补出且不可覆盖继续输入3得到ba3输入z得到ba3zb。掩码为空或为 false 的行为从测试用例可以看出如果x-mask的表达式结果为空字符串或字符串false源码第 77-78 行 的守卫逻辑插件会直接跳过格式化处理输入框表现为普通文本框任意字符均可输入见 mask.spec.js 中x-mask与x-maskfalse的测试。格式化底层原理stripDown 与 buildUpx-mask之所以能边输入边格式化核心是 processInputValue → formatInput 这条处理链其中两步是关键stripDown剥离把当前输入值中不属于模板的字面量字符删掉只保留与通配符匹配的原始字符序列。算法会先删除与模板字面量字符相同的字符再按通配符顺序逐个校验正则并收集匹配字符一旦某位不匹配就立即停止。buildUp重建用剥离后的干净字符序列按模板结构重新填充遇到通配符就从队列头部取出一个字符遇到字面量就原样插入字符耗尽则提前终止见 buildUp 函数。剥离 → 重建两步合一的优势在于无论用户粘贴的是已格式化文本如(123) 456-7890还是未格式化文本如1234567890最终都会被归一化为统一的掩码格式。这一行为在测试中被反复验证mask.spec.js 粘贴场景。光标位置与退格键的特殊处理直接给el.value赋值会把光标强制移动到末尾影响中间编辑体验因此源码做了三处精细处理光标恢复restoreCursorPosition 函数 在改写值之前记录selectionStart改写后只对光标左侧的文本执行一次剥离 重建以其结果长度作为新的光标位置并通过setSelectionRange恢复。由于 Safari 在blur时会重新聚焦造成焦点陷阱恢复光标逻辑只在input事件中启用blur事件用于处理粘贴落定则不恢复。退格放行当检测到lastInputValue.length - el.value.length 1即本次操作删除了一个字符时直接跳过格式化源码第 81-83 行让用户能顺畅地删除字符避免删不掉的体验。测试中断言连续退格时(123) 456-7890逐步回退为(123) 456-789、(123) 456-78……直至(123) 45正是该逻辑的效果。非法字符吞掉由于剥离阶段只收集正则匹配的字符在数字位输入字母、符号等非法字符时会被过滤掉输入框值保持不变测试中断言输入a、-后值仍为(123) 45见 mask.spec.js 第 26-27 行。动态掩码x-mask:dynamic当固定字面量掩码如(999) 999-9999无法满足需求时可以使用x-mask:dynamic根据用户输入动态生成掩码。典型的信用卡号场景当卡号以34或37开头时说明是 Amex美国运通卡应采用9999 999999 99999格式否则采用通用格式9999 9999 9999 9999input x-mask:dynamic $input.startsWith(34) || $input.startsWith(37) ? 9999 999999 99999 : 9999 9999 9999 9999 每次输入当前输入框的值都会以$input的身份传入表达式表达式求值后返回的字符串即当前应使用的掩码。用户输入34开头的号码与普通号码时输入框会自动切换为不同的格式。动态掩码也可以是一个函数x-mask:dynamic的表达式结果还可以是一个函数插件会自动把$input作为第一个参数传入input x-mask:dynamiccreditCardMask script function creditCardMask(input) { return input.startsWith(34) || input.startsWith(37) ? 9999 999999 99999 : 9999 9999 9999 9999 } /script动态掩码的源码实现从源码看x-mask:dynamic源码中称为 function/dynamic 分支 使用了 Alpine 的evaluateLater延迟求值与effect响应式机制模板函数templateFn会在每次输入时执行得到当前掩码字符串同时effect会追踪表达式中的响应式依赖一旦依赖变化就自动重新计算掩码并重新格式化输入框。求值时通过Alpine.dontAutoEvaluateFunctions防止函数被自动执行以便把函数本身作为掩码生成器使用并注入$input与$money两个魔法变量。金额输入$money为金额输入手写动态掩码表达式相当繁琐因此插件内置了预制的金额格式化函数并以$money魔法变量的形式暴露给x-mask:dynamic或x-mask:function使用。一个开箱即用的金额输入框input x-mask:dynamic$money($input)用户输入1234时显示1,234输入567追加后显示1,234,567再输入.89得到1,234,567.89——千分位自动按三位一组插入。自定义小数分隔符第二个参数某些货币使用逗号作为小数分隔符此时交换小数点和逗号的角色即可input x-mask:dynamic$money($input, ,)输入30,00后继续输入会得到30,05千分位自动变为点号如1.234.567,89相关行为见 mask.spec.js 中的逗号/句点互换测试。自定义千分位分隔符第三个参数传入第三个参数可覆盖千分位分隔符例如用空格分组input x-mask:dynamic$money($input, ., )输入3000会显示为3 000再输入567显示1 234 567.89对应测试。自定义小数精度第四个参数默认保留 2 位小数通过第四个参数可改为任意精度甚至支持 0 位纯整数input x-mask:dynamic$money($input, ., ,, 4)测试覆盖了精度 03 的全部情况输入1234.5678精度为 0 时显示12,345,678精度为 1 显示1,234.5精度为 2 显示1,234.56精度为 3 显示1,234.567mask.spec.js 第 243-255 行。$money 的源码细节formatMoney 函数 是$money的底层实现有几个值得注意的行为负号支持输入以-开头时保留负号测试断言-1234.50会被格式化为-1,234.50且负号的插入/删除不会破坏掩码mask.spec.js 负数测试。非法字符过滤仅保留数字与小数分隔符A、ABC、$、/等字符全部被清除对应测试若输入中不含任何数字如只输入了符号会返回占位字符串9相当于一个等待数字输入的模板。千分位默认值联动当第三个参数未提供时千分位自动取小数分隔符的反向字符分隔符为,则千分位用.否则用,。光标微调格式化后如果光标恰好在分隔符之后会通过setSelectionRange把光标前移一位避免用户每次输入后光标停在错误的符号位置。与 x-model 的协作x-mask与x-model可以无缝配合掩码格式化后的值会自动同步进数据模型反之模型值变化也会反映到输入框。注意两点前提监听顺序插件在input事件上以capture捕获阶段监听源码第 61-66 行确保格式化先于x-model等潜在绑定执行从而让模型拿到的是已格式化值。指令注册顺序插件通过Alpine.directive(mask, ...).before(model)注册源码第 110 行保证x-mask在x-model之前初始化。初始值同步与特殊值保护初始化时插件会把格式化后的el.value写回x-model源码第 42-52 行但有两个防抖保护若模型值已等于输入框值、或模型值为null而输入框为空字符串则不做覆盖避免触发无意义的更新链。对应测试验证了模型初始值为1234567890时输入框与第二个展示x-model的输入框都会初始显示为(123) 456-7890而模型初始值为null时输入框保持为空且模型仍为nullmask.spec.js 初始值测试。资源清理插件使用AbortController管理事件监听器并在cleanup回调中调用controller.abort()源码第 55-59 行因此当 Alpine 销毁指令或组件时监听器会被正确移除不会造成内存泄漏。常见问题与边界行为速查粘贴已格式化/未格式化文本blur事件也会触发一次格式化不恢复光标粘贴后点击外部即可完成归一化input事件则保证边贴边格式化。中间插入编辑光标恢复机制支持在已有值中间插入数字测试验证了在(123) 456-7890中间插入123456得到(123) 456-1234以及金额中间插入数字后千分位自动重排mask.spec.js 中间插入测试。退格删除操作会被放行并自动保留合法掩码骨架。*不是任意字符源码正则限定为[a-zA-Z0-9]空格与标点不会被*接受。掩码为空/为 false跳过格式化退化为普通输入框。小结x-mask用一条指令解决了前端表单中最常见的输入格式化需求而x-mask:dynamic与$money进一步覆盖了信用卡号、多货币金额等复杂动态场景。理解其剥离-重建算法、光标恢复、捕获阶段监听等实现细节能帮助你在项目中正确处理粘贴、退格、中间编辑等边界情况。仓库中 Mask 源码、集成测试 与 官方文档 三份资料互为印证是深入学习与排查问题的最佳起点。【免费下载链接】alpineA rugged, minimal framework for composing JavaScript behavior in your markup.项目地址: https://gitcode.com/gh_mirrors/al/alpine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考