Smart Input 引擎：能力与实现

普通文本框用原生 <input> 足矣。可一旦要「边输入边格式化」或「按规则拦截」，实现者会依次遇到 IME 合成、光标漂移、原生 undo 撕碎格式、粘贴带富文本、拦截时机五个浏览器层问题。@vega/smart-input 把这五点统一封装，让调用方只描述一个 Formatter——允许什么字符、如何规范化、是否合法、怎么渲染。本页沿数据流自底向上拆开这台引擎：先看它提供哪些能力，再看每项能力具体怎么实现。两个落地 demo 见 格式化合集 与 规则输入框。

1 · 原生 input 的五个陷阱，与引擎的接管

每一项都是「自己实现 masking 时绕不开、且极易写错」的浏览器细节。引擎把它们收敛进同一条管线，调用方不再感知。

2 · 两层 API:helper 与 createSmartInput

引擎分两层。底层是五个互不依赖的 helper（自己拼装事件源 / 多元素联动时直接取用）；高阶 createSmartInput 把这五个 helper 串成一条管线，只接收一个 Formatter。

3 · Formatter 契约：七个可选字段

Formatter 描述「这个框接受什么、显示什么」，完全不感知 DOM 事件 / 历史 / IME。七个字段全部可选，未提供时落到合理默认。这是调用方唯一要写的东西。

最小可运行例子（hex 颜色输入框，输入即归一为小写、6 位即把背景刷成该色）：

import { createSmartInput } from '@vega/smart-input';

createSmartInput({
  el: document.querySelector('#color') as HTMLInputElement,
  formatter: {
    allowChar: (ch) => /[0-9a-fA-F]/.test(ch),
    normalize: (text, caret) => ({
      text: text.toLowerCase().slice(0, 6),
      caret: Math.min(caret, 6),
    }),
    validate: (text) =>
      text.length === 6
        ? { kind: 'valid', value: '#' + text }
        : { kind: 'partial' },
  },
  onChange: ({ result }) => {
    if (result.kind === 'valid') document.body.style.background = result.value;
  },
});

4 · 核心管线：refresh → normalize → strict 守门 → apply → commit

每次 DOM 事件都走同一条 refresh 管线。它把「读 DOM → 归一 → 守门 → 写回 → 提交历史」串成五步，其中所有 DOM 写入都集中在 apply() 一处；undo / redo 则共用 apply() 但不提交历史。

下面把这台引擎接到一个真实电话号 formatter 上——边输入边看每一步的可观察产物：

试试：打 13800001111 → 实时分组成 138 0000 1111；打字母 → allowChar 拦截（闪红）；把光标移到中间删一位 → caret 按字符重映射不漂；Ctrl/Cmd+Z 整段回退；开 strict 后在空框打 2 → 没有 2 字头的合法号，直接被吞；用拼音打中文 → IME 徽标亮起，合成期间不进校验。

5 · normalize:single source of truth 与光标重映射

normalize 返回的 text 是引擎的唯一可信源——history 存它、DOM 写它。当 normalize 往文本里插入字符（空格 / 横线 / 千分位逗号），光标必须同步重算，否则在中间删一位时光标会停在原偏移、有时正好落进分隔符里。这是「边输入边格式化」最容易写错的一块。

你不用自己算光标：返回 anchor 形态 { text, caretAfter, anchorClass }——只声明「哪些字符算有效(anchorClass)」+「光标逻辑上落在第几个有效字符之后(caretAfter)」，引擎负责把它换算到插了分隔符的 formatted 域。你只做两步：抽有效字符并顺带数光标前有几个 → 插分隔符：

import { isDigit } from '@vega/smart-input/helpers';

normalize: (raw, caret) => {
  // ① 抽有效字符,顺带数光标前有几个(这一步的丢弃规则是 formatter 特有的)
  let digits = '';
  let digitsBeforeCaret = 0;
  for (let i = 0; i < raw.length; i++) {
    if (raw[i] >= '0' && raw[i] <= '9') {
      digits += raw[i];
      if (i < caret) digitsBeforeCaret++;
    }
  }
  digits = digits.slice(0, 11);

  // ② 插分隔符
  let out = digits.slice(0, 3);
  if (digits.length >= 4) out += ' ' + digits.slice(3, 7);
  if (digits.length >= 8) out += ' ' + digits.slice(7, 11);

  // ③ 光标交给引擎:落到「第 digitsBeforeCaret 个数字之后」,无需再手写映射
  return { text: out, caretAfter: digitsBeforeCaret, anchorClass: isDigit };
}

引擎内部就是「数 formatted 里第 N 个有效字符、落到它之后」这一步（想手写或做更复杂映射，caretAfterNthInClass / remapCaretByClass 也从 /helpers 导出）。若变换是保序的（仅大小写归一 / 末尾截断，不插字符），更省事：直接返回 string，引擎用公共前缀 / 后缀锚定自动推断光标。三种形态覆盖了从最省心到完全手动的整条谱系。

6 · 两道关：allowChar（字符级）与 isExtendable（整体级）

allowChar 限定单个字符的字符集；isExtendable 判断整段文本是否仍可扩展成合法值。启用 strict: true 后，beforeinput 会模拟插入并跑 isExtendable，未通过的按键直接拒、不进 DOM。

createSmartInput({
  el: phoneEl,
  strict: true,
  formatter: {
    allowChar: (ch) => /\d/.test(ch),
    isExtendable: (s) => {
      const digits = s.replace(/ /g, '');
      return digits.length <= 11 && (digits === '' || digits[0] === '1');
    },
  },
});

7 · 逻辑层 history：为什么不用原生 undo

每次输入后引擎都重写 DOM（覆写 value / innerHTML），浏览器的撤销栈会被砸坏到无法挽救。于是改为自维护一份 snapshot 栈，Ctrl+Z 回退到「用户停顿」粒度。

8 · IME 合成：被忽略的 preventDefault 与 keyCode 229

中文 / 日文经 IME 组字上屏：按键先交给输入法，keydown 全变 keyCode 229、isComposing: true，靠 compositionstart / update / end 完成上屏。合成期间 beforeinput 的 preventDefault 被浏览器忽略，且 input 会随每次候选词更新触发——此时重写 DOM 必然破坏 IME 状态。引擎的统一做法：合成期间跳过校验与 refresh,compositionend 后跑一次防御性 refresh（让 normalize / rebuild 收尾清理）并 hardBreak。

import { isImeComposingKey } from '@vega/smart-input';

el.addEventListener('keydown', (e) => {
  if (isImeComposingKey(e)) return;
  if (e.key === 'Enter') submit();
});

function isImeComposingKey(e: KeyboardEvent): boolean {
  return e.isComposing || e.keyCode === 229;
}

9 · caret：跨 DOM 重写保持的字符偏移

<input> 有现成的 selectionStart；但 contenteditable 重写 innerHTML 后，原生 Range 会失效。引擎统一把光标抽象成「root.textContent 里第 N 个字符」，用 TreeWalker 遍历文本节点累加长度来读 / 写偏移。这样无论 renderHtml 把文本拆成多少层 <span>，光标都能稳定落回原字符位置。

function getCaretOffset(root: HTMLElement): number {
  const sel = window.getSelection();
  if (!sel || sel.rangeCount === 0) return 0;
  const range = sel.getRangeAt(0);
  const pre = document.createRange();
  pre.selectNodeContents(root);
  pre.setEnd(range.endContainer, range.endOffset);
  return pre.toString().length;
}

function setCaretOffset(root: HTMLElement, offset: number): void {
  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
  let remaining = offset;
  let node = walker.nextNode() as Text | null;
  while (node) {
    if (remaining <= node.data.length) {
      const range = document.createRange();
      range.setStart(node, remaining);
      range.collapse(true);
      const sel = window.getSelection();
      sel.removeAllRanges();
      sel.addRange(range);
      return;
    }
    remaining -= node.data.length;
    node = walker.nextNode() as Text | null;
  }
}

10 · asyncValidate:pending 态与竞态取消

「用户名是否被占用」这类需要网络的判断走 asyncValidate。它仅在 sync validate 已 valid 时触发：引擎先把结果替换为 { kind: 'pending' } 派发一次（让 UI 画 loading），再调本函数；结果到达时以 trigger='async' 再派发。

asyncValidate: async (text, signal) => {
  const res = await fetch('/api/check-username?name=' + text, { signal });
  const { taken } = await res.json();
  return taken
    ? { kind: 'invalid', error: '已被占用' }
    : { kind: 'valid', value: text };
}

11 · renderHtml：富渲染与 textContent 约束

把 el 换成 <div>（引擎自动设 contenteditable）即可启用 renderHtml：文本 → HTML 字符串，写进 innerHTML 做字符级染色。配套的 html tagged template 自动 escape 插值，防止用户输入的 < > & 被当 HTML 解析。

import { createSmartInput, html } from '@vega/smart-input';

createSmartInput({
  el: document.querySelector('#color') as HTMLDivElement,
  formatter: {
    allowChar: (ch) => /[0-9a-fA-F]/.test(ch),
    normalize: (text, caret) => ({
      text: text.toLowerCase().slice(0, 6),
      caret: Math.min(caret, 6),
    }),
    renderHtml: (text) => {
      const r = text.slice(0, 2);
      const g = text.slice(2, 4);
      const b = text.slice(4, 6);
      return (
        (r ? html`<span style="color:#c33">${r}</span>` : '') +
        (g ? html`<span style="color:#3a3">${g}</span>` : '') +
        (b ? html`<span style="color:#36c">${b}</span>` : '')
      );
    },
  },
});

12 · Trigger 八态与生命周期

每次 onChange 都带一个 trigger，让调用方区分用户键入与程序化操作。运行时还可换 formatter / 配置、或仅重评估当前文本而不动 DOM。

api.setText(text, caret?) 程序化设值（走完整 refresh、进 history）;api.update({ formatter?, strict?, onChange?, debug? }) 运行时换配置后立即对当前文本跑一次完整管线；api.revalidate() 仅重跑 validate 并派发 onChange（外部依赖如 min/max 变了时用），不写 DOM、不进 history。

13 · 相关链接

• @vega/smart-input · README · 本仓库——本页的源出处：完整 API、quick start、数据流图、底层 helper 装配示例与开箱即用 formatter 表。
• MDN · beforeinput event · developer.mozilla.org——对应「拦截」与「IME」两节：inputType 取值、preventDefault 的可取消性，以及合成期间为何被忽略。
• MDN · compositionstart / compositionend · developer.mozilla.org——对应「IME 合成」节：组字的事件序列，以及 isComposing 信号的边界。
• imask · cleave.js · npm——同类的开箱即用 mask 控件；本包定位为构建这类组件的底层库，可作对照。
• 表单输入 · 格式化合集——本引擎的五个落地场景：千分位 number、HH:MM:SS strict 守门、6 位 OTP、tag chip、IME-safe Enter 提交。
• 表单输入 · 规则输入框——最复杂用例：动作规则 DSL 的 masking / renderHtml 富渲染 / strict 前缀守门三框渐进展示。