版本：v8

ion-textarea

scoped

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

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

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

基本用法

填充样式文本区域

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

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

注意

使用 fill 的文本区域不应放在 ion-item 中使用，因为组件间存在样式冲突。

帮助文本与错误文本

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

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

文本区域计数器

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

自动增长

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

编辑时清除

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

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

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

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

备注

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

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

主题

接口

TextareaChangeEventDetail

interface TextareaChangeEventDetail {
  value?: string | null;
}

TextareaCustomEvent

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

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

属性

autoGrow

说明	If `true`, the textarea container will grow and shrink based on the contents of the textarea.
属性	`auto-grow`
类型	`boolean`
默认值	`false`

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`
默认值	`'none'`

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`

clearOnEdit

说明	If `true`, the value will be cleared after focus upon edit.
属性	`clear-on-edit`
类型	`boolean`
默认值	`false`

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`

cols

说明	The visible width of the text control, in average character widths. If it is specified, it must be a positive integer.
属性	`cols`
类型	`number ｜ 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 textarea.
属性	`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 textarea 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 textarea 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 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.
属性	`label`
类型	`string ｜ undefined`
默认值	`undefined`

labelPlacement

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

maxlength

说明	This attribute specifies the maximum number of characters that the user can enter.
属性	`maxlength`
类型	`number ｜ undefined`
默认值	`undefined`

minlength

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

name

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

placeholder

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

rows

说明	The number of visible text lines for the control.
属性	`rows`
类型	`number ｜ undefined`
默认值	`undefined`

shape

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

value

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

wrap

说明	Indicates how the control wraps text.
属性	`wrap`
类型	`"hard" ｜ "off" ｜ "soft" ｜ undefined`
默认值	`undefined`

事件

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

方法

getInputElement

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

setFocus

说明	Sets focus on the native `textarea` in `ion-textarea`. Use this method instead of the global `textarea.focus()`. See managing focus for more information.
签名	`setFocus() => Promise<void>`

CSS Shadow Parts

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

CSS 自定义属性

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

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

插槽

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

基本用法​

标签​

标签位置​

标签插槽（实验性）​

无可视标签​

填充样式文本区域​

帮助文本与错误文本​

文本区域计数器​

自动增长​

编辑时清除​

开始和结束插槽（实验性）​

主题​

接口​

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

CSS 自定义属性​

插槽​

目录