ion-textarea

スコープ

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 コンポーネントスロットのシミュレートされたバージョンに依存しているため、試験的と見なされています。そのため、シミュレートされた動作はネイティブのスロット動作と完全に一致しない場合があります。

表示ラベルなし

表示ラベルが不要な場合でも、開発者はスクリーンリーダーが textarea にアクセスできるように aria-label を指定する必要があります。

塗りつぶされた Textarea

マテリアルデザインでは、textarea に塗りつぶされたスタイルを提供しています。アイテムの fill プロパティは、"solid" または "outline" に設定できます。

塗りつぶされた textarea は、textarea の mode を md に設定することで iOS で使用できます。

警告

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 はぼかし後に再び入力されるとクリアされます。

開始スロットと終了スロット (試験的)

start スロットと end スロットを使用して、textarea の両側にアイコン、ボタン、またはプレフィックス/サフィックステキストを配置できます。

この機能は、Web コンポーネントスロットのシミュレートされたバージョンに依存しているため、試験的と見なされています。そのため、シミュレートされた動作はネイティブのスロット動作と完全に一致しない場合があります。

注記

ほとんどの場合、これらのスロットに配置されたアイコンコンポーネントは、aria-hidden="true" を持つ必要があります。詳細については、アイコンのアクセシビリティに関するドキュメントを参照してください。

スロットコンテンツを操作する場合は、ボタンなどのインタラクティブな要素でラップする必要があります。これにより、コンテンツにタブで移動できるようになります。

従来の Textarea 構文からの移行

Ionic 7.0 では、よりシンプルな textarea 構文が導入されました。この新しい構文により、textarea のセットアップに必要な定型コードが削減され、アクセシビリティの問題が解決され、開発エクスペリエンスが向上します。

開発者は、この移行を textarea ごとに実行できます。開発者は従来の構文を引き続き使用できますが、できるだけ早く移行することをお勧めします。

最新の構文の使用

最新の構文の使用には、3つの手順が含まれます。

1. ion-label を削除し、代わりに ion-textarea の label プロパティを使用します。ラベルの配置は、ion-textarea の labelPlacement プロパティを使用して構成できます。
2. ion-itemにあったtextarea特有のプロパティ（counter、counterFormatter、fill、shape）をion-textareaに移動しました。
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

必須ではありませんが、このインターフェースは、このコンポーネントから発行されるIonicイベントの型指定を強化するために、CustomEventインターフェースの代わりに使用できます。

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.dokyumento.jp/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
型	型 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

イベント

名前	説明	バブリング
ionBlur	入力がフォーカスを失ったときに発生します。	true
ionChange	ionChange イベントは、ユーザーがテキストエリアの値を変更したときに発生します。 ionInput イベントとは異なり、ionChange イベントは、要素が値の変更後にフォーカスを失ったときに発生します。 このイベントは、プログラムで value プロパティを設定しても発生しません。	true
ionFocus	入力がフォーカスされたときに発生します。	true
ionInput	ionInput イベントは、ユーザーがテキストエリアの値を変更するたびに発生します。 ionChange イベントとは異なり、ionInput イベントは、テキストエリアの値が変更されるたびに発生します。これは通常、ユーザーが入力するたびにキーストロークごとに発生します。 clearOnEdit が有効になっている場合、ユーザーがキーダウンイベントを実行してテキストエリアをクリアすると、ionInput イベントが発生します。	true

メソッド

getInputElement

説明	内部で使用されているネイティブの <textarea> 要素を返します。
シグネチャ	getInputElement() => Promise<HTMLTextAreaElement>

setFocus

説明	ion-textarea 内のネイティブ textarea にフォーカスを設定します。グローバルな textarea.focus() の代わりにこのメソッドを使用してください。 詳細はフォーカスの管理を参照してください。
シグネチャ	setFocus() => Promise<void>

CSSシャドウパーツ

このコンポーネントで使用できる CSS シャドウパーツはありません。

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	プレースホルダーテキストの不透明度

スロット

名前	説明
end	テキストエリアの末尾に表示するコンテンツ。(実験的)
属性 label	テキストエリアに関連付けるラベルテキスト。 labelPlacement プロパティを使用して、テキストエリアに対するラベルの配置を制御します。カスタム HTML でラベルをレンダリングする必要がある場合は、これを使用します。(実験的)
start	テキストエリアの先頭に表示するコンテンツ。(実験的)