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"：- 将
inputmode="numeric"设置为在移动设备上显示数字键盘 - 将
pattern="[\p{N}]"设置为仅允许数字输入
- 将
- 当
type="text"：- 将
inputmode="text"设置为显示标准键盘 - 将
pattern="[\p{L}\p{N}]"设置为允许字母数字输入
- 将
有关模式验证和自定义的更多详细信息，请参阅模式部分。
🌐 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"） - 数字数组（例如，
[1, 3]） - 字符串
"all"用于显示每个输入框之间的分隔符
这些数字表示分隔符应出现的索引。例如，"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状态通过各自的属性- 表单验证状态：通过 CSS 类以视觉方式指示
valid和invalid - 在 Angular 中：验证状态通过框架的值访问器和表单验证自动管理
- 对于其他框架：开发者必须手动添加
ion-valid、ion-invalid和ion-touched类 ion-invalid样式仅在触碰时显示 (ion-touched)ion-valid样式仅在聚焦时显示 (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="text"："[\p{L}\p{N}]"用于任何脚本中的任何数字字符以及任何语言中的任何字母。
该组件将阻止用户输入与指定模式不符的任何字符。开发者可以通过提供自己的模式字符串来覆盖这些默认设置，以匹配特定的输入要求。
🌐 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 属性控制移动设备上出现的键盘类型：
- 对于仅包含数字的模式，请使用
type="number"来显示数字键盘 - 对于包含字母的模式，使用
type="text"来显示字母数字键盘:::
主题化
🌐 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 属性。
CSS 自定义属性
🌐 CSS Custom Properties
Input OTP 使用了 scoped 封装，这意味着它会通过在运行时为每个样式附加一个额外的类来自动对其 CSS 进行作用域限制。要在 CSS 中覆盖 scoped 选择器，需要使用具有更高特异性的选择器。直接针对 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 Authoring Practices Guide 对复合控件的推荐。它被视为复合控件，因为它包含多个可聚焦元素（输入框），这些元素作为单一控件运行。
🌐 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 键会移动到页面上的下一个可聚焦元素。 |
| Shift + Tab | 当向后切换到组件时，焦点会移动到第一个空框。如果所有框都已填写，焦点会移动到 最后一个框。一旦进入组件，按 Shift+Tab 切换焦点会移动到页面上上一个可聚焦的元素。|
| ArrowRight | 将焦点移动到下一个输入框，在第一个空框处停止。在 RTL 模式下，将焦点移回任何包含数值的上一个框。 |
| ArrowLeft | 将焦点移回任意包含值的前一个框。在从右到左模式下，将焦点移到下一个输入框，并在第一个空框处停止。 |
| 任何符合 pattern 属性的字符 | 填充当前输入框并自动将焦点移到下一个空输入框。如果所有输入框都已填充，焦点保持在最后一个输入框。如果当前输入框已有值，将被输入的字符覆盖。在从右到左 (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.