ion-input

scoped

输入组件是 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".

label 属性：用于纯文本标签

¥label property: used for plaintext labels
label 插槽：用于自定义 HTML 标签（实验性）

¥label slot: used for custom HTML labels (experimental)
aria-label：用于为屏幕阅读器提供标签，但不添加可见标签

¥aria-label: used to provide a label for screen readers but adds no visible 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 Component 插槽的模拟版本。因此，模拟行为可能与原生插槽行为不完全匹配。

¥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 中使用。

¥Inputs that use fill should not be used in an ion-item due to styling conflicts between the components.

辅助程序和错误文本

¥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-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 是一个轻量级、无依赖的库，用于屏蔽输入字段。它支持多种掩码，包括调用号码、信用卡、日期等。

¥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 向 Maskito Github 存储库提交错误报告。如需技术支持，请使用 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 Component 插槽的模拟版本。因此，模拟行为可能与原生插槽行为不完全匹配。

注意

在大多数情况下，放置在这些插槽中的图标组件应具有 aria-hidden="true"。请参阅图标辅助功能文档了解更多信息。

¥In most cases, Icon components placed in these slots should have aria-hidden="true". See the Icon accessibility docs for more information.

如果插槽内容需要进行交互，则应将其封装在交互元素中，例如按钮。这确保了可以通过选项卡切换到内容。

¥If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a Button. This ensures that the content can be tabbed to.

主题化

¥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 属性。

¥The color property does not change the text color of the input. For that, use the --color CSS property.

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.

从旧输入语法迁移

¥Migrating from Legacy Input Syntax

Ionic 7.0 中引入了更简单的输入语法。这种新语法减少了设置输入所需的样板文件，解决了可访问性问题，并改善了开发者体验。

¥A simpler input syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an input, resolves accessibility issues, and improves the developer experience.

开发者可以一次输入一个输入来执行此迁移。虽然开发者可以继续使用旧语法，但我们建议尽快迁移。

¥Developers can perform this migration one input at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.

使用现代语法

¥Using the Modern Syntax

使用现代语法涉及三个步骤：

¥Using the modern syntax involves three steps:

删除 ion-label 并使用 ion-input 上的 label 属性。可以使用 ion-input 上的 labelPlacement 属性来配置标签的位置。

¥Remove ion-label and use the label property on ion-input instead. The placement of the label can be configured using the labelPlacement property on ion-input.
将特定于输入的属性从 ion-item 移至 ion-input。这包括 counter、counterFormatter、fill 和 shape 属性。

¥Move input-specific properties from ion-item on to ion-input. This includes the counter, counterFormatter, fill, and shape properties.
删除 ion-item 上 helper 和 error 插槽的使用，并使用 ion-input 上的 helperText 和 errorText 属性。

¥Remove usages of the helper and error slots on ion-item and use the helperText and errorText properties on ion-input instead.

JavaScript
Angular
React
Vue

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Email:</ion-label>
  <ion-input></ion-input>
</ion-item>

<!-- After -->
<ion-item>
  <ion-input label="Email:" label-placement="floating"></ion-input>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Email:</ion-label>
  <ion-input></ion-input>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-input fill="outline" shape="round" label="Email:" label-placement="floating"></ion-input>

<!-- Input-specific features on ion-item -->

<!-- Before -->
<ion-item counter="true">
  <ion-label position="floating">Email:</ion-label>
  <ion-input maxlength="100"></ion-input>
  <div slot="helper">Enter an email</div>
  <div slot="error">Please enter a valid email</div>
</ion-item>

<!-- After -->

<!--
  Metadata such as counters and helper text should not
  be used when an input is in an item/list. If you need to
  provide more context on a input, consider using an ion-note
  underneath the ion-list.
-->

<ion-input
  label="Email:"
  counter="true"
  maxlength="100"
  helper-text="Enter an email"
  error-text="Please enter a valid email"
></ion-input>

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Email:</ion-label>
  <ion-input></ion-input>
</ion-item>

<!-- After -->
<ion-item>
  <ion-input label="Email:" labelPlacement="floating"></ion-input>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Email:</ion-label>
  <ion-input></ion-input>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-input fill="outline" shape="round" label="Email:" labelPlacement="floating"></ion-input>

<!-- Input-specific features on ion-item -->

<!-- Before -->
<ion-item [counter]="true">
  <ion-label position="floating">Email:</ion-label>
  <ion-input maxlength="100"></ion-input>
  <div slot="helper">Enter an email</div>
  <div slot="error">Please enter a valid email</div>
</ion-item>

<!-- After -->

<!--
  Metadata such as counters and helper text should not
  be used when an input is in an item/list. If you need to
  provide more context on a input, consider using an ion-note
  underneath the ion-list.
-->

<ion-input
  label="Email:"
  [counter]="true"
  maxlength="100"
  helperText="Enter an email"
  errorText="Please enter a valid email"
></ion-input>

{/* Label and Label Position */}

{/* Before */}
<IonItem>
  <IonLabel position="floating">Email:</IonLabel>
  <IonInput></IonInput>
</IonItem>

{/* After */}
<IonItem>
  <IonInput label="Email:" labelPlacement="floating"></IonInput>
</IonItem>


{/* Fill */}

{/* Before */}
<IonItem fill="outline" shape="round">
  <IonLabel position="floating">Email:</IonLabel>
  <IonInput></IonInput>
</IonItem>

{/* After */}

{/* Inputs using `fill` should not be placed in IonItem */}
<IonInput fill="outline" shape="round" label="Email:" labelPlacement="floating"></IonInput>

{/* Input-specific features on IonItem */}

{/* Before */}
<IonItem counter={true}>
  <IonLabel position="floating">Email:</IonLabel>
  <IonInput maxlength="100"></IonInput>
  <div slot="helper">Enter an email</div>
  <div slot="error">Please enter a valid email</div>
</IonItem>

{/* After */}

{/*
  Metadata such as counters and helper text should not
  be used when an input is in an item/list. If you need to
  provide more context on a input, consider using an IonNote
  underneath the IonList.
*/}

<IonInput
  label="Email:"
  counter={true}
  maxlength="100"
  helperText="Enter an email"
  errorText="Please enter a valid email"
></IonInput>

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Email:</ion-label>
  <ion-input></ion-input>
</ion-item>

<!-- After -->
<ion-item>
  <ion-input label="Email:" label-placement="floating"></ion-input>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">Email:</ion-label>
  <ion-input></ion-input>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-input fill="outline" shape="round" label="Email:" label-placement="floating"></ion-input>

<!-- Input-specific features on ion-item -->

<!-- Before -->
<ion-item :counter="true">
  <ion-label position="floating">Email:</ion-label>
  <ion-input maxlength="100"></ion-input>
  <div slot="helper">Enter an email</div>
  <div slot="error">Please enter a valid email</div>
</ion-item>

<!-- After -->

<!--
  Metadata such as counters and helper text should not
  be used when an input is in an item/list. If you need to
  provide more context on a input, consider using an ion-note
  underneath the ion-list.
-->

<ion-input
  label="Email:"
  :counter="true"
  maxlength="100"
  helper-text="Enter an email"
  error-text="Please enter a valid email"
></ion-input>

使用旧语法

¥Using the Legacy Syntax

Ionic 使用启发式方法来检测应用是否使用现代输入语法。在某些情况下，最好继续使用旧语法。开发者可以将 ion-input 上的 legacy 属性设置为 true，以强制该输入实例使用旧语法。

¥Ionic uses heuristics to detect if an app is using the modern input syntax. In some instances, it may be preferable to continue using the legacy syntax. Developers can set the legacy property on ion-input to true to force that instance of the input to use the legacy syntax.

接口

¥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	"name" ｜ "email" ｜ "tel" ｜ "url" ｜ "on" ｜ "off" ｜ "honorific-prefix" ｜ "given-name" ｜ "additional-name" ｜ "family-name" ｜ "honorific-suffix" ｜ "nickname" ｜ "username" ｜ "new-password" ｜ "current-password" ｜ "one-time-code" ｜ "organization-title" ｜ "organization" ｜ "street-address" ｜ "address-line1" ｜ "address-line2" ｜ "address-line3" ｜ "address-level4" ｜ "address-level3" ｜ "address-level2" ｜ "address-level1" ｜ "country" ｜ "country-name" ｜ "postal-code" ｜ "cc-name" ｜ "cc-given-name" ｜ "cc-additional-name" ｜ "cc-family-name" ｜ "cc-number" ｜ "cc-exp" ｜ "cc-exp-month" ｜ "cc-exp-year" ｜ "cc-csc" ｜ "cc-type" ｜ "transaction-currency" ｜ "transaction-amount" ｜ "language" ｜ "bday" ｜ "bday-day" ｜ "bday-month" ｜ "bday-year" ｜ "sex" ｜ "tel-country-code" ｜ "tel-national" ｜ "tel-area-code" ｜ "tel-local" ｜ "tel-extension" ｜ "impp" ｜ "photo"
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.
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.
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

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)

基本用法​

类型​

标签​

标签放置​

标签槽（实验性）​

无可见标签​

清除选项​

填充输入​

辅助程序和错误文本​

输入计数器​

过滤用户输入​

输入屏蔽​

开始和结束槽（实验）​

主题化​

颜色​

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 自定义属性​

插槽​

目录

基本用法

类型

标签

标签放置

标签槽（实验性）

无可见标签

清除选项

填充输入

辅助程序和错误文本

输入计数器

过滤用户输入

输入屏蔽

开始和结束槽（实验）

主题化

颜色

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 自定义属性

插槽