Skip to main content
Version: v7

ion-textarea

scoped

textareaコンポーネントは、複数行のテキスト入力に使用されます。ネイティブの textarea 要素は、コンポーネントの内部でレンダリングされます。ネイティブのtextareaを制御することで、textareaコンポーネントのユーザーエクスペリエンスとインタラクティブ性を向上させることができます。

ネイティブのtextarea要素とは異なり、Ionicのtextareaは要素内部のコンテンツからその値を読み込むことをサポートしていません。textareaの値はvalue属性で設定しなくてはなりません。

textareaコンポーネントはIonicのプロパティに加えて ネイティブのtextareaの属性 に対応します。

基本的な使い方

Labels

Labels should be used to describe the textarea. They can be used visually, and they will also be read out by screen readers when the user is focused on the textarea. This makes it easy for the user to understand the intent of the textarea. Textarea has several ways to assign a label:

  • label property: used for plaintext labels
  • label slot: used for custom HTML labels (experimental)
  • aria-label: used to provide a label for screen readers but adds no visible label

Label Placement

ラベルは、デフォルトでそのコンテンツの幅を占めます。 開発者は labelPlacement プロパティを使用して、ラベルがどのように配置されるかを制御することができます。

Label Slot (experimental)

While plaintext labels should be passed in via the label property, if custom HTML is needed, it can be passed through the label slot instead.

Note that this feature is considered experimental because it relies on a simulated version of Web Component slots. As a result, the simulated behavior may not exactly match the native slot behavior.

No Visible Label

If no visible label is needed, developers should still supply an aria-label so the textarea is accessible to screen readers.

Filled Textareas

Material Designでは、テキストエリアの塗りつぶしスタイルが用意されています。アイテムの fill プロパティは "solid" または "outline" のいずれかに設定することができます。

fill スタイルはテキストエリアのコンテナを視覚的に定義するため、fill を使用するテキストエリアは ion-item で使用すべきではありません。

Helper & Error Text

ヘルパーテキストとエラーテキストは、helperTexterrorText プロパティを使って textarea 内で使用することができます。エラーテキストは、ion-invalidion-touched クラスが ion-textarea に追加されていない限り表示されません。これにより、ユーザがデータを入力する前にエラーが表示されることはありません。

Angularでは、これはフォームバリデーションによって自動的に行われます。JavaScript、React、Vueでは、独自のバリデーションに基づいてクラスを手動で追加する必要があります。

Textarea Counter

textareaカウンターは、textareaの下に表示されるテキストで、textareaが受け付ける合計文字数のうち、何文字が入力されたかをユーザーに通知します。カウンターを追加する場合、デフォルトの動作は、表示される値を inputLength / maxLength としてフォーマットすることです。この動作は、counterFormatterプロパティにフォーマッタ関数を渡すことでカスタマイズすることができます。

Autogrow

autoGrowプロパティがtrueに設定されている場合、テキストエリアはその内容に基づいて拡大・縮小します。

Clear on Edit

clearOnEditプロパティをtrueに設定すると、テキストエリアが編集削除された後、再度入力されるとクリアされます。

レガシーtextarea構文からの移行

Ionic 7.0では、よりシンプルなtextareaの構文が導入されました。この新しい構文は、textareaを設定するために必要な定型文を減らし、アクセシビリティの問題を解決し、開発者の体験を向上させます。

開発者はこの移行を一度に1つのtextareaで行うことができます。開発者は従来の構文を使い続けることができますが、できるだけ早く移行することをお勧めします。

最新の構文の使い方

最新の構文を使うには、3つのステップがあります。

  1. ion-label を削除して、代わりに ion-textarealabel プロパティを使用します。ラベルの配置は ion-textarealabelPlacement プロパティを使用して設定することができる。
  2. テキストエリア固有のプロパティを ion-item から ion-textarea に移動します。これには、countercounterFormatterfillshapeプロパティが含まれます。
  3. ion-itemhelpererror スロットの使用を削除し、代わりに ion-textareahelperTexterrorText プロパティを使用します。
<!-- 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-textarealegacyプロパティをtrueに設定することで、そのインスタンスのtextareaがレガシー構文を使用するように強制できます。

テーマ

Interfaces

TextareaChangeEventDetail

interface TextareaChangeEventDetail {
value?: string | null;
}

TextareaCustomEvent

必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent インターフェースの代わりにこのインターフェースを使用することが可能です。

interface TextareaCustomEvent extends CustomEvent {
detail: TextareaChangeEventDetail;
target: HTMLIonTextareaElement;
}

プロパティ

autoGrow

Descriptiontrueの場合、textareaコンテナはtextareaの内容に応じて拡大・縮小します。
Attributeauto-grow
Typeboolean
Defaultfalse

autocapitalize

Descriptionテキスト値がユーザーによって入力/編集される際に、自動的に大文字にするかどうか、またどのようにするかについて示します。利用可能なオプションoff", "none", "on", "sentences", "words", "characters"`.
Attributeautocapitalize
Typestring
Default'none'

autofocus

Descriptionこの Boolean 属性により、ページロード時にフォームコントロールにInputフォーカスが当たるように指定することができます。
Attributeautofocus
Typeboolean
Defaultfalse

clearOnEdit

Descriptiontrue`の場合、編集時にフォーカスが当たった後、値がクリアされる。
Attributeclear-on-edit
Typeboolean
Defaultfalse

color

Descriptionアプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです。 "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", と "dark" です.色に関する詳しい情報は theming を参照してください。
Attributecolor
Type"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string & Record<never, never> | undefined
Defaultundefined

cols

Descriptionテキストコントロールの可視幅を、平均文字幅で指定します。指定する場合は、正の整数である必要があります。
Attributecols
Typenumber | undefined
Defaultundefined

counter

Descriptiontrueの場合、文字カウンタが使用された文字の比率と総文字数制限を表示します。カウンターを正しく計算するために、開発者は maxlength プロパティも設定する必要があります。
Attributecounter
Typeboolean
Defaultfalse

counterFormatter

Descriptionカウンターのテキストをフォーマットするために使用されるコールバックです。デフォルトでは、カウンターのテキストは"itemLength / maxLength"に設定されています。
Attributeundefined
Type((inputLength: number, maxLength: number) => string) | undefined
Defaultundefined

debounce

Descriptionキーを押すたびに ionInput イベントが発生するまでの待ち時間をミリ秒単位で設定します。
Attributedebounce
Typenumber | undefined
Defaultundefined

disabled

Descriptiontrueの場合、ユーザはテキストエリアと対話することができません。
Attributedisabled
Typeboolean
Defaultfalse

enterkeyhint

Descriptionどのエンターキーを表示するかのブラウザへのヒント。指定可能な値。enter", "done", "go", "next", "previous", "search", and "send"`.
Attributeenterkeyhint
Type"done" | "enter" | "go" | "next" | "previous" | "search" | "send" | undefined
Defaultundefined

errorText

Descriptionテキストエリアの下に配置され、エラーが検出されたときに表示されるテキストです。
Attributeerror-text
Typestring | undefined
Defaultundefined

fill

Descriptionアイテムの塗りつぶし。もし "solid" ならば、アイテムは背景を持つようになります。もし "outline" ならば、アイテムはボーダー付きの透明なものになります。md`モードでのみ使用可能です。
Attributefill
Type"outline" | "solid" | undefined
Defaultundefined

helperText

Descriptiontextareaの下に配置され、エラーが検出されなかった場合に表示されるテキストです。
Attributehelper-text
Typestring | undefined
Defaultundefined

inputmode

Descriptionどのキーボードを表示するかのブラウザへのヒント。指定可能な値。none", "text", "tel", "url", "email", "numeric", "decimal", and "search"`.
Attributeinputmode
Type"decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url" | undefined
Defaultundefined

label

Descriptionテキストエリアに関連する可視ラベル。
Attributelabel
Typestring | undefined
Defaultundefined

labelPlacement

Descriptionテキストエリアと相対的にラベルを配置する場所。"start":ラベルはLTRではテキストエリアの左側に、RTLでは右側に表示されます。"end":ラベルはLTRではテキストエリアの右側に、RTLでは左側に表示されます。"floating":ラベルは、テキストエリアにフォーカスが当たっているか、値がある場合、小さく表示され、テキストエリアの上に表示されます。それ以外の場合はtextareaの上に表示されます。"stacked":テキストエリアがぼやけた状態や値がない場合でも、ラベルは小さく表示され、テキストエリアの上に表示されます。固定":ラベルの幅が固定される以外は、"start"`と同じ動作になります。長いテキストは省略記号("...")で切り捨てられます。
Attributelabel-placement
Type"end" | "fixed" | "floating" | "stacked" | "start"
Default'start'

legacy

Descriptionlegacyプロパティをtrueに設定すると、レガシーフォームコントロールのマークアップを強制的に使用することができます。Ionicは、コンポーネントがaria-label属性またはラベルテキストを含むデフォルトスロットのいずれかを使用している場合にのみ、モダンフォームマークアップを選択するようになっています。そのため、legacyプロパティは、この自動オプトイン動作を回避したい場合にのみ、エスケープハッチとして使用する必要があります。なお、このプロパティはIonicの今後のメジャーリリースで削除され、すべてのフォームコンポーネントはモダンフォームマークアップを使用するようにオプトインされる予定です。
Attributelegacy
Typeboolean | undefined
Defaultundefined

maxlength

Descriptionこの属性は、ユーザが入力できる最大文字数を指定します。
Attributemaxlength
Typenumber | undefined
Defaultundefined

minlength

Descriptionこの属性は、ユーザーが入力できる最小の文字数を指定します。
Attributeminlength
Typenumber | undefined
Defaultundefined

mode

Descriptionmodeは、どのプラットフォームのスタイルを使用するかを決定します。
Attributemode
Type"ios" | "md"
Defaultundefined

name

Descriptionフォームデータとともに送信されるコントロールの名前。
Attributename
Typestring
Defaultthis.inputId

placeholder

Description入力が値を持つ前に表示される指示文。
Attributeplaceholder
Typestring | undefined
Defaultundefined

readonly

Descriptiontrueの場合、ユーザーは値を変更することができません。
Attributereadonly
Typeboolean
Defaultfalse

required

Descriptiontrueの場合、ユーザーはフォームを送信する前に値を入力する必要があります。
Attributerequired
Typeboolean
Defaultfalse

rows

Descriptionコントロールの可視テキスト行数。
Attributerows
Typenumber | undefined
Defaultundefined

shape

Descriptionテキストエリアの形状を指定します。round "の場合、ボーダーの半径が大きくなります。
Attributeshape
Type"round" | undefined
Defaultundefined

spellcheck

Descriptiontrueの場合、その要素のスペルチェックと文法チェックが行われる。
Attributespellcheck
Typeboolean
Defaultfalse

value

Descriptiontextareaの値です。
Attributevalue
Typenull | string | undefined
Default''

wrap

Descriptionコントロールがテキストをどのように折り返すかを示します。
Attributewrap
Type"hard" | "off" | "soft" | undefined
Defaultundefined

イベント

NameDescription
ionBlurInputのフォーカスが外れたときに発行されます。
ionChangeionChange イベントは <ion-textarea> 要素に対して、ユーザがその要素の値を変更したときに発生します。 ionInput イベントとは異なり、ionChange イベントは要素の値が変更されるたびに発生する必要はない。 値が変更された後、要素のフォーカスが外れると ionChange イベントが発生します。
ionFocusInputにフォーカスが当たったときに発行されます。
ionInputionInput イベントは、<ion-textarea> 要素の value が変更されたときに発生します。 clearOnEdit が有効な場合、ユーザがキーダウンイベントを実行してテキストエリアをクリアしたときに ionInput イベントが発生します。

メソッド

getInputElement

Description要素の内部で使用されるネイティブの <textarea> 要素を返します。
SignaturegetInputElement() => Promise<HTMLTextAreaElement>

setFocus

Descriptionion-textareaのネイティブtextareaにフォーカスを設定します。グローバルなtextarea.focus()` の代わりに、このメソッドを使用します。
SignaturesetFocus() => Promise<void>

CSS Shadow Parts

No CSS shadow parts available for this component.

CSSカスタムプロパティ

NameDescription
--backgroundtextareaの背景
--border-colorヘルパーテキスト、エラーテキスト、カウンターを使用する場合のテキストエリア下のボーダーの色
--border-radiusテキストエリアの境界半径
--border-styleヘルパーテキスト、エラーテキスト、カウンター使用時のテキストエリア下のボーダーのスタイル
--border-widthヘルパーテキスト、エラーテキスト、カウンターを使用する場合のテキストエリア下のボーダーの幅
--color本文の色
--highlight-color-focusedフォーカスされたときのテキストエリアのハイライトの色
--highlight-color-invalid無効時のテキストエリア上のハイライトの色
--highlight-color-valid有効時のテキストエリアのハイライトの色
--padding-bottomテキストエリアのBottom Padding
--padding-endテキストエリアの方向が左から右の場合はRight Padding、右から左の場合はLeft Paddingを使用します。
--padding-starttextareaの方向が左から右の場合はLeft Padding、右から左の場合はRight Padding。
--padding-toptextareaのTop Padding
--placeholder-colorPlaceholderテキストの色
--placeholder-font-stylePlaceholderテキストのスタイル
--placeholder-font-weightPlaceholderテキストの重さ
--placeholder-opacityPlaceholderテキストの不透明度

Slots

No slots available for this component.