ion-input
input コンポーネントは、HTML input 要素のラッパーで、カスタムスタイルと追加機能を備えています。HTML入力と同じプロパティのほとんどを受け入れ、モバイルデバイスのキーボードと統合します。
基本的な使い方
Types
input コンポーネントは、"text"
, "password"
, "email"
, "number"
, "search"
, "tel"
, "url"
などのテキストタイプの入力のみを対象としています。また、keyup
、keydown
、keypress
などの標準的なテキスト入力イベントをすべてサポートしています。デフォルトの type
は "text"
です。
Labels
ラベルは、入力を説明するために使用されるべきです。これらは視覚的に使用することができ、また、ユーザーが入力に集中しているときには、スクリーンリーダーによって読み上げられます。これにより、ユーザーは入力の意図を理解しやすくなる。Inputにはラベルを割り当てる方法がいくつかあります:
label
プロパティ:プレーンテキストのラベルに使用する。label
スロット: カスタム HTML ラベルに使用する(実験的)。aria-label
: スクリーンリーダー用のラベルとして使用されるが、ラベルは表示されない。
Label Placement
ラベルは、デフォルトでそのコンテンツの幅を占めます。 開発者は labelPlacement
プロパティを使用して、ラベルがどのように配置されるかを制御することができます。
Label Slot (実験的)
プレーンテキストのラベルは label
プロパティを通して渡されるべきですが、カスタム HTML が必要な場合は、代わりに label
スロットを通して渡すことができます。
この機能は、Web Component slots のシミュレート版に依存しているため、実験的なものとみなされていることに注意してください。その結果、シミュレートされた動作はネイティブのスロットの動作と完全に一致するとは限りません。
No Visible Label
表示するラベルが必要ない場合でも、開発者は aria-label
を指定する必要があります。
Clear Options
Inputsには、入力の操作方法に応じて、Inputをクリアするための2つのオプションがあります。最初の方法は clearInput
プロパティを追加することで、Inputに value
があるときにクリアボタンを表示します。2つ目の方法は clearOnEdit
プロパティで、入力が編集削除された後、再度入力されるとクリアされます。 type
が "password"
に設定されているInputは、デフォルトで clearOnEdit
が有効になっています。
Filled Inputs
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 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.
Filtering User Input
開発者は ionInput
イベントを使用して、キー入力などのユーザー入力に応答して入力値を更新することができます。これは、無効な文字や不要な文字をフィルタリングするのに便利です。
ステート変数に値を格納する場合、ステート変数と ion-input
コンポーネントの値の両方を更新することを推奨します。これにより、状態変数と ion-input
コンポーネントの値が確実に同期されます。
入力マスキング
入力マスキングは、有効な入力値をサポートするように入力を制約する式です。Ionicでは、入力マスキングにMaskitoを使うことを推奨しています。Maskitoは、入力フィールドをマスクするための軽量で依存関係のないライブラリです。電話番号、クレジットカード、日付など、幅広いマスクをサポートしています。
Maskitoを使い始めるには、ライブラリをインストールしてください:
npm install @maskito/core @maskito/{angular,react,vue}
Please submit bug reports with Maskito to the Maskito Github repository. For technical support, please use the Ionic Forum or Ionic Discord.
Start and End Slots (experimental)
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.
CSSカスタムプロパティ
Inputはscoped encapsulationを採用しており、実行時に各スタイルに追加のクラスを付加することで、CSSを自動的にスコープ化します。CSSでscopedセレクタを上書きするには、higher specificity セレクタが必要です。そのため、クラスを追加してカスタマイズすることをお勧めします。
レガシーな Input 構文からの移行
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
<!-- 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>
<!-- 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:" labelPlacement="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:" labelPlacement="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"
helperText="Enter an email"
errorText="Please enter a valid email"
></ion-input>
{/* Label and Label Position */}
{/* Before */}
<IonItem>
<IonLabel position="floating">Email:</IonLabel>
<IonInput></IonInput>
</IonItem>
{/* After */}
<IonItem>
<IonInput label="Email:" labelPlacement="floating"></IonInput>
</IonItem>
{/* Fill */}
{/* Before */}
<IonItem fill="outline" shape="round">
<IonLabel position="floating">Email:</IonLabel>
<IonInput></IonInput>
</IonItem>
{/* After */}
{/* Inputs using `fill` should not be placed in IonItem */}
<IonInput fill="outline" shape="round" label="Email:" labelPlacement="floating"></IonInput>
{/* Input-specific features on IonItem */}
{/* Before */}
<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>
{/* 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 IonNote
underneath the IonList.
*/}
<IonInput
label="Email:"
counter={true}
maxlength="100"
helperText="Enter an email"
errorText="Please enter a valid email"
></IonInput>
<!-- 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>