ion-textarea

textarea 组件用于多行文本输入。组件内部渲染了一个原生的 textarea 元素。通过控制原生 textarea，可以提升 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 组件还接受原生 textarea 属性。

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

基本用法

🌐 Basic Usage

填充文本区域

🌐 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".

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

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

warning

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

辅助程序和错误文本

🌐 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

textarea 计数器是在 textarea 下方显示的文本，用于通知用户已输入的字符数占 textarea 可接受的总字符数的比例。添加计数器时，默认行为是将显示的值格式化为 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 组件插槽的模拟版本。因此，模拟行为可能与原生插槽行为不完全相同。

note

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

如果插槽内容是为了互动的，应将其封装在交互元素中，例如 Button。这确保了内容可以通过 Tab 键跳转。

🌐 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

接口

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

事件

🌐 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

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)

基本用法​

标签​

标签放置​

标签槽（实验性）​

无可见标签​

填充文本区域​

辅助程序和错误文本​

文本区域计数器​

自动增长​

编辑时清除​

开始和结束槽（实验）​

主题化​

接口​

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

插槽​

目录