Mask

• 介绍
• 基本示例
• 遮罩
  • 内置令牌
  • 转义内置令牌
• 模式
  • Shift 和 replace 模式
  • Select 模式
• 令牌
  • 创建新令牌
  • 修改令牌
  • 字符令牌
  • 枚举令牌
• 组
  • 组选项
• 前缀 & 后缀
• 反向运行遮罩
• 遮罩值
  • 不完整的值
  • 未遮罩的值
• 隐藏遮罩
• 覆盖层（给遮罩上色）
• 属性 & 特性
• 章节
• 可访问性
  • 键盘交互

介绍

mask 输入会自动转换用户输入以匹配提供的格式。适当使用遮罩输入可以通过消除对期望值的任何歧义（例如电话号码或社会安全号码）来提供改善的用户体验。

基本示例

遮罩

遮罩是输入的期望格式。它被传递给 mask 属性，在那里它被解析为令牌。遮罩由以下部分组成：

• 令牌 - 用户可编辑区域的字符串表示。下面以白色显示。
• 字符串字面量 - 任何不是令牌的字符。不可由用户编辑。下面以橙色显示。

内置令牌

遮罩输入带有 4 个内置令牌：

• h - 接受一个十六进制字符（0-9a-fA-F）。
• # - 接受一个数字字符。
• a - 接受一个字母字符。
• * - 接受任何字符。

转义内置令牌

如果您需要在遮罩中将内置令牌之一用作字符串字面量，您可以使用 \ 来转义它们。这里我们正在转义井号 # 以在我们的十六进制颜色中使用：

<FormKit mask="\#hhhhhh" type="mask" />

模式

遮罩输入支持 3 种输入模式：

• Shift（默认）
• Replace
• Select

Shift 和 replace 模式

默认情况下，当输入时，遮罩的字符会自动向前移动。当遮罩已经填充并且您将光标放在输入的开头或附近开始输入时，这一点尤其明显。随着您的输入，跟随您的光标的字符会被“移动”向前。然而，在 replace 模式下，随后的字符会被新值覆盖：

Select 模式

在 select 模式下，相同的 char 类型令牌被分组成可选择的文本范围。FormKit 在点击或聚焦输入时自动选择这些文本范围。用户输入时，这些选择范围会被保持。当谨慎使用时，这会产生清晰的用户体验，因为用户知道他们预期输入什么值。

此外，当输入处于 select 模式时，用户可以使用箭头或 tab 键将焦点从一个选择范围移动到另一个：

令牌

创建新令牌

如果一个模式可以在同一位置接受字母 或 数字怎么办？创建新令牌相对简单。有两种类型的令牌：

• char 接受单个字符。
• enum 接受来自可能值数组的任何字符串。

创建新令牌必须定义以下属性：

{
  /**
   * 令牌的类型。可以是 `char` 或 `enum`。
   */
  type: 'char',
  /**
   * 从掩码中解析出的令牌。
   */
  token: 'z',
  /**
   * 当 `show-mask` 启用时，在输入框中显示的占位符字符。
   */
  placeholder: '_',
  /**
   * 在使用 `select` 模式时，确定新字符流动的方向。
   */
  selectDirection: 'left',
  /**
   * （仅限 `char` 类型）。描述可以出现在此槽中的字符类型的正则表达式。
   * 这个模式将针对单个字符进行评估 — 而不是在整个字符串的上下文中。
   */
  pattern: /[A-Za-z0-9]/,
  /**
   * （仅限 `char` 类型，可选）。在选择模式下用来“填充”选择范围的可选字符。
   * 例如，将 selectFill 设置为 "0" 可以在数字中产生前导零，如 "001"。
   */
  selectFill: "0",
  /**
   * （仅限 `enum` 类型）。可能值的数组。
   */
  values: [
    'March',
    'April',
    'May'
  ],
}

例如，一个接受字母和数字的新令牌，并且在掩码字符串中由字母 z 表示，看起来会像这样：

{
  type: 'char',
  token: 'z',
  pattern: /[A-Za-z0-9]/,
  placeholder: '_',
  selectDirection: 'left',
}

通过 prop 添加令牌

要将新令牌传递给掩码输入，您可以使用 tokens prop，它期望一个键与 token 属性匹配的对象。例如，我们上面示例中的新令牌可以直接应用：

全局添加令牌

要全局注册您的掩码令牌，请扩展您全局 FormKit 配置的 config 属性：

修改令牌

除了创建新令牌外，tokens 属性也可以修改现有令牌。提供给 tokens 属性的任何值都将合并到该输入的现有令牌中。例如，数字令牌（#）默认情况下没有 selectFill。要添加一个，只需扩展它：

字符令牌

char 令牌接受单个字符。为了让一个字符被接受，它必须匹配 token.pattern 正则表达式。四个内置令牌（h、#、a 和 *）都是 char 类型的令牌。

在 select 模式下，char 令牌被组合成一个选择范围。

枚举令牌

枚举令牌允许在预定义的选项集内使用可变长度的掩码。当用户开始输入时，枚举令牌的值将变为第一个匹配的值，并且选择范围将反映当前未匹配的字符。实际上，这操作非常像是特定令牌的自动完成。此外，用户可以通过按上/下箭头键来循环浏览给定令牌的可用选项。

一个带有自动完成月份名称的日期可以很好地用枚举表示：

组

组是将多个掩码字符视为单个单元的一种方式。你可以通过用 {} 包围所需的掩码字符来创建一个组：

<FormKit mask="id{-a#a}" type="mask" />
<!-- "-a#a" 是组 -->

如果你不定义组选项，组本身不会做任何事情。

组选项

组选项允许你使用管道 | 后跟选项名称和任何参数，将功能应用于整个组。可用的选项包括：

• repeat — 允许一个组无限次重复。
• placeholder — 在用户输入之前占位的字符。

选项参数

可以通过使用冒号将参数传递给组选项，例如 placeholder:+，其中加号 + 被传递给 placeholder 选项。

你可以将组选项串联起来：

前缀 & 后缀

你可以通过使用 prefix 和 suffix 属性，分别确保某些字符始终出现在输入的开头或结尾：

反向运行遮罩

在特定情况下，你可能想要反向运行你的遮罩。遮罩将测试用户输入是否从右到左满足遮罩。这在货币类型输入中很常见，并且可以通过添加 reverse 属性来应用：

遮罩值

不完整的值

遮罩的值在用户填满整个模式之前不被视为“完整”。在那之前，FormKit 将视输入的值为“空”。这使得它方便与像 required 这样的验证规则一起使用。然而，如果你愿意接受不完整的值，你可以通过 allow-incomplete 属性来实现：

未遮罩的值

默认情况下，遮罩输入的值包括通过 mask 属性提供的格式。然而，如果你想要原始的未遮罩值，并移除字符串字面量，你可以使用 unmask-value 属性：

隐藏遮罩

默认情况下，mask 输入显示每个标记的占位符字符。你可以禁用这种行为（选择模式除外），同时通过 show-mask 属性自动应用格式：

覆盖层（给遮罩上色）

默认情况下，遮罩的值通过其输入元素的值显示。虽然这种方式“开箱即用”，但它不允许文本在样式上有所区分。例如，如果遮罩的“字面”部分与“占位符”部分看起来不同，那会很好。

为了实现这种效果，你可以启用一个overlay，它会渲染直接定位在输入框上方的DOM元素。输入框内的文本仍然存在，但它会变成透明的。通常，必要的覆盖层定位样式会自动为你应用。

覆盖层包含4个可能的部分，你可以在其中定位你的样式：

• 字面（.formkit-overlay-literal 或 overlay-literal-class）
• 占位符（.formkit-overlay-placeholder 或 overlay-placeholder-class）
• 枚举（.formkit-overlay-enum 或 overlay-enum-class）
• 字符（.formkit-overlay-char 或 overlay-char-class）

默认的genesis主题自动支持覆盖层，并将占位符应用浅灰色。如果你没有使用Genesis，请确保inner部分已定位（如position: relative）。

属性 & 特性

章节

您可以通过使用该部分的"key"来定位输入的特定部分，从而可以修改该部分的类、HTML（通过:sections-schema）或内容（通过插槽)）。了解更多关于部分的信息，请点击这里。

可访问性

所有 FormKit 输入都是考虑到以下可访问性因素而设计的。通过在此处提交可访问性问题，帮助我们不断提高所有人的可访问性：

键盘交互