MaskedTextEdit 固定格式输入

通用布局能力：RenderMaskedTextEdit 支持 width、height、min/max、margin 和槽位对齐；fieldHeight 只控制输入主体高度。详见组件通用布局属性。

RenderMaskedTextEdit 用于录入结构固定、但不参与数值运算的文本，例如病案号、固定长度编号、电话号码和自定义业务编码。

它在 RenderTextBox 的输入、选区、粘贴和 IME 会话之上增加 MaskEngine。业务保存的是不含分隔符的 raw value，界面绘制的是包含固定字符的 display value。

API 总览

主类：

• RenderMaskedTextEdit
• MaskEngine

相关 public type：

• RenderMaskedTextEditOptions
• MaskTokenDefinition
• MaskTokenDefinitions
• MaskValue
• MaskEditResult

导入：

import {  MaskEngine,  RenderMaskedTextEdit,  type MaskTokenDefinitions,  type MaskValue,} from 'ds-ui'

何时使用

适合：

• 病案号、就诊号、设备编号等固定格式字符串。
• 电话号码、邮政编码等需要自动插入分隔符的字段。
• 只允许数字、字母或字母数字组合的业务编码。
• 需要业务自定义字符规则和大小写转换的输入。

不适合：

• 普通自由文本，使用 TextField。
• 需要数值运算、范围和步进的字段，使用 NumberInput。
• 日期、时间和持续时长，分别使用 DatePicker、TimeEdit 和 TimeSpanEdit。
• 格式会根据上下文大幅变化，或者需要在同一字段中任意跳过中间段的输入。这类规则应由专用编辑器承担。

最小示例

import { RenderMaskedTextEdit } from 'ds-ui' const patientState = {  phone: '',} const phone = new RenderMaskedTextEdit({  mask: '000-0000-0000',  value: patientState.phone,  placeholder: '输入手机号',  clearable: true,  onChange: (value, details) => {    patientState.phone = value    console.log(details.display, details.complete)  },})

输入 13800138000 后：

phone.value        // '13800138000'
phone.displayValue // '138-0013-8000'
phone.complete     // true

值模型

组件同时维护两种值：

构造参数和运行时属性 value 都接收 raw value。写入时会：

1. 按 mask 槽位逐个 Unicode code point 检查。
2. 丢弃不符合当前槽位的字符。
3. 超过 mask 容量的字符会被截断。
4. 重新生成 displayValue 和 complete。

程序直接写入 edit.value 或调用 reset() 不会触发 onChange。

const code = new RenderMaskedTextEdit({  mask: 'AA-0000',  value: 'ab12x34',}) code.value        // 'ab1234'code.displayValue // 'ab-1234'

固定字符按输入进度显示，不会为尚未填写的槽位绘制 prompt character。例如 mask 为 000-000 时：

内置 mask token

其他字符按固定文本处理：

const dateLikeCode = new RenderMaskedTextEdit({  mask: '0000-00-00',})

这里的两个 - 由组件自动插入，不属于 raw value。

转义 token

反斜杠 \ 会把下一个字符转成固定文本。因为 TypeScript 字符串本身也使用反斜杠转义，代码中通常需要写成 \\：

const prefixedCode = new RenderMaskedTextEdit({  // 界面格式：A-BF；第一个 A 是固定字符，两个 X 是自定义槽位。  mask: '\\A-XX',  definitions: {    X: {      pattern: /[A-F]/i,      transform: character => character.toUpperCase(),    },  },  value: 'bf',})

如果希望数字 0、字母 A 等内置 token 作为固定字符显示，也必须转义。

自定义 token

definitions 会与内置 token 合并；相同 key 会覆盖内置定义。

interface MaskTokenDefinition {  readonly pattern: RegExp  readonly required?: boolean  readonly transform?: (character: string) => string} type MaskTokenDefinitions =  Readonly<Record<string, MaskTokenDefinition>>

示例：

const upperHexDefinitions: MaskTokenDefinitions = {  X: {    pattern: /[0-9a-f]/i,    required: true,    transform: character => character.toUpperCase(),  },} const colorCode = new RenderMaskedTextEdit({  mask: '\\#XXXXXX',  definitions: upperHexDefinitions,  value: '12abef',}) colorCode.value        // '12ABEF'colorCode.displayValue // '#12ABEF'

自定义定义的约束：

• pattern 应检查单个 Unicode code point。
• required 省略时按 true 处理。
• transform 必须返回一个 Unicode code point。
• 转换后的字符仍必须通过 pattern，否则会被丢弃。
• 可选 token 是顺序槽位，不能跳过中间可选槽位后继续填写后面的必填槽位。因此可选 token 优先放在 mask 尾部。

构造参数

构造 MaskEngine 时，空 mask 或不包含任何 token 的 mask 会直接抛出错误，避免生成一个看似可编辑、实际上没有输入槽位的字段。

MaskValue

interface MaskValue {  readonly raw: string  readonly display: string  readonly complete: boolean  readonly rawToDisplay: readonly number[]  readonly displayToRaw: readonly number[]}

普通表单通常只使用 raw、display 和 complete。两个位置映射主要供自定义编辑宿主、诊断和精确恢复选区使用。编辑器按完整 code point 占用一个 mask 槽位；如果浏览器给出的选区落在代理对内部，替换和删除会安全地归到该槽位边界。

这里承诺的是 Unicode code point，而不是用户感知的 grapheme cluster。由多个 code point 组成的 emoji、变音组合或复杂文字簇会占用多个槽位；需要按字素簇编辑时，应使用专门的文本编辑组件。

属性和方法

不要直接写 edit.textBox.value。这会绕过 raw/display 同步；业务应写 edit.value 或调用 reset()。

MaskEngine

MaskEngine 是无界面的纯值工具，可用于 DataGrid 编辑适配、批量格式化和单元测试：

const engine = new MaskEngine('000-000') engine.formatRaw('1234').display// '123-4' engine.normalize('123-456').raw// '123456'

normalizeDisplay、replace 和 delete 返回 MaskEditResult，它在 MaskValue 基础上增加 selectionStart 和 selectionEnd。

键盘、粘贴和 IME

L、?、A、a 使用 Unicode 字母规则，所以可以接受中文。数字 token 会在 IME 确认后拒绝中文输入。

回调时机

• onChange 的第一参数始终是 raw value。
• details 是同一时刻的完整 MaskValue。
• 固定字符插入、无效字符过滤和选区修正都在回调之前完成。
• 只有规范化后的值实际变化时才触发 onChange；被 mask 完全拒绝的输入不会产生不变值通知。
• 程序写入 value 和调用 reset() 不触发 onChange，同时会清空当前撤销/重做历史，避免撤销回到已经失效的外部状态。
• onSubmit 和 onBlur 会先根据当前显示文本刷新 raw/display，再执行回调。

只读和禁用

当前边界

• mask 是构造期配置，组件不提供运行时替换 mask 的 setter。mask 变化时应重建组件。
• 不显示未填写槽位的下划线或 prompt character。
• 不内置正负数、小数、千分位、日期合法性或时间范围校验；这些应由对应的专业输入组件处理。
• 可选槽位采用顺序填充，推荐只把可选 token 放在末尾。
• complete 只表示必填槽位已填满，不代表业务值一定有效。例如 2026-99-99 可以填满日期形状，但仍需业务日期校验。
• 当前没有作为 DataGrid 内置列编辑类型；需要表格内使用时，应由后续明确的 Grid editor contract 接入。

相关组件

• TextField
• NumberInput
• TimeEdit
• ButtonEdit