跳到主要内容
版本：v8

ion-input-otp

scoped

Input OTP 组件是一个专门用于输入一次性密码（OTP）的输入组件。它提供了一个用户友好的验证码输入界面，支持多个输入框和自动焦点管理。

基本用法​

该组件默认提供 4 个输入框，这是许多验证码的常见长度。可以使用 length 属性自定义输入框的数量。

类型​

type 属性决定输入格式，支持数字或字母数字验证码。它接受两个值：number 和 text。默认使用 type="number" 输入数字验证码。当指定 type="text" 时，它接受字母数字输入。这种灵活性允许处理不同的 OTP 格式，无论是纯数字代码（如短信验证码）还是字母数字代码（如备份代码或恢复密钥）。

type 属性会自动设置 inputmode 和 pattern 属性：

  • 当 type="number" 时：
    • 设置 inputmode="numeric" 以在移动设备上显示数字键盘
    • 设置 pattern="[\p{N}]" 以仅允许数字输入
  • 当 type="text" 时：
    • 设置 inputmode="text" 以显示标准键盘
    • 设置 pattern="[\p{L}\p{N}]" 以允许字母数字输入

有关模式验证和自定义的更多详细信息，请参阅模式部分。

形状​

shape 属性控制输入框的边框半径，创建圆角或尖角。

填充​

fill 属性控制输入框的背景样式，提供边框或填充背景。

尺寸​

size 属性为输入框提供不同的尺寸选项。

分隔符​

separators 属性在一个或多个输入框之间添加视觉分隔线。分隔符可以通过三种方式定义：

  • 以逗号分隔的数字字符串（例如，"1,3"）
  • 数字数组（例如，[1, 3]）
  • 字符串 "all" 以在每个输入框之间显示分隔符

数字表示分隔符应出现在哪个索引之后。例如，"1,3" 在第一个和第三个输入框之后显示分隔符。这可以用于创建视觉上不同的输入框分组，但它仍然只有一个值。

状态​

组件支持输入框自动样式的各种状态：

  • 通过相应属性支持的 disabled 和 readonly 状态
  • 表单验证状态：通过 CSS 类在视觉上指示的 valid 和 invalid
  • 在 Angular 中：验证状态通过框架的值访问器和表单验证自动管理
  • 对于其他框架：开发人员必须手动添加 ion-valid、ion-invalid 和 ion-touched 类
  • ion-invalid 样式仅在触摸后（ion-touched）显示
  • ion-valid 样式仅在聚焦时（has-focus）显示

模式​

pattern 属性使用正则表达式启用自定义验证。它接受字符串正则表达式或unicode 正则表达式来验证允许的字符。pattern 必须匹配整个值，而不仅仅是子集。默认模式：

  • type="number"："[\p{N}]" 用于匹配任何脚本中的任何数字字符。
  • type="text"："[\p{L}\p{N}]" 用于任何脚本中的任何数字字符和任何语言的任何字母。

组件将阻止用户输入任何与指定模式不匹配的字符。开发人员可以通过提供自己的模式字符串来覆盖这些默认值，以匹配特定的输入要求。

提示

使用自定义 pattern 时，请记住 type 属性控制在移动设备上显示哪种键盘：

  • 对纯数字模式使用 type="number" 以显示数字键盘
  • 对包含字母的模式使用 type="text" 以显示字母数字键盘

主题​

颜色​

color 属性更改输入框的调色板。对于 outline 填充，此属性更改光标颜色、高亮颜色和边框颜色。对于 solid 填充，此属性更改光标颜色和高亮颜色。

备注

color 属性不会更改输入 OTP 的文本颜色。要更改文本颜色，请使用 --color CSS 属性。

CSS 自定义属性​

Input OTP 使用作用域封装，这意味着它会通过运行时为每个样式附加一个额外的类来自动限定其 CSS 的作用域。在 CSS 中覆盖作用域选择器需要更高的特异性选择器。针对 ion-input-otp 进行自定义不起作用；因此我们建议添加一个类并以此方式进行自定义。由于某些样式是根据 fill 应用的，您可能需要单独覆盖各个填充的属性。

辅助功能​

键盘交互​

Input OTP 的键盘导航遵循 ARIA 创作实践指南关于复合小部件的建议。它被视为复合小部件，因为它包含多个可聚焦元素（输入框），这些元素作为一个控件运行。

当组件未禁用时，这些键盘交互适用于所有 ion-input-otp 元素。

键描述
Tab首次 Tab 进入组件时，焦点移动到第一个空框。如果所有框都已填满，焦点移动到最后一个框。进入组件后，Tab 移动到页面上的下一个可聚焦元素。
Shift + Tab反向 Tab 进入组件时，焦点移动到第一个空框。如果所有框都已填满，焦点移动到最后一个框。进入组件后，Shift+Tab 将焦点移动到页面上的上一个可聚焦元素。
ArrowRight将焦点移动到下一个输入框，停在第一个空框。在 RTL 模式下，将焦点移回到任何包含值的上一个框。
ArrowLeft将焦点移回到任何包含值的上一个框。在 RTL 模式下，将焦点移动到下一个输入框，停在第一个空框。
与 pattern 属性匹配的任何字符填充当前框并自动将焦点移动到下一个空框。如果所有框都已填满，焦点保持在最后一个框。如果当前框有值，用输入的字符覆盖该值。在 RTL 模式下，输入从右到左填充框。
Backspace在空框中：将焦点移回一个框并清除其值。
在有值的框中：清除该值。
如果右侧框中有值：将所有值向左移动一个位置。在 RTL 模式下，如果左侧框中有值：将所有值向右移动一个位置。
Ctrl + V
Cmd + V		从第一个框开始粘贴内容，无论当前聚焦的是哪个框。粘贴前会清除所有现有值。例如，如果所有框中都有 "1234" 并粘贴 "56"，结果将是前两个框中为 "56"，其余框为空。如果粘贴的内容长于可用框的数量，多余字符将被忽略。

属性​

autocapitalize​

说明Indicates whether and how the text value should be automatically capitalized as it is entered/edited by the user. Available options: "off", "none", "on", "sentences", "words", "characters".
属性autocapitalize
类型string
默认值'off'

color​

说明The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
属性color
类型"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
默认值undefined

disabled​

说明If true, the user cannot interact with the input.
属性disabled
类型boolean
默认值false

fill​

说明The fill for the input boxes. If "solid" the input boxes will have a background. If "outline" the input boxes will be transparent with a border.
属性fill
类型"outline" ｜ "solid" ｜ undefined
默认值'outline'

inputmode​

说明A hint to the browser for which keyboard to display. Possible values: "none", "text", "tel", "url", "email", "numeric", "decimal", and "search".

For numbers (type="number"): "numeric" For text (type="text"): "text"
属性inputmode
类型"decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined
默认值undefined

length​

说明The number of input boxes to display.
属性length
类型number
默认值4

pattern​

说明A regex pattern string for allowed characters. Defaults based on type.

For numbers (type="number"): "[\p{N}]" For text (type="text"): "[\p{L}\p{N}]"
属性pattern
类型string ｜ undefined
默认值undefined

readonly​

说明If true, the user cannot modify the value.
属性readonly
类型boolean
默认值false

separators​

说明Where separators should be shown between input boxes. Can be a comma-separated string or an array of numbers.

For example: "3" will show a separator after the 3rd input box. [1,4] will show a separator after the 1st and 4th input boxes. "all" will show a separator between every input box.
属性separators
类型number[] ｜ string ｜ undefined
默认值undefined

shape​

说明The shape of the input boxes. If "round" they will have an increased border radius. If "rectangular" they will have no border radius. If "soft" they will have a soft border radius.
属性shape
类型"rectangular" ｜ "round" ｜ "soft"
默认值'round'

size​

说明The size of the input boxes.
属性size
类型"large" ｜ "medium" ｜ "small"
默认值'medium'

type​

说明The type of input allowed in the input boxes.
属性type
类型"number" ｜ "text"
默认值'number'

value​

说明The value of the input group.
属性value
类型null ｜ number ｜ string ｜ undefined
默认值''

事件​

Name说明冒泡
ionBlurEmitted when the input group loses focus.true
ionChangeThe ionChange event is fired when the user modifies the input's value. Unlike the ionInput event, the ionChange event is only fired when changes are committed, not as the user types.

The ionChange event fires when the <ion-input-otp> component loses focus after its value has changed.

This event will not emit when programmatically setting the value property.		true
ionCompleteEmitted when all input boxes have been filled with valid values.true
ionFocusEmitted when the input group has focus.true
ionInputThe ionInput event is fired each time the user modifies the input's value. Unlike the ionChange event, the ionInput event is fired for each alteration to the input's value. This typically happens for each keystroke as the user types.

For elements that accept text input (type=text, type=tel, etc.), the interface is InputEvent; for others, the interface is Event. If the input is cleared on edit, the type is null.		true

方法​

setFocus​

说明Sets focus to an input box.
签名setFocus(index?: number) => Promise<void>
参数index: - The index of the input box to focus (0-based). If provided and the input box has a value, the input box at that index will be focused. Otherwise, the first empty input box or the last input if all are filled will be focused.

CSS Shadow Parts​

该组件没有可用的 CSS 阴影部分。

CSS 自定义属性​

Name说明
--backgroundBackground color of the input boxes
--border-colorBorder color of the input boxes
--border-radiusBorder radius of the input boxes
--border-widthBorder width of the input boxes
--colorText color of the input
--heightHeight of input boxes
--highlight-color-focusedThe color of the highlight on the input when focused
--highlight-color-invalidThe color of the highlight on the input when invalid
--highlight-color-validThe color of the highlight on the input when valid
--margin-bottomBottom margin of the input group
--margin-endRight margin if direction is left-to-right, and left margin if direction is right-to-left of the input group
--margin-startLeft margin if direction is left-to-right, and right margin if direction is right-to-left of the input group
--margin-topTop margin of the input group
--min-widthMinimum width of input boxes
--padding-bottomBottom padding of the input group
--padding-endRight padding if direction is left-to-right, and left padding if direction is right-to-left of the input group
--padding-startLeft padding if direction is left-to-right, and right padding if direction is right-to-left of the input group
--padding-topTop padding of the input group
--separator-border-radiusBorder radius of the separator between boxes
--separator-colorColor of the separator between boxes
--separator-heightHeight of the separator between boxes
--separator-widthWidth of the separator between boxes
--widthWidth of input boxes

插槽​

该组件没有可用的插槽。

目录

编辑此页