ion-input-otp
输入一次性密码 (OTP) 组件是一个专门用于输入一次性密码 (OTP) 的输入组件。它提供了一个用户友好的验证码输入界面，支持多个输入框和自动焦点管理。
¥The Input OTP component is a specialized input component designed for entering one-time passwords (OTP). It provides a user-friendly interface for entering verification codes with support for multiple input boxes and automatic focus management.
基本用法
¥Basic Usage
该组件默认提供 4 个输入框，这是许多验证码的常用长度。可以使用 length 属性自定义输入框的数量。
¥The component provides 4 input boxes by default, which is a common length for many verification codes. The number of input boxes can be customized using the length property.
类型
¥Type
type 属性决定输入格式，支持数字或字母数字验证码。它接受两个值：number 和 text。它默认使用 type="number" 输入数字验证码。指定 type="text" 后，它接受字母数字输入。这种灵活性允许处理不同的 OTP 格式，无论是纯数字代码（如短信验证码）还是字母数字代码（如备份代码或恢复密钥）。
¥The type property determines the input format, supporting either numeric or alphanumeric verification codes. It accepts two values: number and text. It uses type="number" by default for entering numeric verification codes. When type="text" is specified, it accepts alphanumeric input. This flexibility allows handling different OTP formats, whether numeric-only codes (like SMS verification codes) or alphanumeric codes (like backup codes or recovery keys).
type 属性会自动设置 inputmode 和 pattern 属性：
¥The type property automatically sets both the inputmode and pattern attributes:
-
当
type="number"时：¥When
type="number":-
设置
inputmode="numeric"以在移动设备上显示数字键盘¥Sets
inputmode="numeric"to show a numeric keyboard on mobile devices -
设置
pattern="[\p{N}]"以仅允许数字输入¥Sets
pattern="[\p{N}]"to allow only numeric input
-
-
当
type="text"时：¥When
type="text":-
设置
inputmode="text"以显示标准键盘¥Sets
inputmode="text"to show a standard keyboard -
设置
pattern="[\p{L}\p{N}]"以允许字母数字输入¥Sets
pattern="[\p{L}\p{N}]"to allow alphanumeric input
-
有关模式验证和自定义的更多详细信息，请参阅 模式 部分。
¥See the Pattern section for more details on pattern validation and customization.
形状
¥Shape
shape 属性控制输入框的边框半径，提供圆角或尖角。
¥The shape property controls the border radius of the input boxes, creating rounded or sharp corners.
填充
¥Fill
fill 属性控制输入框的背景样式，提供带边框或填充的背景。
¥The fill property controls the background style of the input boxes, offering bordered or filled backgrounds.
尺寸
¥Size
size 属性为输入框提供了不同的大小选项。
¥The size property provides different size options for the input boxes.
分隔符
¥Separators
separators 属性在一个或多个输入框之间添加视觉分隔符。分隔符可以通过三种方式定义：
¥The separators property adds visual dividers between one or more of the input boxes. Separators can be defined in three ways:
-
以逗号分隔的数字字符串（例如，
"1,3"）¥Comma-separated string of numbers (e.g.,
"1,3") -
数字数组（例如，
[1, 3]）¥Array of numbers (e.g.,
[1, 3]) -
设置字符串
"all"以在每个输入框之间显示分隔符¥String
"all"to show separators between every input box
数字代表索引，分隔符应出现在索引之后。例如，"1,3" 会在第一个和第三个输入框后显示分隔符。这可用于创建视觉上不同的输入框分组，但它仍然只有一个值。
¥The numbers represent the index after which a separator should appear. For example, "1,3" displays a separator after the first and third input box. This can be used to create visually distinct groupings of input boxes, but it will still have one value.
状态
¥States
该组件支持多种状态以自动设置输入框的样式：
¥The component supports various states for automatic styling of input boxes:
-
disabled和readonly通过各自的属性状态¥
disabledandreadonlystates via respective properties -
表单验证状态：
valid和invalid通过 CSS 类进行视觉指示¥Form validation states:
validandinvalidvisually indicated through CSS classes -
在 Angular 中：验证状态由框架的值访问器和表单验证自动管理
¥In Angular: validation states are automatically managed through the framework's value accessors and form validation
-
其他框架：开发者必须手动添加
ion-valid、ion-invalid和ion-touched类。¥For other frameworks: developers must manually add
ion-valid,ion-invalid, andion-touchedclasses -
ion-invalid样式仅在被触摸时显示 (ion-touched)¥
ion-invalidstyles only display when touched (ion-touched) -
ion-valid样式仅在获得焦点时显示 (has-focus)¥
ion-validstyles only display when focused (has-focus)
模式
¥Pattern
pattern 属性支持使用正则表达式进行自定义验证。它接受 字符串正则表达式 或 Unicode 正则表达式 来验证允许的字符。pattern 必须匹配整个值，而不仅仅是子集。默认模式：
¥The pattern property enables custom validation using regular expressions. It accepts a string regular expression or unicode regular expression to validate allowed characters. The pattern must match the entire value, not just a subset. Default patterns:
-
type="number"："[\p{N}]"适用于匹配任何脚本中的任何类型的数字字符。¥
type="number":"[\p{N}]"for matching any kind of numeric character in any script. -
type="text"："[\p{L}\p{N}]"适用于任何脚本中的任何类型的数字字符以及任何语言中的任何类型的字母。¥
type="text":"[\p{L}\p{N}]"for any kind of numeric character in any script and any kind of letter from any language.
该组件将阻止用户输入任何与指定模式不匹配的字符。开发者可以通过提供自己的模式字符串来覆盖这些默认值，以满足特定的输入要求。
¥The component will prevent users from entering any characters that don't match the specified pattern. Developers can override these defaults by providing their own pattern string to match specific input requirements.
使用自定义 pattern 时，请记住 type 属性控制在移动设备上显示的键盘：
¥When using a custom pattern, remember that the type property controls which keyboard appears on mobile devices:
-
对于纯数字模式，使用
type="number"来显示数字键盘¥Use
type="number"for numeric-only patterns to show the numeric keyboard -
对于包含字母的模式，使用
type="text"来显示字母数字键盘¥Use
type="text"for patterns that include letters to show the alphanumeric keyboard
主题化
¥Theming
颜色
¥Colors
color 属性会更改输入框的调色板。对于 outline 填充，此属性会更改插入符号的颜色、高亮颜色和边框颜色。对于 solid 填充，此属性会更改插入符号的颜色和高亮颜色。
¥The color property changes the color palette for input boxes. For outline fills, this property changes the caret color, highlight color and border color. For solid fills, this property changes the caret color and highlight color.
color 属性不会改变输入 OTP 的文本颜色。为此，请使用 --color CSS 属性。
¥The color property does not change the text color of the input OTP. For that, use the --color CSS property.
CSS 自定义属性
¥CSS Custom Properties
Input OTP 使用作用域封装，这意味着它将通过在运行时为每个样式附加一个额外的类来自动确定其 CSS 的作用域。覆盖 CSS 中的作用域选择器需要 更高的特异性 选择器。以 ion-input-otp 为目标进行定制是行不通的；因此，我们建议添加一个类并以这种方式对其进行自定义。由于某些样式是基于 fill 应用的，你可能需要单独覆盖填充的属性。
¥Input OTP uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a higher specificity selector. Targeting the ion-input-otp for customization will not work; therefore we recommend adding a class and customizing it that way. Due to certain styles being applied based on the fill, you may need to override properties on the fills separately.
无障碍
¥Accessibility
键盘交互
¥Keyboard Interactions
输入 OTP 的键盘导航遵循 ARIA 创作实践指南 对复合小部件的建议。它被视为复合控件，因为它包含多个可聚焦元素（输入框），这些元素的功能与单个控件相同。
¥The keyboard navigation for Input OTP follows the ARIA Authoring Practices Guide's recommendations for composite widgets. It is treated as a composite widget because it contains multiple focusable elements (input boxes) that function as a single control.
当组件未禁用时，这些键盘交互适用于所有 ion-input-otp 元素。
¥These keyboard interactions apply to all ion-input-otp elements when the component is not disabled.
| 密钥 | 描述 |
|---|---|
| Tab | 首次使用 Tab 键进入组件时，焦点将移动到第一个空框。如果所有框都已填充，焦点将移至最后一个框。进入组件后，Tab 键将移动到页面上的下一个可聚焦元素。 |
| Shift + Tab | 在组件中向后按 Tab 键时，焦点将移动到第一个空框。如果所有框都已填充，焦点将移至最后一个框。进入组件后，Shift 和 Tab 键将焦点移动到页面上的上一个可聚焦元素。 |
| ArrowRight | 将焦点移动到下一个输入框，并在第一个空输入框处停止。在 RTL 模式下，焦点将移回任何包含值的上一个框。 |
| ArrowLeft | 将焦点移回任何包含值的先前输入框。在 RTL 模式下，焦点将移至下一个输入框，并在第一个空框处停止。 |
任何与 pattern 属性匹配的字符 | 填充当前框并自动将焦点移动到下一个空框。如果所有框都已填充，焦点仍保留在最后一个框上。如果当前框中有值，则用输入的字符覆盖该值。在 RTL 模式下，输入从右到左填充框。 |
| Backspace | 在空框中：将焦点向后移动一个框并清除其值。 在带有值的框中：清除该值。 右侧框中带有值：将它们全部向左移动一个位置。在 RTL 模式下，左侧框中有值：将它们全部向右移动一位。 |
| Ctrl + V Cmd + V | 从第一个输入框开始粘贴内容，无论当前聚焦的是哪个输入框。粘贴前清除所有现有值。例如，如果你在所有框中都输入了 "1234" 并粘贴了 "56"，则结果将是前两个框中显示 "56"，其余框为空。如果粘贴的内容超出可用框的长度，则多余的字符将被忽略。 |
属性
¥Properties
autocapitalize
| Description | 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". |
| Attribute | autocapitalize |
| Type | string |
| Default | 'off' |
color
| Description | 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. |
| Attribute | color |
| Type | "danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined |
| Default | undefined |
disabled
| Description | If true, the user cannot interact with the input. |
| Attribute | disabled |
| Type | boolean |
| Default | false |
fill
| Description | 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. |
| Attribute | fill |
| Type | "outline" ｜ "solid" ｜ undefined |
| Default | 'outline' |
inputmode
| Description | 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" |
| Attribute | inputmode |
| Type | "decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined |
| Default | undefined |
length
| Description | The number of input boxes to display. |
| Attribute | length |
| Type | number |
| Default | 4 |
pattern
| Description | 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}]" |
| Attribute | pattern |
| Type | string ｜ undefined |
| Default | undefined |
readonly
| Description | If true, the user cannot modify the value. |
| Attribute | readonly |
| Type | boolean |
| Default | false |
separators
| Description | 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. |
| Attribute | separators |
| Type | number[] ｜ string ｜ undefined |
| Default | undefined |
shape
| Description | 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. |
| Attribute | shape |
| Type | "rectangular" ｜ "round" ｜ "soft" |
| Default | 'round' |
size
| Description | The size of the input boxes. |
| Attribute | size |
| Type | "large" ｜ "medium" ｜ "small" |
| Default | 'medium' |
type
| Description | The type of input allowed in the input boxes. |
| Attribute | type |
| Type | "number" ｜ "text" |
| Default | 'number' |
value
| Description | The value of the input group. |
| Attribute | value |
| Type | null ｜ number ｜ string ｜ undefined |
| Default | '' |
事件
¥Events
| Name | Description | Bubbles |
|---|---|---|
ionBlur | Emitted when the input group loses focus. | true |
ionChange | The 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 |
ionComplete | Emitted when all input boxes have been filled with valid values. | true |
ionFocus | Emitted when the input group has focus. | true |
ionInput | The 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 |
方法
¥Methods
setFocus
| Description | Sets focus to an input box. |
| Signature | setFocus(index?: number) => Promise<void> |
| Parameters | 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 阴影部分
¥CSS Shadow Parts
No CSS shadow parts available for this component.
CSS 自定义属性
¥CSS Custom Properties
- iOS
- MD
| Name | Description |
|---|---|
--background | Background color of the input boxes |
--border-color | Border color of the input boxes |
--border-radius | Border radius of the input boxes |
--border-width | Border width of the input boxes |
--color | Text color of the input |
--height | Height of input boxes |
--highlight-color-focused | The color of the highlight on the input when focused |
--highlight-color-invalid | The color of the highlight on the input when invalid |
--highlight-color-valid | The color of the highlight on the input when valid |
--margin-bottom | Bottom margin of the input group |
--margin-end | Right margin if direction is left-to-right, and left margin if direction is right-to-left of the input group |
--margin-start | Left margin if direction is left-to-right, and right margin if direction is right-to-left of the input group |
--margin-top | Top margin of the input group |
--min-width | Minimum width of input boxes |
--padding-bottom | Bottom padding of the input group |
--padding-end | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the input group |
--padding-start | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the input group |
--padding-top | Top padding of the input group |
--separator-border-radius | Border radius of the separator between boxes |
--separator-color | Color of the separator between boxes |
--separator-height | Height of the separator between boxes |
--separator-width | Width of the separator between boxes |
--width | Width of input boxes |
| Name | Description |
|---|---|
--background | Background color of the input boxes |
--border-color | Border color of the input boxes |
--border-radius | Border radius of the input boxes |
--border-width | Border width of the input boxes |
--color | Text color of the input |
--height | Height of input boxes |
--highlight-color-focused | The color of the highlight on the input when focused |
--highlight-color-invalid | The color of the highlight on the input when invalid |
--highlight-color-valid | The color of the highlight on the input when valid |
--margin-bottom | Bottom margin of the input group |
--margin-end | Right margin if direction is left-to-right, and left margin if direction is right-to-left of the input group |
--margin-start | Left margin if direction is left-to-right, and right margin if direction is right-to-left of the input group |
--margin-top | Top margin of the input group |
--min-width | Minimum width of input boxes |
--padding-bottom | Bottom padding of the input group |
--padding-end | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the input group |
--padding-start | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the input group |
--padding-top | Top padding of the input group |
--separator-border-radius | Border radius of the separator between boxes |
--separator-color | Color of the separator between boxes |
--separator-height | Height of the separator between boxes |
--separator-width | Width of the separator between boxes |
--width | Width of input boxes |
插槽
¥Slots
No slots available for this component.