版本：v8

ion-input

input 组件是 HTML input 元素的包装器，具有自定义样式和附加功能。它接受与 HTML input 相同的大部分属性，并与移动设备上的键盘集成。

基本用法

类型

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

清除选项

Input 提供了两种根据交互方式清除输入的选项。第一种方式是添加 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 自定义属性

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

接口

InputChangeEventDetail

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

InputCustomEvent

虽然不是必需的，但此接口可用于替代 CustomEvent 接口，为此组件发出的 Ionic 事件提供更强的类型支持。

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

属性

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

autocomplete

说明	Indicates whether the value of the control can be automatically completed by the browser.
属性	`autocomplete`
类型	"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"
默认值	`'off'`

autocorrect

说明	Whether auto correction should be enabled when the user is entering/editing the text value.
属性	`autocorrect`
类型	`"off" ｜ "on"`
默认值	`'off'`

autofocus

说明	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.
属性	`autofocus`
类型	`boolean`
默认值	`false`

clearInput

说明	If `true`, a clear icon will appear in the input when there is a value. Clicking it clears the input.
属性	`clear-input`
类型	`boolean`
默认值	`false`

clearInputIcon

说明	The icon to use for the clear button. Only applies when `clearInput` is set to `true`.
属性	`clear-input-icon`
类型	`string ｜ undefined`
默认值	`undefined`

clearOnEdit

说明	If `true`, the value will be cleared after focus upon edit. Defaults to `true` when `type` is `"password"`, `false` for all other types.
属性	`clear-on-edit`
类型	`boolean ｜ undefined`
默认值	`undefined`

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`

counter

说明	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.
属性	`counter`
类型	`boolean`
默认值	`false`

counterFormatter

说明	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.
属性	`undefined`
类型	`((inputLength: number, maxLength: number) => string) ｜ undefined`
默认值	`undefined`

debounce

说明	Set the amount of time, in milliseconds, to wait to trigger the `ionInput` event after each keystroke.
属性	`debounce`
类型	`number ｜ undefined`
默认值	`undefined`

disabled

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

enterkeyhint

说明	A hint to the browser for which enter key to display. Possible values: `"enter"`, `"done"`, `"go"`, `"next"`, `"previous"`, `"search"`, and `"send"`.
属性	`enterkeyhint`
类型	`"done" ｜ "enter" ｜ "go" ｜ "next" ｜ "previous" ｜ "search" ｜ "send" ｜ undefined`
默认值	`undefined`

errorText

说明	Text that is placed under the input and displayed when an error is detected.
属性	`error-text`
类型	`string ｜ undefined`
默认值	`undefined`

fill

说明	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.
属性	`fill`
类型	`"outline" ｜ "solid" ｜ undefined`
默认值	`undefined`

helperText

说明	Text that is placed under the input and displayed when no error is detected.
属性	`helper-text`
类型	`string ｜ undefined`
默认值	`undefined`

inputmode

说明	A hint to the browser for which keyboard to display. Possible values: `"none"`, `"text"`, `"tel"`, `"url"`, `"email"`, `"numeric"`, `"decimal"`, and `"search"`.
属性	`inputmode`
类型	`"decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined`
默认值	`undefined`

label

说明	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.
属性	`label`
类型	`string ｜ undefined`
默认值	`undefined`

labelPlacement

说明	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 ("...").
属性	`label-placement`
类型	`"end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start"`
默认值	`'start'`

max

说明	The maximum value, which must not be less than its minimum (min attribute) value.
属性	`max`
类型	`number ｜ string ｜ undefined`
默认值	`undefined`

maxlength

说明	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.
属性	`maxlength`
类型	`number ｜ undefined`
默认值	`undefined`

min

说明	The minimum value, which must not be greater than its maximum (max attribute) value. 这是一个虚拟属性，在初始化时设置一次，之后更改其值不会更新组件。
属性	`min`
类型	`number ｜ string ｜ undefined`
默认值	`undefined`

minlength

说明	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.
属性	`minlength`
类型	`number ｜ undefined`
默认值	`undefined`

mode

说明	The mode determines which platform styles to use. 这是一个虚拟属性，在初始化时设置一次，之后更改其值不会更新组件。
属性	`mode`
类型	`"ios" ｜ "md"`
默认值	`undefined`

multiple

说明	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.
属性	`multiple`
类型	`boolean ｜ undefined`
默认值	`undefined`

name

说明	The name of the control, which is submitted with the form data.
属性	`name`
类型	`string`
默认值	`this.inputId`

pattern

说明	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.
属性	`pattern`
类型	`string ｜ undefined`
默认值	`undefined`

placeholder

说明	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.
属性	`placeholder`
类型	`string ｜ undefined`
默认值	`undefined`

readonly

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

required

说明	If `true`, the user must fill in a value before submitting a form.
属性	`required`
类型	`boolean`
默认值	`false`

shape

说明	The shape of the input. If "round" it will have an increased border radius.
属性	`shape`
类型	`"round" ｜ undefined`
默认值	`undefined`

spellcheck

说明	If `true`, the element will have its spelling and grammar checked.
属性	`spellcheck`
类型	`boolean`
默认值	`false`

step

说明	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.
属性	`step`
类型	`string ｜ undefined`
默认值	`undefined`

type

说明	The type of control to display. The default type is text.
属性	`type`
类型	`"date" ｜ "datetime-local" ｜ "email" ｜ "month" ｜ "number" ｜ "password" ｜ "search" ｜ "tel" ｜ "text" ｜ "time" ｜ "url" ｜ "week"`
默认值	`'text'`

value

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

事件

Name	说明	冒泡
`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

说明	Returns the native `<input>` element used under the hood.
签名	`getInputElement() => Promise<HTMLInputElement>`

setFocus

说明	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.
签名	`setFocus() => Promise<void>`

CSS Shadow Parts

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

CSS 自定义属性

Name	说明
`--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	说明
`--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	说明
`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 Shadow Parts​

CSS 自定义属性​

插槽​

目录

基本用法

类型

标签

标签位置

标签插槽（实验性）

无可见标签

清除选项

填充样式输入

帮助与错误文本

输入计数器

过滤用户输入

输入掩码

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

主题

颜色

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 Shadow Parts

CSS 自定义属性

插槽