ion-textarea

scoped

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

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

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

基本用法

标签

标签应用于描述 textarea。它们可以在视觉上使用，当用户聚焦 textarea 时，屏幕阅读器也会将其读出。这使用户能够轻松理解 textarea 的用途。Textarea 有几种分配标签的方式：

• label 属性：用于纯文本标签
• label 插槽：用于自定义 HTML 标签（实验性）
• aria-label：用于为屏幕阅读器提供标签，但不添加可见标签

标签位置

默认情况下，标签将占用其内容的宽度。开发者可以使用 labelPlacement 属性控制标签相对于控件的位置。

标签插槽（实验性）

虽然纯文本标签应通过 label 属性传递，但如果需要自定义 HTML，可以通过 label 插槽传递。

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

无可见标签

如果不需要可见标签，开发者仍应提供 aria-label，以便屏幕阅读器可以访问 textarea。

填充样式 Textarea

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

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

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

帮助和错误文本

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

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

Textarea 计数器

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

自动增长

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

编辑时清除

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

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

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

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

备注

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

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

从旧版 Textarea 语法迁移

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

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

使用现代语法

使用现代语法包括三个步骤：

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

JavaScript

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

Angular

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

React

{/* 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>

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>

使用旧版语法

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

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

legacy

说明	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.
属性	legacy
类型	boolean ｜ undefined
默认值	undefined

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.	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 阴影部分

该组件没有可用的 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
--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)