本文へスキップ
バージョン: v8

ion-input

スコープ

入力コンポーネントは、カスタムスタイルと追加機能を備えたHTML入力要素のラッパーです。HTML入力と同じほとんどのプロパティを受け入れ、モバイルデバイスのキーボードと統合します。

基本的な使用方法

入力コンポーネントは、"text""password""email""number""search""tel""url"などのテキストタイプの入力のみを対象としています。keyupkeydownkeypressなど、すべての標準的なテキスト入力イベントをサポートします。デフォルトのtype"text"です。

ラベル

ラベルは、入力を説明するために使用します。視覚的に使用することもでき、ユーザーが入力にフォーカスしているときにスクリーンリーダーによって読み上げられます。これにより、ユーザーは入力の意図を簡単に理解できます。入力には、ラベルを割り当てるためのいくつかの方法があります。

  • labelプロパティ: プレーンテキストのラベルに使用します。
  • labelスロット: カスタムHTMLラベルに使用します(実験的)。
  • aria-label: スクリーンリーダーにラベルを提供しますが、目に見えるラベルは追加しません。

ラベルの位置

ラベルはデフォルトでコンテンツの幅を占めます。開発者はlabelPlacementプロパティを使用して、コントロールに対するラベルの位置を制御できます。

ラベルスロット(実験的)

プレーンテキストのラベルはlabelプロパティで渡すべきですが、カスタムHTMLが必要な場合は、代わりにlabelスロットで渡すことができます。

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

目に見えるラベルなし

目に見えるラベルが不要な場合でも、入力内容をスクリーンリーダーでアクセスできるようにするため、aria-labelを指定する必要があります。

クリアオプション

入力は、操作方法に基づいて入力をクリアするための2つのオプションを提供します。最初の方法は、clearInputプロパティを追加することです。これにより、入力にvalueがある場合にクリアボタンが表示されます。2番目の方法はclearOnEditプロパティで、入力がぼやけてから再度入力された後に入力をクリアします。type"password"に設定されている入力では、clearOnEditがデフォルトで有効になります。

塗りつぶされた入力

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

塗りつぶされた入力は、入力のmodemdに設定することでiOSで使用できます。

警告

fillを使用する入力は、コンポーネント間のスタイルの競合のため、ion-item内では使用しないでください。

ヘルプテキストとエラーテキスト

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

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

入力カウンター

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

ion-itemcounterプロパティとcounterFormatterプロパティは、Ionic 7で非推奨となり、代わりにion-inputで直接使用する必要があります。

カウンター付きの入力は、入力とカウンターの間にボーダーを追加するため、アイテムの下に追加のボーダーを追加するion-item内には配置しないでください。カウンター入力をアイテム内の入力と揃えるには、ion-padding-startクラスを追加できます。

ユーザー入力のフィルタリング

開発者は、ionInputイベントを使用して、keypressなどのユーザー入力に応じて入力値を更新できます。これは、無効な文字または不要な文字を除外する場合に役立ちます。

値を状態変数に保存する際には、状態変数とion-inputコンポーネントの値の両方を更新することをお勧めします。これにより、状態変数とion-inputコンポーネントの値が同期した状態を維持できます。

入力マスキング

入力マスクは、有効な入力値をサポートするために入力を制限する式です。Ionicでは、入力マスキングにMaskitoの使用を推奨します。Maskitoは、入力フィールドをマスキングするための軽量で依存関係のないライブラリです。電話番号、クレジットカード、日付など、幅広いマスクをサポートしています。

Maskitoを使い始めるには、ライブラリをインストールします。

npm install @maskito/core @maskito/{angular,react,vue}
注記

Maskitoのバグ報告はMaskitoのGithubリポジトリに提出してください。技術サポートについては、IonicフォーラムまたはIonic Discordをご利用ください。

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

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

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

注記

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

スロットコンテンツと対話する必要がある場合は、Buttonなどの対話型要素でラップする必要があります。これにより、コンテンツにタブで移動できるようになります。

テーマ

colorプロパティを設定すると、各入力の色パレットが変更されます。iosモードでは、このプロパティはキャレットの色を変更します。mdモードでは、このプロパティはキャレットの色とハイライト/下線の色を変更します。

注記

colorプロパティは、入力のテキストの色を変更しません。テキストの色を変更するには、--color CSSプロパティを使用してください。

CSSカスタムプロパティ

Inputはスコープされたカプセル化を使用しているため、実行時に各スタイルに追加のクラスを追加することでCSSを自動的にスコープします。CSSでスコープされたセレクターをオーバーライドするには、より高い特異性を持つセレクターが必要です。カスタマイズのためにion-inputをターゲットにしても機能しません。そのため、クラスを追加してカスタマイズすることをお勧めします。

従来の入力構文からの移行

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

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

最新の構文の使用

最新の構文を使用するには、3つの手順があります。

  1. ion-labelを削除し、代わりにion-inputlabelプロパティを使用します。ラベルの配置は、ion-inputlabelPlacementプロパティを使用して設定できます。
  2. ion-itemからion-inputに入力固有のプロパティを移動します。これには、countercounterFormatterfillshapeプロパティが含まれます。
  3. ion-itemhelperスロットとerrorスロットの使用を削除し、代わりにion-inputhelperTextプロパティとerrorTextプロパティを使用します。
<!-- Label and Label Position -->

<!-- Before -->
<ion-item>
<ion-label position="floating">Email:</ion-label>
<ion-input></ion-input>
</ion-item>

<!-- After -->
<ion-item>
<ion-input label="Email:" label-placement="floating"></ion-input>
</ion-item>


<!-- Fill -->

<!-- Before -->
<ion-item fill="outline" shape="round">
<ion-label position="floating">Email:</ion-label>
<ion-input></ion-input>
</ion-item>

<!-- After -->

<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-input fill="outline" shape="round" label="Email:" label-placement="floating"></ion-input>

<!-- Input-specific features on ion-item -->

<!-- Before -->
<ion-item counter="true">
<ion-label position="floating">Email:</ion-label>
<ion-input maxlength="100"></ion-input>
<div slot="helper">Enter an email</div>
<div slot="error">Please enter a valid email</div>
</ion-item>

<!-- After -->

<!--
Metadata such as counters and helper text should not
be used when an input is in an item/list. If you need to
provide more context on a input, consider using an ion-note
underneath the ion-list.
-->

<ion-input
label="Email:"
counter="true"
maxlength="100"
helper-text="Enter an email"
error-text="Please enter a valid email"
></ion-input>

従来の構文の使用

Ionicは、アプリが最新の入力構文を使用しているかどうかを検出するためのヒューリスティックを使用します。場合によっては、従来の構文を引き続き使用することが望ましい場合があります。開発者は、ion-inputlegacyプロパティをtrueに設定して、入力のそのインスタンスで従来の構文を使用するように強制できます。

インターフェース

InputChangeEventDetail

interface InputChangeEventDetail {
value: string | undefined | null;
}

InputCustomEvent

必須ではありませんが、このインターフェースをCustomEventインターフェースの代わりに使用して、このコンポーネントから送信されるIonicイベントの型付けを強化できます。

interface InputCustomEvent extends CustomEvent {
detail: InputChangeEventDetail;
target: HTMLIonInputElement;
}

プロパティ

autocapitalize

説明ユーザーが入力/編集する際に、テキスト値を自動的にどのように大文字にするかを指定します。使用可能なオプション:"off""none""on""sentences""words""characters"
属性autocapitalize
string
デフォルト'off'

autocomplete

説明コントロールの値をブラウザで自動的に補完できるかどうかを示します。
属性autocomplete
"name" | "email" | "tel" | "url" | "on" | "off" | "honorific-prefix" | "given-name" | "additional-name" | "family-name" | "honorific-suffix" | "nickname" | "username" | "new-password" | "current-password" | "one-time-code" | "organization-title" | "organization" | "street-address" | "address-line1" | "address-line2" | "address-line3" | "address-level4" | "address-level3" | "address-level2" | "address-level1" | "country" | "country-name" | "postal-code" | "cc-name" | "cc-given-name" | "cc-additional-name" | "cc-family-name" | "cc-number" | "cc-exp" | "cc-exp-month" | "cc-exp-year" | "cc-csc" | "cc-type" | "transaction-currency" | "transaction-amount" | "language" | "bday" | "bday-day" | "bday-month" | "bday-year" | "sex" | "tel-country-code" | "tel-national" | "tel-area-code" | "tel-local" | "tel-extension" | "impp" | "photo"
デフォルト'off'

autocorrect

説明ユーザーが入力/編集しているときに、自動修正を有効にするかどうか。
属性autocorrect
"off" | "on"
デフォルト'off'

autofocus

説明ネイティブ入力要素にautofocus属性を設定します。

ページロード時に要素にフォーカスするには、これだけでは不十分な場合があります。詳細については、フォーカスの管理を参照してください。
属性autofocus
boolean
デフォルトfalse

clearInput

説明trueの場合、値がある場合に入力にクリアアイコンが表示されます。クリックすると入力がクリアされます。
属性clear-input
boolean
デフォルトfalse

clearInputIcon

説明クリアボタンに使用するアイコン。clearInputtrueに設定されている場合にのみ適用されます。
属性clear-input-icon
string | undefined
デフォルトundefined

clearOnEdit

説明trueの場合、編集時にフォーカス後に値がクリアされます。type"password"の場合はtrue、その他の型の場合はfalseになります。
属性clear-on-edit
boolean | undefined
デフォルトundefined

color

説明アプリケーションの色パレットから使用する色。デフォルトのオプションは、"primary""secondary""tertiary""success""warning""danger""light""medium""dark"です。色の詳細については、テーマを参照してください。
属性color
"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | 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の場合、ユーザーは入力と対話できません。
属性disabled
boolean
デフォルトfalse

enterkeyhint

説明表示するEnterキーをブラウザにヒントします。可能な値:"enter""done""go""next""previous""search""send"
属性enterkeyhint
"done" | "enter" | "go" | "next" | "previous" | "search" | "send" | undefined
デフォルトundefined

errorText

説明エラーが検出されたときに、入力の下に配置され、表示されるテキスト。
属性error-text
string | undefined
デフォルトundefined

fill

説明アイテムの塗りつぶし。"solid"の場合、アイテムに背景があります。"outline"の場合、アイテムは透明でボーダーがあります。mdモードでのみ使用できます。
属性fill
"outline" | "solid" | undefined
デフォルトundefined

helperText

説明エラーが検出されないときに、入力の下に配置され、表示されるテキスト。
属性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

説明入力に関連付けられた表示されるラベル。

プレーンテキストのラベルをレンダリングする必要がある場合に使用します。

両方を使用する場合、labelプロパティはlabelスロットよりも優先されます。
属性label
string | undefined
デフォルトundefined

labelPlacement

説明入力欄に対するラベルの位置。"start": ラベルはLTRでは入力欄の左側に、RTLでは右側に表示されます。"end": ラベルはLTRでは入力欄の右側に、RTLでは左側に表示されます。"floating": 入力欄がフォーカスされているか値を持つ場合、ラベルは小さくなって入力欄の上に表示されます。それ以外の場合は、入力欄の上に重なって表示されます。"stacked": 入力欄がフォーカスされていないか値を持たない場合でも、ラベルは小さくなって入力欄の上に表示されます。"fixed": ラベルは"start"と同じ動作ですが、固定幅も持っています。長いテキストは省略記号("...")で切り詰められます。
属性label-placement
"end" | "fixed" | "floating" | "stacked" | "start"
デフォルト'start'

max

説明最大値。最小値(min属性)の値より小さくすることはできません。
属性max
数値 | 文字列 | 未定義
デフォルトundefined

maxlength

説明type属性の値がtextemailsearchpasswordtel、またはurlの場合、この属性はユーザーが入力できる最大文字数を指定します。
属性maxlength
number | undefined
デフォルトundefined

min

説明最小値。最大値(max属性)の値より大きくすることはできません。
属性min
数値 | 文字列 | 未定義
デフォルトundefined

minlength

説明type属性の値がtextemailsearchpasswordtel、またはurlの場合、この属性はユーザーが入力できる最小文字数を指定します。
属性minlength
number | undefined
デフォルトundefined

mode

説明modeは、使用するプラットフォームスタイルを決定します。
属性mode
"ios" | "md"
デフォルトundefined

multiple

説明trueの場合、ユーザーは複数の値を入力できます。この属性はtype属性が"email"に設定されている場合に適用され、それ以外の場合は無視されます。
属性multiple
boolean | undefined
デフォルトundefined

name

説明フォームデータと共に送信されるコントロールの名前。
属性name
string
デフォルトthis.inputId

pattern

説明値に対してチェックされる正規表現。パターンは部分集合ではなく、値全体と一致する必要があります。ユーザーを支援するために、title属性を使用してパターンを記述してください。この属性は、type属性の値が"text""search""tel""url""email""date"、または"password"の場合に適用され、それ以外の場合は無視されます。type属性が"date"の場合、patternは、ネイティブに"date"入力タイプをサポートしていないブラウザでのみ使用されます。詳細については、https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/dateを参照してください。
属性pattern
string | undefined
デフォルトundefined

placeholder

説明入力値がある前に表示される指示テキスト。このプロパティは、typeプロパティが"email""number""password""search""tel""text"、または"url"に設定されている場合にのみ適用され、それ以外の場合は無視されます。
属性placeholder
string | undefined
デフォルトundefined

readonly

説明trueの場合、ユーザーは値を変更できません。
属性readonly
boolean
デフォルトfalse

required

説明trueの場合、ユーザーはフォームを送信する前に値を入力する必要があります。
属性required
boolean
デフォルトfalse

shape

説明入力の形状。"round"の場合、ボーダーの半径が大きくなります。
属性shape
"round" | 未定義
デフォルトundefined

spellcheck

説明trueの場合、要素のスペルと文法がチェックされます。
属性spellcheck
boolean
デフォルトfalse

step

説明min属性とmax属性と連携して、値を設定できる増分を制限します。可能な値は"any"または正の浮動小数点数です。
属性step
string | undefined
デフォルトundefined

type

説明表示するコントロールの種類。デフォルトの種類はtextです。
属性type
"date" | "datetime-local" | "email" | "month" | "number" | "password" | "search" | "tel" | "text" | "time" | "url" | "week"
デフォルト'text'

value

説明入力の値。
属性value
null | 数値 | 文字列 | 未定義
デフォルト''

イベント

名前説明バブル
ionBlur入力がフォーカスを失ったときに発生します。true
ionChangeユーザーが入力値を変更したときにionChangeイベントが発生します。ionInputイベントとは異なり、ionChangeイベントは変更が確定された場合にのみ発生し、ユーザーが入力中に発生することはありません。

ユーザーが要素を操作する方法によっては、ionChangeイベントは異なるタイミングで発生します。 - ユーザーが明示的に変更を確定した場合(例:<ion-input type="date">の日付ピッカーから日付を選択した場合、"Enter"キーを押した場合など)。 - 値が変更された後に要素がフォーカスを失った場合:ユーザーの操作が入力である要素の場合。

このイベントは、プログラムによってvalueプロパティを設定した場合には発生しません。
true
ionFocus入力がフォーカスされたときに発生します。true
ionInputユーザーが入力値を変更するたびにionInputイベントが発生します。ionChangeイベントとは異なり、ionInputイベントは入力値の変更ごとに発生します。これは通常、ユーザーが入力するたびにキーストロークごとに発生します。

テキスト入力を受け入れる要素(type=texttype=telなど)の場合、インターフェースはInputEventです。それ以外の要素の場合、インターフェースはEventです。編集時に入力がクリアされた場合、型はnullです。
true

メソッド

getInputElement

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

setFocus

説明ion-input内のネイティブinputにフォーカスを設定します。グローバルなinput.focus()の代わりにこのメソッドを使用してください。

ページが表示されたときに入力をフォーカスしたい開発者は、ionViewDidEnter()ライフサイクルメソッドでsetFocus()を呼び出す必要があります。

オーバーレイが表示されたときに入力をフォーカスしたい開発者は、didPresentが解決された後にsetFocusを呼び出す必要があります。

詳細については、フォーカスの管理を参照してください。
シグネチャsetFocus() => Promise<void>

CSSシャドウパーツ

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

CSSカスタムプロパティ

名前説明
--background入力の背景
--border-colorヘルパーテキスト、エラーテキスト、またはカウンターを使用する場合の、入力の下のボーダーの色
--border-radius入力の半径。fill="outline"を使用する場合、大きな半径は不均一に表示される可能性があります。必要に応じて、代わりにshape="round"を使用するか、--padding-startを増やしてください。
--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入力の先頭に表示するコンテンツ。(実験的)