Mask

• 简介
• 基本示例
• 遮罩
  • 内置令牌
  • 转义内置令牌
• 模式
  • Shift & replace 模式
  • Select 模式
• 令牌
  • 创建新令牌
  • 修改令牌
  • 字符令牌
  • 枚举令牌
• 组
  • 组选项
• 前缀 & 后缀
• 反向运行掩码
• 掩码值
  • 不完整的值
  • 未掩码的值
• 隐藏掩码
• 覆盖层（对遮罩进行着色）
• 属性和特性
• 章节

简介

mask 输入会自动将用户输入转换为匹配提供的格式。如果使用得当，遮罩输入可以通过消除所需值的任何模糊性（例如电话号码或社会保障号码）来提供改善的用户体验。

基本示例

遮罩

遮罩是输入的期望格式。它被传递给 mask 属性，然后解析为令牌。遮罩包括：

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

内置令牌

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

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

转义内置令牌

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

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

模式

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

• Shift（默认）
• Replace
• Select

Shift & 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 属性禁用此行为（除在选择模式中），同时仍然自动应用格式：

覆盖层（对遮罩进行着色）

默认情况下，遮罩的值通过其输入元素的值显示。虽然这个功能"开箱即用"，但它不允许文本在样式上进行区分。例如，如果遮罩的"字面"部分看起来与"占位符"部分不同，那就好了。

为了实现这种效果，你可以启用一个覆盖层，它会渲染直接位于输入本身上方的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）

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

属性和特性

章节

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