scoped
input コンポーネントは、HTML input 要素のラッパーで、カスタムスタイルと追加機能を備えています。HTML入力と同じプロパティのほとんどを受け入れ、モバイルデバイスのキーボードと統合します。
input コンポーネントは、"text"
, "password"
, "email"
, "number"
, "search"
, "tel"
, "url"
などのテキストタイプの入力のみを対象としています。また、keyup
、keydown
、keypress
などの標準的なテキスト入力イベントをすべてサポートしています。デフォルトの type
は "text"
です。
ラベルは、入力を説明するために使用されるべきです。これらは視覚的に使用することができ、また、ユーザーが入力に集中しているときには、スクリーンリーダーによって読み上げられます。これにより、ユーザーは入力の意図を理解しやすくなる。Inputにはラベルを割り当てる方法がいくつかあります:
label
プロパティ:プレーンテキストのラベルに使用する。
label
スロット: カスタム HTML ラベルに使用する(実験的)。
aria-label
: スクリーンリーダー用のラベルとして使用されるが、ラベルは表示されない。
ラベルは、デフォルトでそのコンテンツの幅を占めます。 開発者は labelPlacement
プロパティを使用して、ラベルがどのように配置されるかを制御することができます。
プレーンテキストのラベルは label
プロパティを通して渡されるべきですが、カスタム HTML が必要な場合は、代わりに label
スロットを通して渡すことができます。
この機能は、Web Component slots のシミュレート版に依存しているため、実験的なものとみなされていることに注意してください。その結果、シミュレートされた動作はネイティブのスロットの動作と完全に一致するとは限りません。
表示するラベルが必要ない場合でも、開発者は aria-label
を指定する必要があります。
Inputsには、入力の操作方法に応じて、Inputをクリアするための2つのオプションがあります。最初の方法は clearInput
プロパティを追加することで、Inputに value
があるときにクリアボタンを表示します。2つ目の方法は clearOnEdit
プロパティで、入力が編集削除された後、再度入力されるとクリアされます。 type
が "password"
に設定されているInputは、デフォルトで clearOnEdit
が有効になっています。
Material Design では、Inputに塗りつぶしのスタイルが用意されています。Inputの fill
プロパティは "solid"
または "outline"
のいずれかに設定することができます。
Filled inputs をiOSで使うためには、inputの mode
を md
に設定する必要があります。
Inputs that use fill
should not be used in an ion-item
due to styling conflicts between the components.
Helper & Error Text
ヘルパーテキストとエラーテキストは、helperText
と errorText
プロパティを使用して入力の内部で使用することができます。エラーテキストは、 ion-invalid
クラスと ion-touched
クラスが ion-input
に追加されていない限り表示されない。これにより、ユーザがデータを入力する前にエラーが表示されることはありません。
Angularでは、これはフォームバリデーションによって自動的に行われます。JavaScript、React、Vueでは、独自のバリデーションに基づいてクラスを手動で追加する必要があります。
Input Counterは、Inputの下に表示されるテキストで、入力可能な文字数のうち、何文字が入力されたかをユーザーに通知するものです。カウンターを追加する場合、デフォルトの動作は、表示される値を inputLength
/ maxLength
としてフォーマットすることです。この動作は、counterFormatter
プロパティにフォーマッタ関数を渡すことでカスタマイズすることができます。
The counter
and counterFormatter
properties on ion-item
were deprecated in Ionic 7 and should be used directly on ion-input
instead.
Inputs with a counter add a border between the input and the counter, therefore they should not be placed inside of an ion-item
which adds an additional border under the item. The ion-padding-start
class can be added to align the counter inputs with inputs inside of items.
開発者は ionInput
イベントを使用して、キー入力などのユーザー入力に応答して入力値を更新することができます。これは、無効な文字や不要な文字をフィルタリングするのに便利です。
ステート変数に値を格納する場合、ステート変数と ion-input
コンポーネントの値の両方を更新することを推奨します。これにより、状態変数と ion-input
コンポーネントの値が確実に同期されます。
入力マスキングは、有効な入力値をサポートするように入力を制約する式です。Ionicでは、入力マスキングにMaskitoを使うことを推奨しています。Maskitoは、入力フィールドをマスクするための軽量で依存関係のないライブラリです。電話番号、クレジットカード、日付など、幅広いマスクをサポートしています。
Maskitoを使い始めるには、ライブラリをインストールしてください:
npm install @maskito/core @maskito/{angular,react,vue}
start
スロットと end
スロットはInputの両側にアイコン、ボタン、接頭辞/接尾辞テキストを配置するために使用することができます。
この機能は Web Component slots のシミュレート版に依存しているため、実験的なものであることに注意してください。そのため、シミュレートされた動作はネイティブのスロットの動作と完全に一致するとは限りません。
In most cases, Icon components placed in these slots should have aria-hidden="true"
. See the Icon accessibility docs for more information.
If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a Button. This ensures that the content can be tabbed to.
color
プロパティを設定すると、各Inputのカラーパレットが変更されます。 ios
モードでは、このプロパティはキャレットカラーを変更します。 md
モードでは、このプロパティはキャレットカラーとハイライト/アンダーラインカラーを変更します。
The color
property does not change the text color of the input. For that, use the --color
CSS property.
Inputはscoped encapsulationを採用しており、実行時に各スタイルに追加のクラスを付加することで、CSSを自動的にスコープ化します。CSSでscopedセレクタを上書きするには、higher specificity セレクタが必要です。そのため、クラスを追加してカスタマイズすることをお勧めします。
Ionic 7.0では、よりシンプルなInput構文が導入されました。この新しい構文は、Inputのセットアップに必要な定型文を減らし、アクセシビリティの問題を解決し、開発者のエクスペリエンスを向上させます。
開発者は、この移行を一度に1つのInputで実行できます。開発者はレガシー構文を使い続けることができますが、できるだけ早く移行することをお勧めします。
最新の構文を使うには、3つのステップがあります。
ion-label
を削除して、代わりに ion-input
の label
プロパティを使用します。ラベルの配置は ion-input
の labelPlacement
プロパティで設定することができる。
- Input固有のプロパティを
ion-item
から ion-input
に移動します。これには、counter
、counterFormatter
、fill
、shape
プロパティが含まれる。
ion-item
の helper
と error
スロットの使用を削除し、代わりに ion-input
の helperText
と errorText
プロパティを使用します。
- JavaScript
- Angular
- React
- Vue
<ion-item>
<ion-label position="floating">Email:</ion-label>
<ion-input></ion-input>
</ion-item>
<ion-item>
<ion-input label="Email:" label-placement="floating"></ion-input>
</ion-item>
<ion-item fill="outline" shape="round">
<ion-label position="floating">Email:</ion-label>
<ion-input></ion-input>
</ion-item>
<ion-input fill="outline" shape="round" label="Email:" label-placement="floating"></ion-input>
<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>
<ion-input
label="Email:"
counter="true"
maxlength="100"
helper-text="Enter an email"
error-text="Please enter a valid email"
></ion-input>
<ion-item>
<ion-label position="floating">Email:</ion-label>
<ion-input></ion-input>
</ion-item>
<ion-item>
<ion-input label="Email:" labelPlacement="floating"></ion-input>
</ion-item>
<ion-item fill="outline" shape="round">
<ion-label position="floating">Email:</ion-label>
<ion-input></ion-input>
</ion-item>
<ion-input fill="outline" shape="round" label="Email:" labelPlacement="floating"></ion-input>
<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>
<ion-input
label="Email:"
[counter]="true"
maxlength="100"
helperText="Enter an email"
errorText="Please enter a valid email"
></ion-input>
{}
{}
<IonItem>
<IonLabel position="floating">Email:</IonLabel>
<IonInput></IonInput>
</IonItem>
{}
<IonItem>
<IonInput label="Email:" labelPlacement="floating"></IonInput>
</IonItem>
{}
{}
<IonItem fill="outline" shape="round">
<IonLabel position="floating">Email:</IonLabel>
<IonInput></IonInput>
</IonItem>
{}
{}
<IonInput fill="outline" shape="round" label="Email:" labelPlacement="floating"></IonInput>
{}
{}
<IonItem counter={true}>
<IonLabel position="floating">Email:</IonLabel>
<IonInput maxlength="100"></IonInput>
<div slot="helper">Enter an email</div>
<div slot="error">Please enter a valid email</div>
</IonItem>
{}
{
}
<IonInput
label="Email:"
counter={true}
maxlength="100"
helperText="Enter an email"
errorText="Please enter a valid email"
></IonInput>
<ion-item>
<ion-label position="floating">Email:</ion-label>
<ion-input></ion-input>
</ion-item>
<ion-item>
<ion-input label="Email:" label-placement="floating"></ion-input>
</ion-item>
<ion-item fill="outline" shape="round">
<ion-label position="floating">Email:</ion-label>
<ion-input></ion-input>
</ion-item>
<ion-input fill="outline" shape="round" label="Email:" label-placement="floating"></ion-input>
<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>
<ion-input
label="Email:"
:counter="true"
maxlength="100"
helper-text="Enter an email"
error-text="Please enter a valid email"
></ion-input>
Ionicは、アプリが最新のInput構文を使用しているかどうかをヒューリスティックに検出します。場合によっては、レガシーな構文を使い続けることが望ましいこともあります。開発者は、ion-input
のlegacy
プロパティをtrue
に設定することで、そのInputのインスタンスにレガシー構文を使用するように強制できます。
interface InputChangeEventDetail {
value: string | undefined | null;
}
必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent
インターフェースの代わりにこのインターフェースを使用することが可能です。
interface InputCustomEvent extends CustomEvent {
detail: InputChangeEventDetail;
target: HTMLIonInputElement;
}
Description | テキスト値がユーザーによって入力/編集される際に、自動的に大文字にするかどうか、またどのようにするかについて示します。利用可能なオプションoff", "none", "on", "sentences", "words", "characters"`. |
Attribute | autocapitalize |
Type | string |
Default | 'off' |
Description | コントロールの値が、ブラウザによって自動的に補完されるかどうかを示します。 |
Attribute | autocomplete |
Type | "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" |
Default | 'off' |
Description | ユーザーがテキスト値を入力/編集する際に、自動補正を有効にするかどうか。 |
Attribute | autocorrect |
Type | "off" | "on" |
Default | 'off' |
Description | ネイティブの入力要素に autofocus 属性 を設定します。 ページロード時に要素がフォーカスされるには、これだけでは不十分かもしれません。詳しくはmanaging focusを参照してください。 |
Attribute | autofocus |
Type | boolean |
Default | false |
Description | true の場合、値があるときにInputにクリアアイコンが表示されます。これをクリックすると、入力がクリアされます。 |
Attribute | clear-input |
Type | boolean |
Default | false |
Description | true の場合、編集時にフォーカスされた後、値がクリアされる。デフォルトは type が "password" のとき true で、それ以外のときは false です。 |
Attribute | clear-on-edit |
Type | boolean | undefined |
Default | undefined |
Description | アプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです。 "primary" , "secondary" , "tertiary" , "success" , "warning" , "danger" , "light" , "medium" , と "dark" です.色に関する詳しい情報は theming を参照してください。 |
Attribute | color |
Type | "danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | undefined |
Default | undefined |
Description | true の場合、文字カウンタが使用された文字の比率と総文字数制限を表示します。カウンターを正しく計算するために、開発者は maxlength プロパティも設定する必要があります。 |
Attribute | counter |
Type | boolean |
Default | false |
Description | キーを押すたびに ionInput イベントが発生するまでの待ち時間をミリ秒単位で設定します。 |
Attribute | debounce |
Type | number | undefined |
Default | undefined |
Description | true の場合、ユーザはInputと対話することができません。 |
Attribute | disabled |
Type | boolean |
Default | false |
Description | どのエンターキーを表示するかのブラウザへのヒント。指定可能な値。enter", "done", "go", "next", "previous", "search", and "send"`. |
Attribute | enterkeyhint |
Type | "done" | "enter" | "go" | "next" | "previous" | "search" | "send" | undefined |
Default | undefined |
errorText
Description | Inputの下に配置され、エラーが検出されたときに表示されるテキストです。 |
Attribute | error-text |
Type | string | undefined |
Default | undefined |
Description | アイテムの塗りつぶし。もし "solid" ならば、アイテムは背景を持つようになります。もし "outline" ならば、アイテムはボーダー付きの透明なものになります。md`モードでのみ使用可能です。 |
Attribute | fill |
Type | "outline" | "solid" | undefined |
Default | undefined |
helperText
Description | Inputの下に配置され、エラーが検出されなかった場合に表示されるテキストです。 |
Attribute | helper-text |
Type | string | undefined |
Default | undefined |
Description | どのキーボードを表示するかのブラウザへのヒント。指定可能な値。none", "text", "tel", "url", "email", "numeric", "decimal", and "search"`. |
Attribute | inputmode |
Type | "decimal" | "email" | "none" | "numeric" | "search" | "tel" | "text" | "url" | undefined |
Default | undefined |
Description | 入力に関連付けられた可視ラベル。 プレーンテキストのラベルをレンダリングする必要がある場合に使用する。 両方が使用されている場合、label プロパティが label スロットよりも優先される。 |
Attribute | label |
Type | string | undefined |
Default | undefined |
Description | 入力に対してラベルを配置する位置。"start" :ラベルはLTRでは入力の左側に、RTLでは右側に表示されます。"end" :ラベルはLTRでは入力の右側、RTLでは左側に表示されます。"floating": "floating":ラベルは、入力にフォーカスが当たっているときや、入力に値があるときは小さく表示され、入力の上に表示されます。それ以外の場合は、入力の上に表示されます。 "スタック(stacked)":入力がぼやけた状態や値がない場合でも、ラベルは小さく表示され、入力の上に表示されます。 "fixed":ラベルの幅が固定される以外は、 "start"`と同じ動作になります。長いテキストは省略記号("...")で切り捨てられます。 |
Attribute | label-placement |
Type | "end" | "fixed" | "floating" | "stacked" | "start" |
Default | 'start' |
Description | 最大値で、その最小値(min属性)より小さくてはなりません。 |
Attribute | max |
Type | number | string | undefined |
Default | undefined |
Description | type属性の値が text , email , search , password , tel , または url の場合、この属性はユーザーが入力できる最大文字数を指定します。 |
Attribute | maxlength |
Type | number | undefined |
Default | undefined |
Description | 最小値で、その最大値(max属性)より大きくてはなりません。 |
Attribute | min |
Type | number | string | undefined |
Default | undefined |
Description | type属性の値が text , email , search , password , tel , または url の場合、この属性はユーザーが入力できる最小文字数を指定します。 |
Attribute | minlength |
Type | number | undefined |
Default | undefined |
Description | modeは、どのプラットフォームのスタイルを使用するかを決定します。 |
Attribute | mode |
Type | "ios" | "md" |
Default | undefined |
Description | true の場合、ユーザは複数の値を入力することができる。この属性は、type属性が "email" に設定されている場合に適用され、それ以外の場合は無視される 。 |
Attribute | multiple |
Type | boolean | undefined |
Default | undefined |
Description | フォームデータとともに送信されるコントロールの名前。 |
Attribute | name |
Type | string |
Default | this.inputId |
Description | 値をチェックするための正規表現。パターンは、部分的なものだけでなく、値全体にマッチする必要があります。title 属性を使って、ユーザーを助けるためにパターンを説明します。この属性は、type属性の値が "text" , "search" , "tel" , "url" , "email" , "date" , または "password" であるときに適用され、それ以外のときは無視されます。type 属性が "date" の場合、pattern は "date" Inputタイプをネイティブにサポートしないブラウザでのみ使用されます。詳しくは https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date を参照してください。 |
Attribute | pattern |
Type | string | undefined |
Default | undefined |
Description | Inputが値を持つ前に表示される指示テキスト。このプロパティは、type プロパティが "email" , "number" , "password" , "search" , "tel" , "text" , または "url" に設定されている場合にのみ適用され、それ以外は無視されます。 |
Attribute | placeholder |
Type | string | undefined |
Default | undefined |
Description | true の場合、ユーザーは値を変更することができません。 |
Attribute | readonly |
Type | boolean |
Default | false |
Description | true の場合、ユーザーはフォームを送信する前に値を入力する必要があります。 |
Attribute | required |
Type | boolean |
Default | false |
Description | 入力の形状を指定します。"round"の場合、境界線の半径が大きくなります。 |
Attribute | shape |
Type | "round" | undefined |
Default | undefined |
Description | true の場合、その要素のスペルチェックと文法チェックが行われる。 |
Attribute | spellcheck |
Type | boolean |
Default | false |
Description | min属性、max属性と連携して、値を設定する際の増分を制限することができます。設定可能な値は以下の通りです。any"`または正の浮動小数点数。 |
Attribute | step |
Type | string | undefined |
Default | undefined |
Description | 表示するコントロールの種類を指定します。デフォルトのタイプはテキストです。 |
Attribute | type |
Type | "date" | "datetime-local" | "email" | "month" | "number" | "password" | "search" | "tel" | "text" | "time" | "url" | "week" |
Default | 'text' |
Description | 入力された値です。 |
Attribute | value |
Type | null | number | string | undefined |
Default | '' |
Name | Description | Bubbles |
---|
ionBlur | Inputのフォーカスが外れたときに発行されます。 | true |
ionChange | ionChange イベントは、ユーザが入力値を変更したときに発生する。ionInput イベントとは異なり、ionChange イベントは変更がコミットされたときにのみ発生する。 ユーザが明示的に変更をコミットしたとき (例えば、<ion-input type="date"> の日付ピッカーから日付を選択したり、"Enter" キーを押したりしたときなど)。- 値が変更された後、要素がフォーカスを失ったとき: ユーザーのインタラクションがタイピングである要素の場合。 | true |
ionFocus | Inputにフォーカスが当たったときに発行されます。 | true |
ionInput | ionInput イベントは、ユーザが入力値を変更するたびに発生する。ionChange イベントとは異なり、 ionInput イベントは入力値が変更されるたびに発生する。これは通常、ユーザが入力を行うたびに発生します。 テキスト入力を受け付ける要素(type=text , type=tel など)の場合、インターフェイスはInputEvent となります。その他の要素の場合、インターフェイスはEvent となります。編集時に入力がクリアされる場合、型は null となる。 | true |
Description | 要素の内部で使用されているネイティブの <input> 要素を返します。 |
Signature | getInputElement() => Promise<HTMLInputElement> |
Description | ion-inputのネイティブ inputにフォーカスを設定する。グローバルな input.focus()の代わりにこのメソッドを使用する。 ページ入力時に入力にフォーカスを当てたい場合は、 ionViewDidEnter()ライフサイクルメソッド内で setFocus()を呼び出す必要がある。 オーバーレイが表示されたときに入力にフォーカスを当てたい開発者は、 didPresentが解決した後に setFocus` を呼び出してください。 詳細については、managing focusを参照してください。 |
Signature | setFocus() => Promise<void> |
No CSS shadow parts available for this component.
Name | Description |
---|
--background | Inputの背景 |
--border-color | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合のInput下のボーダーの色 |
--border-radius | 入力の半径。fill="outline "を使う場合、半径が大きいと表示が不 均一になることがある。 |
--border-style | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合の入力下のボーダーのスタイル |
--border-width | ヘルパーテキスト、エラーテキスト、カウンターを使用する場合の入力下のボーダーの幅 |
--color | Inputのテキストの色 |
--highlight-color-focused | フォーカスされたときの入力のハイライトの色 |
--highlight-color-invalid | 入力が無効な場合のハイライトの色 |
--highlight-color-valid | 有効時の入力のハイライトの色 |
--highlight-height | 入力のハイライトの高さ。md モードにのみ適用される。 |
--padding-bottom | InputのBottom Padding |
--padding-end | 入力の方向が左から右の場合はRight Padding、右から左の場合はLeft Paddingとなります。 |
--padding-start | 入力の方向が左から右の場合はLeft Padding、右から左の場合はRight Paddingとなります。 |
--padding-top | InputのTop Padding |
--placeholder-color | InputのPlaceholderテキストの色 |
--placeholder-font-style | InputのPlaceholderテキストのFont Style |
--placeholder-font-weight | InputのPlaceholderテキストのFont Weight |
--placeholder-opacity | InputのPlaceholderテキストの不透明度 |
Name | Description |
---|
end | 入力の後端に表示する内容。(実験的) |
label | 入力に関連付けるラベルテキスト。labelPlacement`プロパティを使用すると、入力に対してラベルを配置する位置を制御することができる。ラベルをカスタム HTML でレンダリングする必要がある場合に使用します。(EXPERIMENTAL) |
start | 入力の最先端に表示するコンテンツ。(実験的) |