Introducing KickStart —  AI generated FormKit forms in seconds. Generate from a screenshot, edit with drag-and-drop or conversational AI, copy & paste as components or schema!
Try for free

专业安装快速启动 :rocket:

介绍

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

遮罩输入概览

2 分钟

基本示例

加载实时示例

遮罩

遮罩是输入的期望格式。它被传递给 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 键将焦点从一个选择范围移动到另一个:

加载实时示例
Select 模式选项

selectDirection 令牌属性控制新字符流入选定范围的方向。您可以使用 selectFill 属性填充“空”的选择字符,以预定值(如前导零 "0")。参见令牌属性

令牌

创建新令牌

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

  • 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',
}
占位符不应匹配模式

您定义的任何 placeholder 都不应该匹配令牌定义中提供的正则表达式 pattern

通过 prop 添加令牌

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

加载实时示例

全局添加令牌

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

加载实时示例

修改令牌

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

加载实时示例

字符令牌

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

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

占位符

一个 char 令牌应该只代表 1 个字符,它的占位符也应该只有单个字符的长度。

枚举令牌

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

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

加载实时示例
选择模式要求

枚举仅在 select 模式下支持。当在掩码字符串中找到任何 enum 令牌时,输入的 mode 被强制设置为 select

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

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

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

组选项

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

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

在组内定义的占位符比在令牌定义中定义的占位符具有更高的特异性,并且将覆盖它。

选项参数

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

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

加载实时示例
不能在选择模式中使用

组不能在选择模式中使用。将会抛出异常。

前缀 & 后缀

你可以通过使用 prefixsuffix 属性,分别确保某些字符始终出现在输入的开头或结尾:

加载实时示例
值不能与遮罩匹配

你的前缀和后缀内容不能与遮罩匹配。例如,如果你的遮罩有一个数字标记 #,你的前缀/后缀就不能包含数字。

反向运行遮罩

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

加载实时示例
需要移位模式

反向运行遮罩只在移位模式下工作。

遮罩值

不完整的值

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

加载实时示例

未遮罩的值

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

加载实时示例

隐藏遮罩

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

加载实时示例

覆盖层(给遮罩上色)

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

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

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

  • 字面(.formkit-overlay-literaloverlay-literal-class
  • 占位符(.formkit-overlay-placeholderoverlay-placeholder-class
  • 枚举(.formkit-overlay-enumoverlay-enum-class
  • 字符(.formkit-overlay-charoverlay-char-class

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

加载实时示例

属性 & 特性

PropType默认描述
allow-incompletebooleanfalse默认情况下,遮罩输入的值在模式完成之前为空。此属性允许输入使用不完整的值。
maskstringnone要应用的遮罩。这是由标记(如“#”)和字面字符串值组成的字符串。
modestringshift决定遮罩输入的操作方式。选项有shiftreplaceselect
overlaybooleanfalse渲染模仿文本输入的DOM元素,以允许在遮罩的样式化中进行区分。
prefixstringnone始终出现在输入开头的字符。
reversebooleanfalse反向运行遮罩 —— 从右到左。
show-maskbooleantrue显示模式占位符的实时表示作为输入的内部值。
suffixstringnone始终出现在输入末尾的字符。
tokensObject{}添加新的标记或修改现有的标记。
unmask-valuebooleanfalse默认情况下,输入的值与显示的内容相同(包括格式化)。如果设置了此属性,字符串字面值将从值中移除。
显示 通用 props
configObject{}提供给 input 的节点和此输入的任何后代节点的配置选项。
delayNumber20在调度 commit hook 前,输入值的去抖动毫秒数。
dirtyBehaviorstringtouched确定此输入的“dirty”标志设置方式。可以设置为 touchedcompare — 默认为 touched,性能更好,但无法检测表单是否再次匹配其初始状态。
errorsArray[]要在此字段上显示的错误消息的字符串数组。
helpString''帮助文本与输入关联的文本。
idStringinput_{n}输入的唯一标识符。提供一个 id 还可以全局访问输入的节点。
ignoreBooleanfalse防止将输入包含在任何父级(组、列表、表单等)中。在仅用于 UI 而不是实际值的情况下非常有用。
indexNumberundefined如果父级是列表,允许在给定索引处插入输入。如果输入的值未定义,它将继承该索引位置的值。如果它有一个值,它将在给定索引处将其插入到列表的值中。
labelString''与输入关联的 label 元素的文本。
nameStringinput_{n}输入的名称,在数据对象中唯一标识。在一组字段中应该是唯一的。
parentFormKitNodecontextual默认情况下,父级是包装组、列表或表单,但此属性允许显式分配父级节点。
prefix-iconString''指定放置在 prefixIcon 部分的 图标
preservebooleanfalse在输入卸载时,在父组、列表或表单上保留输入的值。
preserve-errorsbooleanfalse默认情况下,使用 setErrors 在输入上设置的错误会在输入时自动清除,将此属性设置为 true 可以保留错误,直到明确清除为止。
sections-schemaObject{}一个包含部分键和模式部分值的对象,其中每个模式部分应用于相应的部分。
suffix-iconString''指定放置在 suffixIcon 部分的 图标
typeStringtext要从库中渲染的输入类型。
validationString, Array[]要应用于输入的 验证 规则。
validation-visibilityStringblur确定何时显示输入的验证失败规则。有效值为 blurdirtylive
validation-labelString{label prop}确定在验证错误消息中使用的标签,默认情况下,如果可用,则使用 label 属性,否则使用 name 属性。
validation-rulesObject{}附加的自定义验证规则,可用于验证 prop。
valueAnyundefined为输入和/或其子元素提供初始值。不是响应式的。可以种子 整个组(表单)和列表。

章节

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

输入电话号码
📞
Input field
❤️
🚀
请输入您的电话号码。
电话号码是必填项。
Section-key描述
outer最外层的包装元素。
wrapper标签和输入周围的包装器。
label输入的标签。
prefix默认情况下没有输出,但允许直接在输入元素之前放置内容。
prefixIcon输出在前缀部分之前放置一个图标的元素。
inner实际输入元素周围的包装器。
suffix默认情况下没有输出,但允许直接在输入元素之后放置内容。
suffixIcon输出在后缀部分之后放置一个图标的元素。
input输入元素本身。
help包含帮助文本的元素。
messages包装所有消息的容器。
message包含消息的元素(或多个元素) - 最常见的是验证和错误消息。

可访问性

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

语义标记Aria 属性可通过键盘访问焦点指示器与提供的主题的颜色对比可访问标签、帮助文本和错误
部分键属性默认描述
labellabelfor将其与输入元素关联,提高可访问性和用户体验
inputinputdisabled禁用 HTML 元素,阻止用户交互并指示非交互状态
aria-describedby通过将元素与描述关联,增强可访问性,帮助屏幕阅读器
aria-required当需要验证时,添加所需的状态
iconiconfor每当将图标定义为标签时,将其与输入元素关联,增强可访问性和用户体验

键盘交互

键盘事件描述
Tab将焦点移动到页面上的下一个可聚焦输入。
Shift + Tab将焦点移动到页面上的上一个可聚焦输入。