多行文本输入框组件及 CSS 属性

scoped

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

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

除了 Ionic 属性外，文本输入框组件还接受原生 textarea 属性。

基本用法

标签

标签应用来描述文本输入框。它们在视觉上使用，当用户聚焦到文本输入框时，屏幕阅读器也会朗读它们。这使得用户易于理解文本输入框的用途。Textarea 有几种分配标签的方式：

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

标签位置

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

标签插槽（实验性功能）

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

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

无可见标签

如果不需要可见标签，开发人员仍应提供 aria-label，以便屏幕阅读器可以访问文本输入框。

填充式文本输入框

Material Design 为文本输入框提供了填充样式。可以通过将项目的 fill 属性设置为 "solid" 或 "outline" 来使用。

在 iOS 上也可以通过将文本输入框的 mode 设置为 md 来使用填充式文本输入框。

注意

由于组件之间的样式冲突，使用 fill 的文本输入框不应在 ion-item 中使用。

辅助文本与错误文本

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

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

文本输入框计数器

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

自动增长

当 autoGrow 属性设置为 true 时，文本输入框将根据其内容自动增长和收缩。

编辑时清除

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

起始与结束插槽（实验性功能）

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

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

备注

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

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

主题

接口

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'

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

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 阴影部件

No CSS shadow parts available for this component.

CSS 自定义属性

iOS

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

MD

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