ion-textarea

scoped

textarea 组件用于多行文本输入。原生文本区域元素在组件内部渲染。通过控制原生文本区域，可以改善文本区域组件的用户体验和交互性。

¥The textarea component is used for multi-line text input. A native textarea element is rendered inside of the component. The user experience and interactivity of the textarea component is improved by having control over the native textarea.

与原生 textarea 元素不同，Ionic textarea 不支持从内部内容加载其值。textarea 值应在 value 属性中设置。

¥Unlike the native textarea element, the Ionic textarea does not support loading its value from the inner content. The textarea value should be set in the value attribute.

除了 Ionic 属性之外，textarea 组件还接受原生文本区域属性。

¥The textarea component accepts the native textarea attributes in addition to the Ionic properties.

基本用法

¥Basic Usage

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 textarea is accessible to screen readers.

填充文本区域

¥Filled Textareas

Material Design 为文本区域提供了填充样式。项目的 fill 属性可以设置为 "solid" 或 "outline"。

¥Material Design offers filled styles for a textarea. The fill property on the item can be set to either "solid" or "outline".

通过将文本区域的 mode 设置为 md，可以在 iOS 上使用填充文本区域。

¥Filled textareas can be used on iOS by setting the textarea's mode to md.

警告

由于组件之间的样式冲突，使用 fill 的文本区域不应在 ion-item 中使用。

¥Textareas 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-textarea 类，否则不会显示错误文本。这可确保在用户有机会输入数据之前不会显示错误。

¥Helper and error text can be used inside of a textarea 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-textarea. 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.

文本区域计数器

¥Textarea Counter

文本区域计数器是显示在文本区域下方的文本，用于通知用户在文本区域将接受的总数中已输入了多少个字符。添加计数器时，默认行为是将显示的值格式化为 inputLength / maxLength。可以通过将格式化程序函数传递给 counterFormatter 属性来自定义此行为。

¥The textarea counter is text that displays under a textarea to notify the user of how many characters have been entered out of the total that the textarea 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.

自动增长

¥Autogrow

当 autoGrow 属性设置为 true 时，文本区域将根据其内容增大和缩小。

¥When the autoGrow property is set to true, the textarea will grow and shrink based on its contents.

编辑时清除

¥Clear on Edit

将 clearOnEdit 属性设置为 true 将在文本区域模糊后清除，然后再次输入。

¥Setting the clearOnEdit property to true will clear the textarea after it has been blurred and then typed in again.

开始和结束槽（实验）

¥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 textarea.

请注意，此功能被认为是实验性的，因为它依赖于 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.

从旧版 Textarea 语法迁移

¥Migrating from Legacy Textarea Syntax

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

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

开发者可以一次对一个文本区域执行此迁移。虽然开发者可以继续使用旧语法，但我们建议尽快迁移。

¥Developers can perform this migration one textarea 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-textarea 上的 label 属性。可以使用 ion-textarea 上的 labelPlacement 属性来配置标签的位置。

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

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

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

JavaScript
Angular
React
Vue

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Label:</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- After -->
<ion-item>
  <ion-textarea label="Label:" label-placement="floating"></ion-textarea>
</ion-item>


<!-- Fill -->

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

<!-- After -->

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

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

<!-- Before -->
<ion-item counter="true">
  <ion-label position="floating">Label:</ion-label>
  <ion-textarea maxlength="100"></ion-textarea>
  <div slot="helper">Enter text</div>
  <div slot="error">Please enter text</div>
</ion-item>

<!-- After -->

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

<ion-textarea
  label="Label:"
  counter="true"
  maxlength="100"
  helper-text="Enter text"
  error-text="Please enter text"
></ion-textarea>

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Label:</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- After -->
<ion-item>
  <ion-textarea label="Label:" labelPlacement="floating"></ion-textarea>
</ion-item>


<!-- Fill -->

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

<!-- After -->

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

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

<!-- Before -->
<ion-item [counter]="true">
  <ion-label position="floating">Label:</ion-label>
  <ion-textarea maxlength="100"></ion-textarea>
  <div slot="helper">Enter text</div>
  <div slot="error">Please enter text</div>
</ion-item>

<!-- After -->

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

<ion-textarea
  label="Label:"
  [counter]="true"
  maxlength="100"
  helperText="Enter text"
  errorText="Please enter text"
></ion-textarea>

{/* Label and Label Position */}

{/* Before */}
<IonItem>
  <IonLabel position="floating">Label:</IonLabel>
  <IonTextarea></IonTextarea>
</IonItem>

{/* After */}
<IonItem>
  <IonTextarea label="Label:" labelPlacement="floating"></IonTextarea>
</IonItem>


{/* Fill */}

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

{/* After */}

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

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

{/* Before */}
<IonItem counter={true}>
  <IonLabel position="floating">Label:</IonLabel>
  <IonTextarea maxlength="100"></IonTextarea>
  <div slot="helper">Enter text</div>
  <div slot="error">Please enter text</div>
</IonItem>

{/* After */}

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

<IonTextarea
  label="Label:"
  counter={true}
  maxlength="100"
  helperText="Enter text"
  errorText="Please enter text"
></IonTextarea>

<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
  <ion-label position="floating">Label:</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- After -->
<ion-item>
  <ion-textarea label="Label:" label-placement="floating"></ion-textarea>
</ion-item>


<!-- Fill -->

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

<!-- After -->

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

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

<!-- Before -->
<ion-item :counter="true">
  <ion-label position="floating">Label:</ion-label>
  <ion-textarea maxlength="100"></ion-textarea>
  <div slot="helper">Enter text</div>
  <div slot="error">Please enter text</div>
</ion-item>

<!-- After -->

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

<ion-textarea
  label="Label:"
  :counter="true"
  maxlength="100"
  helper-text="Enter text"
  error-text="Please enter text"
></ion-textarea>

使用旧语法

¥Using the Legacy Syntax

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

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

主题化

¥Theming

接口

¥Interfaces

TextareaChangeEventDetail

interface TextareaChangeEventDetail {
  value?: string | null;
}

TextareaCustomEvent

虽然不是必需的，但可以使用此接口代替 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 TextareaCustomEvent extends CustomEvent {
  detail: TextareaChangeEventDetail;
  target: HTMLIonTextareaElement;
}

属性

¥Properties

autoGrow

Description	If `true`, the textarea container will grow and shrink based on the contents of the textarea.
Attribute	`auto-grow`
Type	`boolean`
Default	`false`

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

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`

clearOnEdit

Description	If `true`, the value will be cleared after focus upon edit.
Attribute	`clear-on-edit`
Type	`boolean`
Default	`false`

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`

cols

Description	The visible width of the text control, in average character widths. If it is specified, it must be a positive integer.
Attribute	`cols`
Type	`number ｜ 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 textarea.
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 textarea 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 textarea 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 textarea. 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 textarea. `"start"`: The label will appear to the left of the textarea in LTR and to the right in RTL. `"end"`: The label will appear to the right of the textarea in LTR and to the left in RTL. `"floating"`: The label will appear smaller and above the textarea when the textarea is focused or it has a value. Otherwise it will appear on top of the textarea. `"stacked"`: The label will appear smaller and above the textarea regardless even when the textarea 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'`

maxlength

Description	This attribute specifies the maximum number of characters that the user can enter.
Attribute	`maxlength`
Type	`number ｜ undefined`
Default	`undefined`

minlength

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

name

Description	The name of the control, which is submitted with the form data.
Attribute	`name`
Type	`string`
Default	`this.inputId`

placeholder

Description	Instructional text that shows before the input has a value.
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`

rows

Description	The number of visible text lines for the control.
Attribute	`rows`
Type	`number ｜ undefined`
Default	`undefined`

shape

Description	The shape of the textarea. 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`

value

Description	The value of the textarea.
Attribute	`value`
Type	`null ｜ string ｜ undefined`
Default	`''`

wrap

Description	Indicates how the control wraps text.
Attribute	`wrap`
Type	`"hard" ｜ "off" ｜ "soft" ｜ undefined`
Default	`undefined`

事件

¥Events

Name	Description	Bubbles
`ionBlur`	Emitted when the input loses focus.	`true`
`ionChange`	The `ionChange` event is fired when the user modifies the textarea's value. Unlike the `ionInput` event, the `ionChange` event is fired when the element loses focus after its value has been modified. 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 textarea's value. Unlike the `ionChange` event, the `ionInput` event is fired for each alteration to the textarea's value. This typically happens for each keystroke as the user types. When `clearOnEdit` is enabled, the `ionInput` event will be fired when the user clears the textarea by performing a keydown event.	`true`

方法

¥Methods

getInputElement

Description	Returns the native `<textarea>` element used under the hood.
Signature	`getInputElement() => Promise<HTMLTextAreaElement>`

setFocus

Description	Sets focus on the native `textarea` in `ion-textarea`. Use this method instead of the global `textarea.focus()`. 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 textarea
`--border-color`	Color of the border below the textarea when using helper text, error text, or counter
`--border-radius`	Border radius of the textarea
`--border-style`	Style of the border below the textarea when using helper text, error text, or counter
`--border-width`	Width of the border below the textarea when using helper text, error text, or counter
`--color`	Color of the text
`--highlight-color-focused`	The color of the highlight on the textarea when focused
`--highlight-color-invalid`	The color of the highlight on the textarea when invalid
`--highlight-color-valid`	The color of the highlight on the textarea when valid
`--highlight-height`	The height of the highlight on the textarea. Only applies to md mode.
`--padding-bottom`	Bottom padding of the textarea
`--padding-end`	Right padding if direction is left-to-right, and left padding if direction is right-to-left of the textarea
`--padding-start`	Left padding if direction is left-to-right, and right padding if direction is right-to-left of the textarea
`--padding-top`	Top padding of the textarea
`--placeholder-color`	Color of the placeholder text
`--placeholder-font-style`	Style of the placeholder text
`--placeholder-font-weight`	Weight of the placeholder text
`--placeholder-opacity`	Opacity of the placeholder text

插槽

¥Slots

Name	Description
`end`	Content to display at the trailing edge of the textarea. (EXPERIMENTAL)
`label`	The label text to associate with the textarea. Use the `labelPlacement` property to control where the label is placed relative to the textarea. Use this if you need to render a label with custom HTML. (EXPERIMENTAL)
`start`	Content to display at the leading edge of the textarea. (EXPERIMENTAL)

基本用法​

标签​

标签放置​

标签槽（实验性）​

无可见标签​

填充文本区域​

辅助程序和错误文本​

文本区域计数器​

自动增长​

编辑时清除​

开始和结束槽（实验）​

从旧版 Textarea 语法迁移​

使用现代语法​

使用旧语法​

主题化​

接口​

TextareaChangeEventDetail​

TextareaCustomEvent​

属性​

autoGrow​

autocapitalize​

autofocus​

clearOnEdit​

color​

cols​

counter​

counterFormatter​

debounce​

disabled​

enterkeyhint​

errorText​

fill​

helperText​

inputmode​

label​

labelPlacement​

maxlength​

minlength​

mode​

name​

placeholder​

readonly​

required​

rows​

shape​

spellcheck​

value​

wrap​

事件​

方法​

getInputElement​

setFocus​

CSS 阴影部分​

CSS 自定义属性​

插槽​

目录