企业官网建设流程全解析

• 前端
• UI组件

Colormask 是 Inputmask 提供的一个扩展：它与标准 Inputmask 完全同源，但额外允许你为"掩码本身"（静态字符、占位符与光标）单独指定颜色，使其与用户输入的文本颜色相互独立。本文以仓库中的官方文档 Colormask.md 为主体，结合 lib/extensions/colormask.js 与 lib/extensions/colormask.css 的源码实现，完整讲解 Colormask 的引入方式、基础用法、样式定制原理与底层渲染机制，读完你就能在自己的表单中落地一套"灰色静态掩码 + 正常颜色输入"的经典交互方案。

一、Colormask 是什么

官方文档对它的定位一句话可以概括：Colormask 与 Inputmask 功能完全一致，区别仅在于它允许你为掩码指定一种颜色。这一特性在以下场景中尤其有用：

• 掩码中的静态字符（如-、(、)、空格）与用户输入内容希望呈现不同颜色；
• 输入尚未完成时，占位符与光标需要以弱化（例如灰色）的方式呈现，突出用户已经键入的文本；
• 表单视觉上需要"引导式"输入框，掩码看起来像底纹/水印，而真实输入浮于其上。

从源码看，Colormask构造器并未重新实现掩码逻辑，而是直接复用 Inputmask 的能力：

// lib/extensions/colormask.js function Colormask(alias, options, internal) { // 允许不带 new 直接调用 if (!(this instanceof Colormask)) { return new Colormask(alias, options, internal); } this.colorMask = undefined; Object.getOwnPropertyNames(Inputmask).forEach(function (key) { if (!Object.prototype.hasOwnProperty.call(this, key)) { this[key] = Inputmask[key]; } }, this); } Colormask.prototype = Inputmask.prototype;

可见 Colormask 以Inputmask.prototype为原型，所有 mask 配置、校验、事件处理能力全部继承自 Inputmask，额外只挂载了几个"钩子"（hook）来接管渲染，这正是"与 inputmask 相同但多了配色"这一说法的源码依据。

二、安装与引入

2.1 经典<script>标签方式

官方文档指出，使用浏览器脚本方式时，需要引入dist目录下（构建产物）的两个文件：

<link rel="stylesheet" href="colormask.css" /> <script src="colormask.js"></script>

仓库中对应的产物确实存在：dist/colormask.css 与 dist/colormask.js。此外 webpack.config.js 中为 Colormask 单独配置了名为colormask的构建任务（入口为 bundle.colormask.js），产出dist/colormask与dist/colormask.min两套文件，并同时生成 ES Module 版本dist/esm/colormask.mjs。如果你需要从源码自行构建，可在仓库根目录运行：

npm run colormask

2.2 ES Module / Bundler 方式

在打包工具（webpack、Vite、Rollup 等）中使用时，官方文档给出的标准写法是：

import "inputmask/colormask.css"; import Colormask from "inputmask/colormask"; Colormask({ mask: "999-999-9999" }).mask(selector);

这里inputmask/colormask之所以可用，是因为 package.json 的exports字段显式声明了./colormask子路径，并同时提供了类型声明（dist/types/extensions/colormask.d.ts）、ESM 构建（dist/esm/colormask.mjs）与 CommonJS 构建（dist/colormask.js）：

"./colormask": { "types": "./dist/types/extensions/colormask.d.ts", "import": "./dist/esm/colormask.mjs", "require": "./dist/colormask.js" }

2.3 子路径导出无法解析时的兜底写法

如果你的打包器（如某些旧版本工具或特定配置）不解析inputmask/*这样的 subpath exports，官方文档明确给出了降级方案——直接使用dist目录下的文件：

import "inputmask/dist/colormask.css"; import Colormask from "inputmask/dist/colormask.js";

这与文档中"Classic web"方式指向同一份构建产物，只是改由打包器来管理依赖。另外，package.json中files字段包含dist/与lib/，因此两种路径在安装后的 node_modules 中都是可用的。

三、基本使用

Colormask 的使用方式与 Inputmask 几乎完全一致，只是把Inputmask(...)换成Colormask(...)：

import "inputmask/colormask.css"; import Colormask from "inputmask/colormask"; // 10 位电话号码掩码：数字以灰色静态样式呈现，输入文本以正常颜色呈现 Colormask({ mask: "999-999-9999" }).mask(document.querySelector("#phone"));

• selector可以是任何 DOM 元素选择器或元素本身，与 Inputmask 的mask()行为一致；
• 所有 Inputmask 支持的选项（如placeholder、jitMasking、rightAlign、isRTL等）理论上都可直接传给Colormask({ ... })，因为它继承自Inputmask.prototype；
• 由于构造器内部做了this instanceof Colormask判断，即使忘记写new也不会报错（见 lib/extensions/colormask.js）。

在浏览器全局环境下，脚本方式引入后可通过window.Colormask访问（源码末尾有window.Colormask = Colormask;的挂载），用法同样为：

Colormask({ mask: "999-999-9999" }).mask(".my-input");

四、通过 colormask.css 定制掩码配色

文档强调：使用前请先查看样式表colormask.css，将颜色调整为你需要的值。整个 Colormask 的"双色"效果完全由样式驱动，因此理解这份样式表是定制的关键。以下逐条解读 lib/extensions/colormask.css（dist/colormask.css为同名构建产物）：

mark.im-caret { animation: 1s blink step-end infinite !important; } mark.im-caret-select { background-color: rgba(0, 0, 0, 0.25); } @keyframes blink { from, to { border-right-color: black; } 50% { border-right-color: white; } } span.im-static { color: grey; } div.im-colormask { display: inline-block; border-style: groove; border-width: 1px; appearance: textfield; cursor: text; } div.im-colormask > input, div.im-colormask > input:-webkit-autofill { position: absolute !important; display: inline-block; background-color: transparent; color: transparent; -webkit-text-fill-color: transparent; transition: background-color 5000s ease-in-out 0s; caret-color: transparent; text-shadow: none; appearance: textfield; border-style: none; left: 0; /*calculated*/ } div.im-colormask > input:focus { outline: none; } div.im-colormask > input::selection { background: none; } div.im-colormask > input::-moz-selection { background: none; } div.im-colormask > input:-webkit-autofill ~ div { background-color: rgb(255, 255, 255); } div.im-colormask > div { color: black; display: inline-block; width: 100px; /*calculated*/ }

这些规则对应了 Colormask 渲染出的三类元素（具体结构见下文源码剖析）：

关键设计在于：真实的<input>元素文字是透明的（color: transparent; caret-color: transparent），用户看到的"输入内容"实际由内层<div>的模板渲染，掩码静态字符由span.im-static渲染。因此只需分别调整span.im-static与div.im-colormask > div两处的颜色，就能实现"掩码一个颜色、输入另一个颜色"。其中-webkit-text-fill-color: transparent与caret-color: transparent还处理了 WebKit 内核下自动填充与光标显示的问题。

五、源码剖析：双色效果是如何渲染出来的

阅读 lib/extensions/colormask.js 可以确认，Colormask 并没有改动 Inputmask 的掩码算法，而是通过 4 个钩子介入渲染流程：

Colormask.prototype.writeBufferHook = function (caretPos) { renderColorMask.call(this, this.el, caretPos, false); }; Colormask.prototype.caretHook = function (caretPos) { renderColorMask.call(this, this.el, caretPos, false); }; Colormask.prototype.applyMaskHook = function () { initializeColorMask.call(this, this.el); }; Colormask.prototype.keyEventHook = function (e) { if (e.key === keys.ArrowRight || e.key === keys.ArrowLeft) { // 方向键移动光标后异步重渲染，保持光标与掩码同步 setTimeout(function () { renderColorMask.call(inputmask, inputmask.el, caretPos); }, 0); } };

其中：

• applyMaskHook：在掩码应用时调用initializeColorMask，负责 DOM 结构改造——创建一个div.im-colormask容器，把原始<input>移入其中，再创建一个模板<div>紧跟在输入框后面，并把输入框设为绝对定位（input.style.left = template.offsetLeft + "px"）。同时为容器绑定mouseleave/mouseenter/click事件，点击时会通过findCaretPos根据点击的clientX坐标、借助克隆字体样式测量文本宽度，反推光标应落到的位置（见 lib/extensions/colormask.js）；
• writeBufferHook/caretHook：在写入缓冲区或光标变化时调用renderColorMask重绘模板；
• keyEventHook：方向键移动时异步重绘，确保光标标记位置正确。

renderColorMask是渲染核心（lib/extensions/colormask.js）：它遍历maskset.validPositions与getTestTemplate，将缓冲区内容拼接为 HTML 模板：

• 静态字符段（test.static === true或该位置尚无输入）被包裹进span.im-static；
• 输入字符段按原样输出；
• 当前光标位置插入mark.im-caret（单字符）或mark.im-caret-select（多字符选区）标记；
• 同时兼容jitMasking占位符渲染（未输入位置输出getPlaceholder）与isRTL方向（RTL 下模板会 reverse 且静态/光标标签的起止顺序反转）。

因此你可以推断：Colormask 的所有静态样式类（im-static、im-caret、im-caret-select、im-colormask）均由源码在运行时生成，与 lib/extensions/colormask.css 中的选择器一一对应——这正是文档要求"先看样式表、再调颜色"的原因。

六、注意事项与使用建议

1. 必须同时引入 CSS 与 JS：colormask.css负责把真实输入框文字透明化并定义静态字符颜色，缺少样式文件时会出现文字重叠或双色失效；
2. 定制入口明确：掩码颜色改span.im-static的color，输入文本颜色改div.im-colormask > div的color，光标颜色改@keyframes blink的border-right-color；
3. 事件绑定在容器上：鼠标进入/离开/点击事件被绑定到div.im-colormask容器而非<input>本身，若你的页面样式重置了该容器的cursor或边框，请以 lib/extensions/colormask.css 中的默认值为基准；
4. 方向键与点击定位：点击掩码空白处会按字符宽度测算光标位置，因此自定义字体（尤其等宽/非等宽字体）可能影响点击定位精度，建议保持字体、letter-spacing、text-transform等样式稳定；
5. 构建与产物：源码入口为 lib/extensions/colormask.js（浏览器全局变量为window.Colormask），打包入口为 bundle.colormask.js，发布到 npm 的子路径映射见 package.json 的exports字段，类型定义见 dist/types/extensions/colormask.d.ts；
6. 与 Inputmask 的关系：Colormask 不改变掩码语法、校验规则与事件体系，任何已掌握 Inputmask 配置经验的开发者都可以零成本迁移，只需将构造器名称替换并引入对应样式与脚本即可。

七、官方文档对照

本文所依据的官方文档为 inputmask-pages/src/assets/Colormask.md，其在文档站中的渲染组件为 inputmask-pages/src/Components/Colormask/Colormask.js（通过MarkDownPage渲染 Markdown 并生成目录 TOC，Colormask.lazy.js 提供懒加载）；仓库 inputmask-pages/src/assets/Documentation.md 的 Colormask 章节也给出了与本文一致的模块化引入示例。文中所列代码、样式类名与钩子名称均可在上述源码与产物文件中逐一核实。

• 前端
• UI组件