版本：v7

ion-textarea

scoped

textarea 组件用于多行文本输入。组件内部会渲染一个原生的 textarea 元素。通过对原生 textarea 的控制，textarea 组件的用户体验和交互性得到了提升。

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

textarea 组件除了支持 Ionic 属性外，还接受原生 textarea 属性。

基本用法

填充式文本输入框

Material Design 为 textarea 提供了填充样式。可以在 item 上将 fill 属性设置为 "solid" 或 "outline"。

由于 fill 样式在视觉上定义了 textarea 容器，因此使用 fill 的 textarea 不应在 ion-item 中使用。

通过在 textarea 上将 mode 设置为 md，可以在 iOS 上使用填充式 textarea。

辅助文本与错误文本

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

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

文本输入框计数器

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

自动增长

将 autoGrow 属性设置为 true 时，textarea 将根据其内容自动增长和收缩。

编辑时清除

将 clearOnEdit 属性设置为 true 将在 textarea 失去焦点后再次键入时清除其内容。

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

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

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

备注

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

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

从旧版 Textarea 语法迁移

Ionic 7.0 引入了更简洁的 textarea 语法。这种新语法减少了设置 textarea 所需的样板代码，解决了无障碍性问题，并改善了开发者体验。

开发者可以一次迁移一个 textarea。虽然开发者可以继续使用旧版语法，但我们建议尽快迁移。

使用现代语法

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

移除 ion-label，改为在 ion-textarea 上使用 label 属性。可以使用 ion-textarea 上的 labelPlacement 属性配置标签位置。
将 textarea 特定的属性从 ion-item 移动到 ion-textarea 上。这包括 counter、counterFormatter、fill 和 shape 属性。
移除 ion-item 上对 helper 和 error 插槽的使用，改为使用 ion-textarea 上的 helperText 和 errorText 属性。

JavaScript
Angular
React
Vue

<!-- 标签与标签位置 -->

<!-- 之前 -->
<ion-item>
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-textarea label="标签：" label-placement="floating"></ion-textarea>
</ion-item>


<!-- 填充模式 -->

<!-- 之前 -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- 之后 -->

<!-- 使用 `fill` 属性的 Textarea 不应放在 ion-item 中 -->
<ion-textarea fill="outline" shape="round" label="标签：" label-placement="floating"></ion-textarea>

<!-- ion-item 上的 Textarea 特有功能 -->

<!-- 之前 -->
<ion-item counter="true">
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea maxlength="100"></ion-textarea>
  <div slot="helper">输入文本</div>
  <div slot="error">请输入文本</div>
</ion-item>

<!-- 之后 -->

<!--
  当 textarea 位于 item/list 中时，不应使用计数器、帮助文本等元数据。
  如需为 textarea 提供更多上下文，可考虑在 ion-list 下方使用 ion-note。
-->

<ion-textarea
  label="标签："
  counter="true"
  maxlength="100"
  helper-text="输入文本"
  error-text="请输入文本"
></ion-textarea>

<!-- 标签与标签位置 -->

<!-- 之前 -->
<ion-item>
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-textarea label="标签：" labelPlacement="floating"></ion-textarea>
</ion-item>


<!-- 填充模式 -->

<!-- 之前 -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- 之后 -->

<!-- 使用 `fill` 属性的 Textarea 不应放在 ion-item 中 -->
<ion-textarea fill="outline" shape="round" label="标签：" labelPlacement="floating"></ion-textarea>

<!-- ion-item 上的 Textarea 特有功能 -->

<!-- 之前 -->
<ion-item [counter]="true">
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea maxlength="100"></ion-textarea>
  <div slot="helper">输入文本</div>
  <div slot="error">请输入文本</div>
</ion-item>

<!-- 之后 -->

<!--
  当 textarea 位于 item/list 中时，不应使用计数器、帮助文本等元数据。
  如需为 textarea 提供更多上下文，可考虑在 ion-list 下方使用 ion-note。
-->

<ion-textarea
  label="标签："
  [counter]="true"
  maxlength="100"
  helperText="输入文本"
  errorText="请输入文本"
></ion-textarea>

{/* 标签与标签位置 */}

{/* 之前 */}
<IonItem>
  <IonLabel position="floating">标签：</IonLabel>
  <IonTextarea></IonTextarea>
</IonItem>

{/* 之后 */}
<IonItem>
  <IonTextarea label="标签：" labelPlacement="floating"></IonTextarea>
</IonItem>


{/* 填充模式 */}

{/* 之前 */}
<IonItem fill="outline" shape="round">
  <IonLabel position="floating">标签：</IonLabel>
  <IonTextarea></IonTextarea>
</IonItem>

{/* 之后 */}

{/* 使用 `fill` 属性的 Textarea 不应放在 IonItem 中 */}
<IonTextarea fill="outline" shape="round" label="标签：" labelPlacement="floating"></IonTextarea>

{/* IonItem 上的 Textarea 特有功能 */}

{/* 之前 */}
<IonItem counter={true}>
  <IonLabel position="floating">标签：</IonLabel>
  <IonTextarea maxlength="100"></IonTextarea>
  <div slot="helper">输入文本</div>
  <div slot="error">请输入文本</div>
</IonItem>

{/* 之后 */}

{/*
  当 textarea 位于 item/list 中时，不应使用计数器、帮助文本等元数据。
  如需为 textarea 提供更多上下文，可考虑在 IonList 下方使用 IonNote。
*/}

<IonTextarea
  label="标签："
  counter={true}
  maxlength="100"
  helperText="输入文本"
  errorText="请输入文本"
></IonTextarea>

<!-- 标签与标签位置 -->

<!-- 之前 -->
<ion-item>
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- 之后 -->
<ion-item>
  <ion-textarea label="标签：" label-placement="floating"></ion-textarea>
</ion-item>


<!-- 填充模式 -->

<!-- 之前 -->
<ion-item fill="outline" shape="round">
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea></ion-textarea>
</ion-item>

<!-- 之后 -->

<!-- 使用 `fill` 属性的 Textarea 不应放在 ion-item 中 -->
<ion-textarea fill="outline" shape="round" label="标签：" label-placement="floating"></ion-textarea>

<!-- ion-item 上的 Textarea 特有功能 -->

<!-- 之前 -->
<ion-item :counter="true">
  <ion-label position="floating">标签：</ion-label>
  <ion-textarea maxlength="100"></ion-textarea>
  <div slot="helper">输入文本</div>
  <div slot="error">请输入文本</div>
</ion-item>

<!-- 之后 -->

<!--
  当 textarea 位于 item/list 中时，不应使用计数器、帮助文本等元数据。
  如需为 textarea 提供更多上下文，可考虑在 ion-list 下方使用 ion-note。
-->

<ion-textarea
  label="标签："
  :counter="true"
  maxlength="100"
  helper-text="输入文本"
  error-text="请输入文本"
></ion-textarea>

使用旧版语法

Ionic 使用启发式方法检测应用是否使用现代 textarea 语法。在某些情况下，可能更倾向于继续使用旧版语法。开发者可以将 ion-textarea 上的 legacy 属性设置为 true，以强制该 textarea 实例使用旧版语法。

主题定制

接口

TextareaChangeEventDetail

interface TextareaChangeEventDetail {
  value?: string | null;
}

TextareaCustomEvent

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

interface TextareaCustomEvent extends CustomEvent {
  detail: TextareaChangeEventDetail;
  target: HTMLIonTextareaElement;
}

属性

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

legacy

Description	Set the `legacy` property to `true` to forcibly use the legacy form control markup. Ionic will only opt components in to the modern form markup when they are using either the `aria-label` attribute or the default slot that contains the label text. As a result, the `legacy` property should only be used as an escape hatch when you want to avoid this automatic opt-in behavior. Note that this property will be removed in an upcoming major release of Ionic, and all form components will be opted-in to using the modern form markup.
Attribute	`legacy`
Type	`boolean ｜ undefined`
Default	`undefined`

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

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`

事件

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

方法

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

No CSS shadow parts available for this component.

CSS 自定义属性

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

插槽

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​

legacy​

maxlength​

minlength​

mode​

name​

placeholder​

readonly​

required​

rows​

shape​

spellcheck​

value​

wrap​

事件​

方法​

getInputElement​

setFocus​

CSS Shadow Parts​

CSS 自定义属性​

插槽​

Contents