输入掩码 InputMask
InputMask 适合日期、编号、版本号、网络地址等具有可辨识输入结构的字段。它复用 Input 的尺寸、禁用、只读、清除、错误态、前后缀、字数统计和表单联动能力。
掩码只负责限制输入过程中的字符与结构，不等于业务校验。比如 preset="ipv4" 会阻止单段超过 255 并限制为四段，但提交前仍应使用表单规则判断值是否完整有效。
字符串 mask 会自动插入普通字符。默认 9 表示数字；将 mask-char 设为 null 可隐藏尚未填写的位置。
中文、英文与自定义规则
Section titled “中文、英文与自定义规则”默认 token 同时支持数字、英文、汉字和 Unicode 字母。复杂场景可以传入由字面量和 RegExp 组成的数组，每个正则表达式对应一个可编辑位置。
| Token | 含义 | 默认规则 |
|---|---|---|
9 |
数字 | [0-9] |
a |
英文字母 | [A-Za-z] |
* |
英文或数字 | [A-Za-z0-9] |
H |
汉字 | \p{Script=Han} |
L |
任意 Unicode 字母 | \p{Letter} |
N |
任意 Unicode 字母或数字 | [\p{Letter}\p{Number}] |
若要把 token 字符作为固定文本，使用反斜杠转义，例如 \9 表示固定字符 9。format-chars 可以覆盖或增加单字符 token。
内置格式模板
Section titled “内置格式模板”preset 提供常见结构化格式的开箱即用输入规则。下面的示例展示全部内置模板，每一项都可以直接编辑和清除。IPv4、URL 和 SemVer 等格式支持变长片段，不会被强制成不真实的固定长度。
| 分类 | 内置模板 |
|---|---|
| 日期时间 | date、time、datetime、rfc3339 |
| 网络地址 | ip、ipv4、ipv6、ip-range、url、fqdn、email |
| 开发格式 | semver、uuid、jwt、mime-type、data-uri、mailto-uri、magnet-uri |
| 标识与编码 | imei、issn、isrc、iso6346、iban |
| 颜色与坐标 | hex-color、rgb-color、hsl、lat-long、mac-address |
受控值与模板切换
Section titled “受控值与模板切换”组件使用标准 v-model。切换 preset 或 mask 时会按新模板重新整理当前值；清除、焦点、回车和变更事件保持与 Input 一致。
组合 Input 能力
Section titled “组合 Input 能力”前缀、后缀、前置标签和后置标签插槽会直接交给内部 Input。下面用前后缀补充版本号语义。
<input-mask> Props
Section titled “<input-mask> Props”除下表外，还支持 Input 的 size、allow-clear、disabled、readonly、error、placeholder、fit-width、max-w-full、word-length、word-slice、input-attrs、prepend 和 append。
| 参数名 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 当前掩码值 | string |
- |
| default-value | 非受控默认值 | string |
'' |
| mask | 固定位置掩码；优先级高于 preset |
string | readonly (string | RegExp)[] |
- |
| preset | 内置格式模板 | InputMaskPresetName |
- |
| mask-char | 固定掩码中未填写位置的字符；null 表示隐藏 |
string | null |
'_' |
| format-chars | 字符串 mask 的自定义 token | Readonly<Record<string, RegExp>> |
内置六类 token |
| always-show-mask | 空值且未聚焦时仍显示固定掩码 | boolean |
false |
| before-masked-value-change | 提交前纯函数调整值与选区 | (nextState, previousState) => InputMaskState |
- |
同时传入 mask 与 preset 时，使用 mask 的位置结构，并复用 preset 的提示和 inputmode。通常只需选择其中一种。