ion-textarea

scoped

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 Component 插槽的模擬版本。因此，模擬行為可能與原生插槽行為不完全一致。

無可見標籤

如果不需要可見標籤，開發人員仍應提供 aria-label，以便螢幕閱讀器可以存取 textarea。

已填寫的 Textarea

Material Design 為 textarea 提供已填寫的樣式。項目的 fill 屬性可以設定為 "solid" 或 "outline"。

可以透過將 textarea 的 mode 設定為 md，在 iOS 上使用已填寫的 textarea。

警告

使用 fill 的 Textarea 不應在 ion-item 中使用，因為元件之間存在樣式衝突。

輔助和錯誤文字

可以使用 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 模糊化，然後再次輸入時清除 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. 將 ion-item 上的 textarea 特定屬性移至 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.dev.org.tw/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"：標籤在 LTR 中將顯示在 textarea 的左側，在 RTL 中將顯示在右側。"end"：標籤在 LTR 中將顯示在 textarea 的右側，在 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 Shadow Parts

此元件沒有可用的 CSS shadow parts。

CSS 自訂屬性

iOS

名稱	描述
--background	文字區域的背景
--border-color	當使用輔助文字、錯誤文字或計數器時，文字區域下方邊框的顏色
--border-radius	文字區域的邊框半徑
--border-style	當使用輔助文字、錯誤文字或計數器時，文字區域下方邊框的樣式
--border-width	當使用輔助文字、錯誤文字或計數器時，文字區域下方邊框的寬度
--color	文字的顏色
--highlight-color-focused	當文字區域被聚焦時，高亮顯示的顏色
--highlight-color-invalid	當文字區域無效時，高亮顯示的顏色
--highlight-color-valid	當文字區域有效時，高亮顯示的顏色
--highlight-height	文字區域高亮顯示的高度。僅適用於 md 模式。
--padding-bottom	文字區域的底部內距
--padding-end	如果方向是從左到右，則為文字區域的右側內距；如果方向是從右到左，則為文字區域的左側內距
--padding-start	如果方向是從左到右，則為文字區域的左側內距；如果方向是從右到左，則為文字區域的右側內距
--padding-top	文字區域的頂部內距
--placeholder-color	占位符文字的顏色
--placeholder-font-style	占位符文字的樣式
--placeholder-font-weight	占位符文字的粗細
--placeholder-opacity	占位符文字的不透明度

MD

名稱	描述
--background	文字區域的背景
--border-color	當使用輔助文字、錯誤文字或計數器時，文字區域下方邊框的顏色
--border-radius	文字區域的邊框半徑
--border-style	當使用輔助文字、錯誤文字或計數器時，文字區域下方邊框的樣式
--border-width	當使用輔助文字、錯誤文字或計數器時，文字區域下方邊框的寬度
--color	文字的顏色
--highlight-color-focused	當文字區域被聚焦時，高亮顯示的顏色
--highlight-color-invalid	當文字區域無效時，高亮顯示的顏色
--highlight-color-valid	當文字區域有效時，高亮顯示的顏色
--highlight-height	文字區域高亮顯示的高度。僅適用於 md 模式。
--padding-bottom	文字區域的底部內距
--padding-end	如果方向是從左到右，則為文字區域的右側內距；如果方向是從右到左，則為文字區域的左側內距
--padding-start	如果方向是從左到右，則為文字區域的左側內距；如果方向是從右到左，則為文字區域的右側內距
--padding-top	文字區域的頂部內距
--placeholder-color	占位符文字的顏色
--placeholder-font-style	占位符文字的樣式
--placeholder-font-weight	占位符文字的粗細
--placeholder-opacity	占位符文字的不透明度

插槽 (Slots)

名稱	描述
end	顯示在文字區域尾端的內容。(實驗性)
label	要與文字區域關聯的標籤文字。使用 labelPlacement 屬性來控制標籤相對於文字區域的位置。如果您需要使用自訂 HTML 呈現標籤，請使用此選項。(實驗性)
start	顯示在文字區域前端的內容。(實驗性)