ion-input
输入组件是 HTML 输入元素的一个封装器，具有自定义样式和附加功能。它接受大多数与 HTML 输入相同的属性，并与移动设备上的键盘集成。
🌐 The input component is a wrapper to the HTML input element with custom styling and additional functionality. It accepts most of the same properties as the HTML input and integrates with the keyboard on mobile devices.
基本用法
🌐 Basic Usage
类型
🌐 Types
该输入组件仅用于文本类型输入，例如 "text"、"password"、"email"、"number"、"search"、"tel" 和 "url"。它支持所有标准文本输入事件，包括 keyup、keydown、keypress 等。默认的 type 是 "text"。
🌐 The input component is meant for text type inputs only, such as "text", "password", "email", "number", "search", "tel", and "url". It supports all standard text input events including keyup, keydown, keypress, and more. The default type is "text".
标签
🌐 Labels
标签应用于描述输入。它们可以以视觉方式使用，当用户聚焦于输入时，屏幕阅读器也会朗读它们。这使用户能够轻松理解输入的意图。输入有几种方式来分配标签：
🌐 Labels should be used to describe the input. They can be used visually, and they will also be read out by screen readers when the user is focused on the input. This makes it easy for the user to understand the intent of the input. Input has several ways to assign a label:
label属性：用于明文标签label插槽：用于自定义 HTML 标签（实验性）aria-label：用于为屏幕阅读器提供标签，但不添加可见标签
标签放置
🌐 Label Placement
标签默认会占据其内容的宽度。开发者可以使用 labelPlacement 属性来控制标签相对于控件的放置方式。
🌐 Labels will take up the width of their content by default. Developers can use the labelPlacement property to control how the label is placed relative to the control.
标签槽（实验性）
🌐 Label Slot (experimental)
虽然明文标签应通过 label 属性传入，但如果需要自定义 HTML，则可以通过 label 插槽传入。
🌐 While plaintext labels should be passed in via the label property, if custom HTML is needed, it can be passed through the label slot instead.
请注意，此功能被视为实验性功能，因为它依赖于Web 组件插槽的模拟版本。因此，模拟行为可能与原生插槽行为不完全相同。
🌐 Note that this feature is considered experimental because it relies on a simulated version of Web Component slots. As a result, the simulated behavior may not exactly match the native slot behavior.
无可见标签
🌐 No Visible Label
即使不需要可见标签，开发者仍应提供一个 aria-label，以便输入对屏幕阅读器可访问。
🌐 If no visible label is needed, developers should still supply an aria-label so the input is accessible to screen readers.
清除选项
🌐 Clear Options
输入框提供了两种根据交互方式清除输入的选项。第一种方式是添加 clearInput 属性，当输入框有 value 时会显示清除按钮。第二种方式是 clearOnEdit 属性，它会在输入框失去焦点后再次输入时清除内容。设置了 type 为 "password" 的输入框默认会启用 clearOnEdit。
🌐 Inputs offer two options for clearing the input based on how you interact with it. The first way is by adding the clearInput property which will show a clear button when the input has a value. The second way is the clearOnEdit property which will clear the input after it has been blurred and then typed in again. Inputs with a type set to "password" will have clearOnEdit enabled by default.
填充输入
🌐 Filled Inputs
Material Design 为输入提供了填充样式。输入上的 fill 属性可以设置为 "solid" 或 "outline"。
🌐 Material Design offers filled styles for an input. The fill property on the input can be set to either "solid" or "outline".
通过将输入的 mode 设置为 md，已填充的输入可以在 iOS 上使用。
🌐 Filled inputs can be used on iOS by setting the input's mode to md.
使用 fill 的输入不应在 ion-item 中使用，因为组件之间的样式存在冲突。
辅助程序和错误文本
🌐 Helper & Error Text
帮助文本和错误文本可以在使用 helperText 和 errorText 属性的输入框中使用。除非将 ion-invalid 和 ion-touched 类添加到 ion-input 中，否则错误文本将不会显示。这确保了在用户有机会输入数据之前不会显示错误。
🌐 Helper and error text can be used inside of an input with the helperText and errorText property. The error text will not be displayed unless the ion-invalid and ion-touched classes are added to the ion-input. This ensures errors are not shown before the user has a chance to enter data.
在 Angular 中，这通过表单验证自动补齐。在 JavaScript、React 和 Vue 中，需要根据你自己的验证手动添加类。
🌐 In Angular, this is done automatically through form validation. In JavaScript, React and Vue, the class needs to be manually added based on your own validation.
输入计数器
🌐 Input Counter
输入计数器是在输入框下方显示的文本，用于通知用户已输入的字符数占输入框可接受的总字符数。当添加计数器时，默认行为是将显示的值格式化为 inputLength / maxLength。此行为可以通过向 counterFormatter 属性传入一个格式化函数来定制。
🌐 The input counter is text that displays under an input to notify the user of how many characters have been entered out of the total that the input will accept. When adding counter, the default behavior is to format the value that gets displayed as inputLength / maxLength. This behavior can be customized by passing in a formatter function to the counterFormatter property.
ion-item 上的 counter 和 counterFormatter 属性在 Ionic 7 中已被弃用，应直接在 ion-input 上使用。
🌐 The counter and counterFormatter properties on ion-item were deprecated in Ionic 7 and should be used directly on ion-input instead.
带计数器的输入在输入框和计数器之间添加边框，因此不应将它们放置在添加额外底部边框的 ion-item 内。可以添加 ion-padding-start 类，以使计数器输入与项内部的输入对齐。
🌐 Inputs with a counter add a border between the input and the counter, therefore they should not be placed inside of an ion-item which adds an additional border under the item. The ion-padding-start class can be added to align the counter inputs with inputs inside of items.
过滤用户输入
🌐 Filtering User Input
开发者可以使用 ionInput 事件根据用户输入（例如 keypress）来更新输入值。这对于过滤无效或不需要的字符非常有用。
🌐 Developers can use the ionInput event to update the input value in response to user input such as a keypress. This is useful for filtering out invalid or unwanted characters.
在将值存储在状态变量中时，我们建议同时更新状态变量和 ion-input 组件的值。这可以确保状态变量和 ion-input 组件的值保持同步。
🌐 When storing the value in a state variable, we recommend updating both the state variable and the ion-input component value. This ensures that the state variable and the ion-input component value remain in sync.
输入屏蔽
🌐 Input Masking
输入掩码是限制输入以支持有效输入值的表达式。Ionic 建议使用 Maskito 进行输入掩码。Maskito 是一个轻量级、无依赖的输入字段掩码库。它支持各种掩码，包括电话号码、信用卡、日期等。
🌐 Input masks are expressions that constrain input to support valid input values. Ionic recommends using Maskito for input masking. Maskito is a lightweight, dependency-free library for masking input fields. It supports a wide range of masks, including phone numbers, credit cards, dates, and more.
要开始使用 Maskito，请安装该库：
🌐 To get started with Maskito, install the library:
npm install @maskito/core @maskito/{angular,react,vue}
请通过 Maskito Github 仓库 提交 Maskito 的错误报告。如需技术支持，请使用 Ionic 论坛 或 Ionic Discord。
🌐 Please submit bug reports with Maskito to the Maskito Github repository. For technical support, please use the Ionic Forum or Ionic Discord.
开始和结束槽（实验）
🌐 Start and End Slots (experimental)
start 和 end 插槽可用于在输入框的任一侧放置图标、按钮或前缀/后缀文本。
🌐 The start and end slots can be used to place icons, buttons, or prefix/suffix text on either side of the input.
请注意，此功能被视为实验性功能，因为它依赖于Web 组件插槽的模拟版本。因此，模拟行为可能与原生插槽行为不完全相同。
🌐 Note that this feature is considered experimental because it relies on a simulated version of Web Component slots. As a result, the simulated behavior may not exactly match the native slot behavior.
主题化
🌐 Theming
颜色
🌐 Colors
设置 color 属性会更改每个输入的颜色调色板。在 ios 模式下，该属性会更改插入点颜色。在 md 模式下，该属性会更改插入点颜色以及高亮/下划线颜色。
🌐 Setting the color property changes the color palette for each input. On ios mode, this property changes the caret color. On md mode, this property changes the caret color and the highlight/underline color.
color 属性 不会 改变输入的文本颜色。要做到这一点，请使用 --color CSS 属性。
CSS 自定义属性
🌐 CSS Custom Properties
输入使用了作用域封装，这意味着它会在运行时通过在每个样式后附加额外的类来自动进行 CSS 作用域。要覆盖作用域选择器的 CSS，需要使用 更高特异性 的选择器。直接针对 ion-input 进行自定义将不起作用；因此我们建议添加一个类并通过这种方式进行自定义。
🌐 Input 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 for customization will not work; therefore we recommend adding a class and customizing it that way.
接口
🌐 Interfaces
InputChangeEventDetail
interface InputChangeEventDetail {
value: string | undefined | null;
}
InputCustomEvent
虽然不是必需的，但可以使用此接口替代 CustomEvent 接口，以便对从此组件发出的 Ionic 事件进行更强类型的处理。
🌐 While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.
interface InputCustomEvent extends CustomEvent {
detail: InputChangeEventDetail;
target: HTMLIonInputElement;
}
属性
🌐 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' |
autocomplete
| Description | Indicates whether the value of the control can be automatically completed by the browser. |
| Attribute | autocomplete |
| Type | "additional-name" ｜ "address-level1" ｜ "address-level2" ｜ "address-level3" ｜ "address-level4" ｜ "address-line1" ｜ "address-line2" ｜ "address-line3" ｜ "bday" ｜ "bday-day" ｜ "bday-month" ｜ "bday-year" ｜ "cc-additional-name" ｜ "cc-csc" ｜ "cc-exp" ｜ "cc-exp-month" ｜ "cc-exp-year" ｜ "cc-family-name" ｜ "cc-given-name" ｜ "cc-name" ｜ "cc-number" ｜ "cc-type" ｜ "country" ｜ "country-name" ｜ "current-password" ｜ "email" ｜ "family-name" ｜ "given-name" ｜ "honorific-prefix" ｜ "honorific-suffix" ｜ "impp" ｜ "language" ｜ "name" ｜ "new-password" ｜ "nickname" ｜ "off" ｜ "on" ｜ "one-time-code" ｜ "organization" ｜ "organization-title" ｜ "photo" ｜ "postal-code" ｜ "sex" ｜ "street-address" ｜ "tel" ｜ "tel-area-code" ｜ "tel-country-code" ｜ "tel-extension" ｜ "tel-local" ｜ "tel-national" ｜ "transaction-amount" ｜ "transaction-currency" ｜ "url" ｜ "username" |
| Default | 'off' |
autocorrect
| Description | Whether auto correction should be enabled when the user is entering/editing the text value. |
| Attribute | autocorrect |
| Type | "off" ｜ "on" |
| Default | 'off' |
autofocus
| Description | Sets the autofocus attribute on the native input element.This may not be sufficient for the element to be focused on page load. See managing focus for more information. |
| Attribute | autofocus |
| Type | boolean |
| Default | false |
clearInput
| Description | If true, a clear icon will appear in the input when there is a value. Clicking it clears the input. |
| Attribute | clear-input |
| Type | boolean |
| Default | false |
clearInputIcon
| Description | The icon to use for the clear button. Only applies when clearInput is set to true. |
| Attribute | clear-input-icon |
| Type | string ｜ undefined |
| Default | undefined |
clearOnEdit
| Description | If true, the value will be cleared after focus upon edit. Defaults to true when type is "password", false for all other types. |
| Attribute | clear-on-edit |
| Type | boolean ｜ undefined |
| Default | undefined |
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 |
counter
| Description | If true, a character counter will display the ratio of characters used and the total character limit. Developers must also set the maxlength property for the counter to be calculated correctly. |
| Attribute | counter |
| Type | boolean |
| Default | false |
counterFormatter
| Description | A callback used to format the counter text. By default the counter text is set to "itemLength / maxLength". See https://ionicframework.com/docs/troubleshooting/runtime#accessing-this if you need to access this from within the callback. |
| Attribute | undefined |
| Type | ((inputLength: number, maxLength: number) => string) ｜ undefined |
| Default | undefined |
debounce
| Description | Set the amount of time, in milliseconds, to wait to trigger the ionInput event after each keystroke. |
| Attribute | debounce |
| Type | number ｜ undefined |
| Default | undefined |
disabled
| Description | If true, the user cannot interact with the input. |
| Attribute | disabled |
| Type | boolean |
| Default | false |
enterkeyhint
| Description | A hint to the browser for which enter key to display. Possible values: "enter", "done", "go", "next", "previous", "search", and "send". |
| Attribute | enterkeyhint |
| Type | "done" ｜ "enter" ｜ "go" ｜ "next" ｜ "previous" ｜ "search" ｜ "send" ｜ undefined |
| Default | undefined |
errorText
| Description | Text that is placed under the input and displayed when an error is detected. |
| Attribute | error-text |
| Type | string ｜ undefined |
| Default | undefined |
fill
| Description | The fill for the item. If "solid" the item will have a background. If "outline" the item will be transparent with a border. Only available in md mode. |
| Attribute | fill |
| Type | "outline" ｜ "solid" ｜ undefined |
| Default | undefined |
helperText
| Description | Text that is placed under the input and displayed when no error is detected. |
| Attribute | helper-text |
| Type | string ｜ undefined |
| Default | undefined |
inputmode
| Description | A hint to the browser for which keyboard to display. Possible values: "none", "text", "tel", "url", "email", "numeric", "decimal", and "search". |
| Attribute | inputmode |
| Type | "decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined |
| Default | undefined |
label
| Description | The visible label associated with the input. Use this if you need to render a plaintext label. The label property will take priority over the label slot if both are used. |
| Attribute | label |
| Type | string ｜ undefined |
| Default | undefined |
labelPlacement
| Description | Where to place the label relative to the input. "start": The label will appear to the left of the input in LTR and to the right in RTL. "end": The label will appear to the right of the input in LTR and to the left in RTL. "floating": The label will appear smaller and above the input when the input is focused or it has a value. Otherwise it will appear on top of the input. "stacked": The label will appear smaller and above the input regardless even when the input is blurred or has no value. "fixed": The label has the same behavior as "start" except it also has a fixed width. Long text will be truncated with ellipses ("..."). |
| Attribute | label-placement |
| Type | "end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start" |
| Default | 'start' |
max
| Description | The maximum value, which must not be less than its minimum (min attribute) value. |
| Attribute | max |
| Type | number ｜ string ｜ undefined |
| Default | undefined |
maxlength
| Description | If the value of the type attribute is text, email, search, password, tel, or url, this attribute specifies the maximum number of characters that the user can enter. |
| Attribute | maxlength |
| Type | number ｜ undefined |
| Default | undefined |
min
| Description | The minimum value, which must not be greater than its maximum (max attribute) value. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render. |
| Attribute | min |
| Type | number ｜ string ｜ undefined |
| Default | undefined |
minlength
| Description | If the value of the type attribute is text, email, search, password, tel, or url, this attribute specifies the minimum number of characters that the user can enter. |
| Attribute | minlength |
| Type | number ｜ undefined |
| Default | undefined |
mode
| Description | The mode determines which platform styles to use. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render. |
| Attribute | mode |
| Type | "ios" ｜ "md" |
| Default | undefined |
multiple
| Description | If true, the user can enter more than one value. This attribute applies when the type attribute is set to "email", otherwise it is ignored. |
| Attribute | multiple |
| Type | boolean ｜ undefined |
| Default | undefined |
name
| Description | The name of the control, which is submitted with the form data. |
| Attribute | name |
| Type | string |
| Default | this.inputId |
pattern
| Description | A regular expression that the value is checked against. The pattern must match the entire value, not just some subset. Use the title attribute to describe the pattern to help the user. This attribute applies when the value of the type attribute is "text", "search", "tel", "url", "email", "date", or "password", otherwise it is ignored. When the type attribute is "date", pattern will only be used in browsers that do not support the "date" input type natively. See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date for more information. |
| Attribute | pattern |
| Type | string ｜ undefined |
| Default | undefined |
placeholder
| Description | Instructional text that shows before the input has a value. This property applies only when the type property is set to "email", "number", "password", "search", "tel", "text", or "url", otherwise it is ignored. |
| Attribute | placeholder |
| Type | string ｜ undefined |
| Default | undefined |
readonly
| Description | If true, the user cannot modify the value. |
| Attribute | readonly |
| Type | boolean |
| Default | false |
required
| Description | If true, the user must fill in a value before submitting a form. |
| Attribute | required |
| Type | boolean |
| Default | false |
shape
| Description | The shape of the input. If "round" it will have an increased border radius. |
| Attribute | shape |
| Type | "round" ｜ undefined |
| Default | undefined |
spellcheck
| Description | If true, the element will have its spelling and grammar checked. |
| Attribute | spellcheck |
| Type | boolean |
| Default | false |
step
| Description | Works with the min and max attributes to limit the increments at which a value can be set. Possible values are: "any" or a positive floating point number. |
| Attribute | step |
| Type | string ｜ undefined |
| Default | undefined |
type
| Description | The type of control to display. The default type is text. |
| Attribute | type |
| Type | "date" ｜ "datetime-local" ｜ "email" ｜ "month" ｜ "number" ｜ "password" ｜ "search" ｜ "tel" ｜ "text" ｜ "time" ｜ "url" ｜ "week" |
| Default | 'text' |
value
| Description | The value of the input. |
| Attribute | value |
| Type | null ｜ number ｜ string ｜ undefined |
| Default | '' |
事件
🌐 Events
| Name | Description | Bubbles |
|---|---|---|
ionBlur | Emitted when the input 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.Depending on the way the users interacts with the element, the ionChange event fires at a different moment: - When the user commits the change explicitly (e.g. by selecting a date from a date picker for <ion-input type="date">, pressing the "Enter" key, etc.). - When the element loses focus after its value has changed: for elements where the user's interaction is typing.This event will not emit when programmatically setting the value property. | true |
ionFocus | Emitted when the input 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
getInputElement
| Description | Returns the native <input> element used under the hood. |
| Signature | getInputElement() => Promise<HTMLInputElement> |
setFocus
| Description | Sets focus on the native input in ion-input. Use this method instead of the global input.focus().Developers who wish to focus an input when a page enters should call setFocus() in the ionViewDidEnter() lifecycle method.Developers who wish to focus an input when an overlay is presented should call setFocus after didPresent has resolved.See managing focus for more information. |
| Signature | setFocus() => Promise<void> |
CSS 阴影部分
🌐 CSS Shadow Parts
No CSS shadow parts available for this component.
CSS 自定义属性
🌐 CSS Custom Properties
- iOS
- MD
| Name | Description |
|---|---|
--background | Background of the input |
--border-color | Color of the border below the input when using helper text, error text, or counter |
--border-radius | Radius of the input. A large radius may display unevenly when using fill="outline"; if needed, use shape="round" instead or increase --padding-start. |
--border-style | Style of the border below the input when using helper text, error text, or counter |
--border-width | Width of the border below the input when using helper text, error text, or counter |
--color | Color of the input text |
--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 |
--highlight-height | The height of the highlight on the input. Only applies to md mode. |
--padding-bottom | Bottom padding of the input |
--padding-end | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the input |
--padding-start | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the input |
--padding-top | Top padding of the input |
--placeholder-color | Color of the input placeholder text |
--placeholder-font-style | Font style of the input placeholder text |
--placeholder-font-weight | Font weight of the input placeholder text |
--placeholder-opacity | Opacity of the input placeholder text |
| Name | Description |
|---|---|
--background | Background of the input |
--border-color | Color of the border below the input when using helper text, error text, or counter |
--border-radius | Radius of the input. A large radius may display unevenly when using fill="outline"; if needed, use shape="round" instead or increase --padding-start. |
--border-style | Style of the border below the input when using helper text, error text, or counter |
--border-width | Width of the border below the input when using helper text, error text, or counter |
--color | Color of the input text |
--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 |
--highlight-height | The height of the highlight on the input. Only applies to md mode. |
--padding-bottom | Bottom padding of the input |
--padding-end | Right padding if direction is left-to-right, and left padding if direction is right-to-left of the input |
--padding-start | Left padding if direction is left-to-right, and right padding if direction is right-to-left of the input |
--padding-top | Top padding of the input |
--placeholder-color | Color of the input placeholder text |
--placeholder-font-style | Font style of the input placeholder text |
--placeholder-font-weight | Font weight of the input placeholder text |
--placeholder-opacity | Opacity of the input placeholder text |
插槽
🌐 Slots
| Name | Description |
|---|---|
end | Content to display at the trailing edge of the input. (EXPERIMENTAL) |
label | The label text to associate with the input. Use the labelPlacement property to control where the label is placed relative to the input. Use this if you need to render a label with custom HTML. (EXPERIMENTAL) |
start | Content to display at the leading edge of the input. (EXPERIMENTAL) |