ion-textarea

作用域

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

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

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

基本用法

标签

标签应该用于描述 textarea。它们可以被视觉化使用，并且当用户聚焦在 textarea 上时，屏幕阅读器也会读取它们。这使得用户很容易理解 textarea 的意图。Textarea 有几种方法可以分配标签

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

标签位置

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

标签插槽（实验性）

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

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

无可见标签

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

填充的 Textareas

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

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

警告

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

辅助文本和错误文本

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

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

Textarea 计数器

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

自动增长

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

编辑时清除

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

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

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

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

注意

在大多数情况下，放置在这些插槽中的 图标 组件应该具有 aria-hidden="true"。有关详细信息，请参阅 图标辅助功能文档。

如果插槽内容旨在进行交互，则应将其包装在交互式元素中，例如 按钮。这确保了内容可以被切换到。

从传统 Textarea 语法迁移

Ionic 在 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

描述	如果为 true，textarea 容器将根据 textarea 的内容进行伸缩。
属性	auto-grow
类型	boolean
默认	false

autocapitalize

描述	指示文本值是否以及如何自动大写，具体取决于用户输入/编辑的方式。可用选项："off"、"none"、"on"、"sentences"、"words"、"characters"。
属性	autocapitalize
类型	string
默认	'none'

autofocus

描述	在原生输入元素上设置 autofocus 属性。 这可能不足以使元素在页面加载时获得焦点。有关更多信息，请参阅 管理焦点。
属性	autofocus
类型	boolean
默认	false

clearOnEdit

描述	如果为 true，则在编辑后获得焦点时，该值将被清除。
属性	clear-on-edit
类型	boolean
默认	false

color

描述	要从应用程序调色板中使用的颜色。默认选项为："primary"、"secondary"、"tertiary"、"success"、"warning"、"danger"、"light"、"medium" 和 "dark"。有关颜色的更多信息，请参阅 主题。
属性	color
类型	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
默认	undefined

cols

描述	文本控件的可见宽度，以平均字符宽度为单位。如果指定，则必须为正整数。
属性	cols
类型	number ｜ undefined
默认	undefined

counter

描述	如果为 true，则字符计数器将显示已使用字符与总字符限制的比例。开发人员还必须设置 maxlength 属性，以便计数器能够正确计算。
属性	counter
类型	boolean
默认	false

counterFormatter

描述	用于格式化计数器文本的回调函数。默认情况下，计数器文本设置为 "itemLength / maxLength"。 如果您需要从回调函数中访问 this，请参阅 https://ionic.js.cn/docs/troubleshooting/runtime#accessing-this。
属性	undefined
类型	((inputLength: number, maxLength: number) => string) ｜ undefined
默认	undefined

debounce

描述	设置每次按键后等待触发 ionInput 事件的时间（以毫秒为单位）。
属性	debounce
类型	number ｜ undefined
默认	undefined

disabled

描述	如果为 true，则用户无法与 textarea 交互。
属性	disabled
类型	boolean
默认	false

enterkeyhint

描述	针对要显示的 Enter 键，对浏览器的提示。可能的值："enter"、"done"、"go"、"next"、"previous"、"search" 和 "send"。
属性	enterkeyhint
类型	"done" ｜ "enter" ｜ "go" ｜ "next" ｜ "previous" ｜ "search" ｜ "send" ｜ undefined
默认	undefined

errorText

描述	放置在 textarea 下面并在检测到错误时显示的文本。
属性	error-text
类型	string ｜ undefined
默认	undefined

fill

描述	项目的填充。如果为 "solid"，则项目将具有背景。如果为 "outline"，则项目将为透明色，带有边框。仅在 md 模式下可用。
属性	fill
类型	"outline" ｜ "solid" ｜ undefined
默认	undefined

helperText

描述	放置在 textarea 下面并在未检测到错误时显示的文本。
属性	helper-text
类型	string ｜ undefined
默认	undefined

inputmode

描述	针对要显示的键盘，对浏览器的提示。可能的值："none"、"text"、"tel"、"url"、"email"、"numeric"、"decimal" 和 "search"。
属性	inputmode
类型	"decimal" ｜ "email" ｜ "none" ｜ "numeric" ｜ "search" ｜ "tel" ｜ "text" ｜ "url" ｜ undefined
默认	undefined

label

描述	与 textarea 关联的可见标签。 如果需要呈现纯文本标签，请使用此属性。 如果同时使用 label 属性和 label 插槽，则 label 属性将优先。
属性	label
类型	string ｜ undefined
默认	undefined

labelPlacement

描述	标签相对于 textarea 的放置位置。"start"：标签将出现在 textarea 的左侧（LTR）或右侧（RTL）。"end"：标签将出现在 textarea 的右侧（LTR）或左侧（RTL）。"floating"：当 textarea 获得焦点或具有值时，标签将以更小的尺寸出现在 textarea 上方。否则，标签将出现在 textarea 的顶部。"stacked"：标签将以更小的尺寸出现在 textarea 上方，无论 textarea 是否处于模糊状态或是否具有值。"fixed"：标签的行为与 "start" 相同，但具有固定宽度。较长的文本将使用省略号 ("...") 进行截断。
属性	label-placement
类型	"end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start"
默认	'start'

maxlength

描述	此属性指定用户可以输入的最大字符数。
属性	maxlength
类型	number ｜ undefined
默认	undefined

minlength

描述	此属性指定用户可以输入的最小字符数。
属性	minlength
类型	number ｜ undefined
默认	undefined

mode

描述	模式决定要使用的平台样式。
属性	mode
类型	"ios" ｜ "md"
默认	undefined

name

描述	控件的名称，将与表单数据一起提交。
属性	name
类型	string
默认	this.inputId

placeholder

描述	输入具有值之前显示的说明性文本。
属性	placeholder
类型	string ｜ undefined
默认	undefined

readonly

描述	如果为 true，则用户无法修改值。
属性	readonly
类型	boolean
默认	false

required

描述	如果为 true，则用户必须在提交表单之前填写一个值。
属性	required
类型	boolean
默认	false

rows

描述	控件的可见文本行数。
属性	rows
类型	number ｜ undefined
默认	undefined

shape

描述	textarea 的形状。如果为 "round"，则将具有更大的边框半径。
属性	shape
类型	"round" ｜ undefined
默认	undefined

spellcheck

描述	如果为 true，则元素将进行拼写和语法检查。
属性	spellcheck
类型	boolean
默认	false

value

描述	textarea 的值。
属性	value
类型	null ｜ string ｜ undefined
默认	''

wrap

描述	指示控件如何换行文本。
属性	wrap
类型	"hard" ｜ "off" ｜ "soft" ｜ undefined
默认	undefined

事件

名称	描述	冒泡
ionBlur	当输入失去焦点时发出。	true
ionChange	当用户修改 textarea 的值时，会触发 ionChange 事件。与 ionInput 事件不同，ionChange 事件在元素失去焦点且其值已修改后触发。 以编程方式设置 value 属性时，此事件不会发出。	true
ionFocus	当输入获得焦点时发出。	true
ionInput	每次用户修改 textarea 的值时，都会触发 ionInput 事件。与 ionChange 事件不同，ionInput 事件针对 textarea 值的每次更改触发。这通常在用户键入时针对每次按键触发。 当 clearOnEdit 启用时，用户通过执行键盘按下事件清除 textarea 时，会触发 ionInput 事件。	true

方法

getInputElement

描述	返回幕后使用的原生 <textarea> 元素。
签名	getInputElement() => Promise<HTMLTextAreaElement>

setFocus

描述	在 ion-textarea 中的原生 textarea 上设置焦点。使用此方法而不是全局 textarea.focus()。 有关更多信息，请参阅 管理焦点。
签名	setFocus() => Promise<void>

CSS 阴影部分

此组件不提供 CSS 阴影部分。

CSS 自定义属性

iOS

名称	描述
--background	textarea 的背景
--border-color	使用辅助文本、错误文本或计数器时，textarea 下方边框的颜色
--border-radius	textarea 的边框半径
--border-style	使用辅助文本、错误文本或计数器时，textarea 下方边框的样式
--border-width	使用辅助文本、错误文本或计数器时，textarea 下方边框的宽度
--color	文本的颜色
--highlight-color-focused	textarea 获得焦点时的突出显示颜色
--highlight-color-invalid	textarea 无效时的突出显示颜色
--highlight-color-valid	textarea 有效时的突出显示颜色
--highlight-height	textarea 上突出显示的高度。仅适用于 md 模式。
--padding-bottom	textarea 的底部填充
--padding-end	如果方向为从左到右，则为 textarea 的右侧填充；如果方向为从右到左，则为 textarea 的左侧填充
--padding-start	如果方向为从左到右，则在文本区域左侧填充；如果方向为从右到左，则在文本区域右侧填充。
--padding-top	文本区域的顶部填充。
--placeholder-color	占位符文本的颜色。
--placeholder-font-style	占位符文本的样式。
--placeholder-font-weight	占位符文本的粗细。
--placeholder-opacity	占位符文本的不透明度。

MD

名称	描述
--background	textarea 的背景
--border-color	使用辅助文本、错误文本或计数器时，textarea 下方边框的颜色
--border-radius	textarea 的边框半径
--border-style	使用辅助文本、错误文本或计数器时，textarea 下方边框的样式
--border-width	使用辅助文本、错误文本或计数器时，textarea 下方边框的宽度
--color	文本的颜色
--highlight-color-focused	textarea 获得焦点时的突出显示颜色
--highlight-color-invalid	textarea 无效时的突出显示颜色
--highlight-color-valid	textarea 有效时的突出显示颜色
--highlight-height	textarea 上突出显示的高度。仅适用于 md 模式。
--padding-bottom	textarea 的底部填充
--padding-end	如果方向为从左到右，则为 textarea 的右侧填充；如果方向为从右到左，则为 textarea 的左侧填充
--padding-start	如果方向为从左到右，则在文本区域左侧填充；如果方向为从右到左，则在文本区域右侧填充。
--padding-top	文本区域的顶部填充。
--placeholder-color	占位符文本的颜色。
--placeholder-font-style	占位符文本的样式。
--placeholder-font-weight	占位符文本的粗细。
--placeholder-opacity	占位符文本的不透明度。

插槽

名称	描述
end	在文本区域的尾部显示的内容。 (实验性)
label	与文本区域关联的标签文本。 使用 labelPlacement 属性来控制标签相对于文本区域的位置。 如果需要使用自定义 HTML 渲染标签，请使用此属性。 (实验性)
start	在文本区域的头部显示的内容。 (实验性)