版本：v8

输入组件

输入组件是对 HTML input 元素的封装，提供了自定义样式和额外功能。它接受与 HTML input 相同的大部分属性，并能与移动设备键盘集成。

基本用法

类型

输入组件仅用于文本类型的输入，例如 "text"、"password"、"email"、"number"、"search"、"tel" 和 "url"。它支持所有标准文本输入事件，包括 keyup、keydown、keypress 等。默认的 type 是 "text"。

清除选项

输入组件提供了两种清除输入的方式，具体取决于你与它的交互方式。第一种是添加 clearInput 属性，当输入框有 value 时会显示清除按钮。第二种是 clearOnEdit 属性，它会在输入框失去焦点后再次输入时清除内容。type 设置为 "password" 的输入框默认启用 clearOnEdit。

填充式输入

Material Design 为输入框提供了填充样式。输入框的 fill 属性可以设置为 "solid" 或 "outline"。

通过在输入框上设置 mode 为 md，填充式输入也可以在 iOS 上使用。

注意

使用 fill 的输入框不应放在 ion-item 中，因为组件之间存在样式冲突。

辅助文本和错误文本

辅助文本和错误文本可以通过 helperText 和 errorText 属性在输入框内部使用。除非将 ion-invalid 和 ion-touched 类添加到 ion-input，否则错误文本不会显示。这确保了在用户有机会输入数据之前不会显示错误。

在 Angular 中，这通过表单验证自动完成。在 JavaScript、React 和 Vue 中，需要根据你自己的验证手动添加这些类。

输入计数器

输入计数器是显示在输入框下方的文本，用于通知用户已输入的字符数占输入框可接受总字符数的比例。添加计数器时，默认行为是将显示的值格式化为 inputLength / maxLength。可以通过向 counterFormatter 属性传入格式化函数来自定义此行为。

ion-item 上的 counter 和 counterFormatter 属性在 Ionic 7 中已弃用，应直接在 ion-input 上使用。

带有计数器的输入框会在输入框和计数器之间添加边框，因此它们不应放在 ion-item 内部，因为 ion-item 会在项目下方添加额外的边框。可以添加 ion-padding-start 类来对齐计数器输入框和项目内部的输入框。

过滤用户输入

开发者可以使用 ionInput 事件来响应用户输入（例如 keypress）更新输入值。这对于过滤掉无效或不需要的字符非常有用。

将值存储在状态变量中时，我们建议同时更新状态变量和 ion-input 组件值。这确保了状态变量和 ion-input 组件值保持同步。

输入掩码

输入掩码是约束输入以支持有效输入值的表达式。Ionic 推荐使用 Maskito 进行输入掩码。Maskito 是一个轻量级、无依赖的输入字段掩码库。它支持多种掩码，包括电话号码、信用卡、日期等。

要开始使用 Maskito，请安装该库：

npm install @maskito/core @maskito/{angular,react,vue}

备注

请将 Maskito 的错误报告提交到 Maskito Github 仓库。如需技术支持，请使用 Ionic 论坛或 Ionic Discord。

起始和结束插槽（实验性功能）

start 和 end 插槽可用于在输入框的任一侧放置图标、按钮或前缀/后缀文本。

请注意，此功能被视为实验性，因为它依赖于Web 组件插槽的模拟版本。因此，模拟行为可能与原生插槽行为不完全一致。

备注

在大多数情况下，放置在这些插槽中的 Icon 组件应设置 aria-hidden="true"。有关更多信息，请参阅 Icon 无障碍文档。

如果插槽内容需要交互，应将其包装在交互式元素中，例如 Button。这确保了内容可以通过 Tab 键聚焦。

主题

颜色

设置 color 属性会更改每个输入框的调色板。在 ios 模式下，此属性会更改光标颜色。在 md 模式下，此属性会更改光标颜色和高亮/下划线颜色。

备注

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

CSS 自定义属性

输入组件使用作用域封装，这意味着它将在运行时通过为每个样式附加一个额外的类来自动限定其 CSS 范围。覆盖 CSS 中的作用域选择器需要更高特异性的选择器。针对 ion-input 进行自定义是无效的；因此我们建议添加一个类并以这种方式进行自定义。

接口

InputChangeEventDetail

interface InputChangeEventDetail {
  value: string | undefined | null;
}

InputCustomEvent

虽然不是必需的，但此接口可用于替代 CustomEvent 接口，以便对此组件发出的 Ionic 事件进行更严格的类型检查。

interface InputCustomEvent extends CustomEvent {
  detail: InputChangeEventDetail;
  target: HTMLIonInputElement;
}

属性

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	`''`

事件

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`

方法

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 阴影部件

No CSS shadow parts available for this component.

CSS 自定义属性

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

插槽

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)

基本用法​

类型​

标签​

标签位置​

标签插槽（实验性功能）​

无可见标签​

清除选项​

填充式输入​

辅助文本和错误文本​

输入计数器​

过滤用户输入​

输入掩码​

起始和结束插槽（实验性功能）​

主题​

颜色​

CSS 自定义属性​

接口​

InputChangeEventDetail​

InputCustomEvent​

属性​

autocapitalize​

autocomplete​

autocorrect​

autofocus​

clearInput​

clearInputIcon​

clearOnEdit​

color​

counter​

counterFormatter​

debounce​

disabled​

enterkeyhint​

errorText​

fill​

helperText​

inputmode​

label​

labelPlacement​

max​

maxlength​

min​

minlength​

mode​

multiple​

name​

pattern​

placeholder​

readonly​

required​

shape​

spellcheck​

step​

type​

value​

事件​

方法​

getInputElement​

setFocus​

CSS 阴影部件​

CSS 自定义属性​

插槽​

Contents

基本用法

类型

标签

标签位置

标签插槽（实验性功能）

无可见标签

清除选项

填充式输入

辅助文本和错误文本

输入计数器

过滤用户输入

输入掩码

起始和结束插槽（实验性功能）

主题

颜色

CSS 自定义属性

接口

InputChangeEventDetail

InputCustomEvent

属性

autocapitalize

autocomplete

autocorrect

autofocus

clearInput

clearInputIcon

clearOnEdit

color

counter

counterFormatter

debounce

disabled

enterkeyhint

errorText

fill

helperText

inputmode

label

labelPlacement

max

maxlength

min

minlength

mode

multiple

name

pattern

placeholder

readonly

required

shape

spellcheck

step

type

value

事件

方法

getInputElement

setFocus

CSS 阴影部件

CSS 自定义属性

插槽