ion-select
セレクトは、一連のオプションから1つまたは複数のオプションを選択するためのフォームコントロールです。ユーザーがセレクトをタップすると、ダイアログが表示され、すべてのオプションが大きく選択しやすいリストに表示されます。
selectは、子要素 <ion-select-option> とともに使用する必要があります。子要素のオプションにvalue属性が指定されていない場合、そのtextが値として使用されます。
value が <ion-select> にセットされている場合、オプションはその値に基づいて選択済みになります。
Labels
ラベルは、Selectを説明するために使用します。これらは視覚的に使用することができ、また、ユーザーがSelectにフォーカスしているときには、スクリーンリーダーによって読み上げられます。これにより、ユーザーはSelectの意図を理解しやすくなります。セレクトには、ラベルを割り当てるいくつかの方法があります：
セレクトには、コンポーネントにラベルを指定するためのいくつかのオプションがあります：
labelプロパティ：プレーンテキストのラベルに使用します。labelスロット：カスタム HTML ラベルに使用する。aria-label：スクリーンリーダー用のラベルとして使用されるが、ラベルは表示されない。
Label Placement
ラベルはデフォルトではコンテンツの幅を占めます。開発者は labelPlacement プロパティを使用して、コントロールに対するラベルの配置を制御することができます。ここでは label プロパティを使用しているが、labelPlacement は label スロットと一緒に使用することもできます。
Label Slot
プレーンテキストのラベルは label プロパティで渡すべきですが、カスタムHTMLが必要な場合は、代わりに label スロットで渡すことができます。
No Visible Label
表示するラベルが必要ない場合でも、開発者はaria-labelを指定する必要があります
Single Selection
デフォルトでは、selectを使用すると、ユーザは1つのOptionだけを選択できます。Alertのインターフェースでは、Optionのリストがradio button形式で表示されます。action sheetインタフェースは、1つの値選択でのみ使用できます。selectコンポーネントの値は、選択したオプションの値の値を受け取ります。
単一選択時のキーボード操作については、以下のキーボード操作のセクションで説明しています。
複数選択
select に multiple 属性を追加することで、ユーザーは複数のオプションを選択することができます。複数のオプションが選択可能な場合、アラートやポップオーバーはチェックボックス形式のオプションリストをユーザに提示します。select コンポーネントの値は、選択されたすべてのオプション値の配列を受け取ります。
注意: action-sheet インターフェースは複数選択では動作しません。
複数選択時のキーボード操作については、以下のキーボード操作のセクションで説明しています。
インターフェイス
デフォルトでは、select は ion-alert を使ってAlertのオプションのオーバーレイを開きます。インターフェイスを変更して、ion-action-sheet または ion-popover を使用するには、 action-sheet または popover を interface プロパティに渡します。各インタフェースの制限については、他のセクションを参照してください。
Alert
Action Sheet
Popover
インタラクションの処理
Select とユーザのインタラクションを処理する主な方法は、 ionChange イベント、 ionDismiss イベント、 ionCancel イベントです。これらのイベントやselectが発生するその他のイベントの詳細については、Eventsを参照してください。
ConsoleConsole messages will appear here when logged from the example above.オブジェクト値の参照
Selectの値にオブジェクトを使用する場合、Selectの値のidentityはそのままで、サーバやデータベースから取得したオブジェクトのidentityが変わってしまうことがあります。例えば、希望するオブジェクト値を持つ既存のレコードがSelectに読み込まれたが、新しく取得されたselectオプションのIDが異なる場合、このようなことが起こりえます。その結果、Selectは、元のSelectがそのまま残っているにもかかわらず、全く値がないように見えることになります。
デフォルトでは、Selectはオブジェクトの等質性(===)を使用してオプションが選択されているかどうかを判断します。これは compareWith プロパティにプロパティ名または関数を指定することでオーバーライドすることができます。
Using compareWith
ConsoleConsole messages will appear here when logged from the example above.Object Values and Multiple Selection
ConsoleConsole messages will appear here when logged from the example above.Justification
開発者は justify プロパティを使用して、ラベルとコントロールの行の詰め方を制御することができます。
Filled Selects
Material DesignはセレクトにFilledスタイルを提供します。select の fill プロパティは "solid" または "outline" のいずれかに設定できます。
fill スタイルはセレクトコンテナを視覚的に定義するので、fill を使用するセレクトは ion-item では使用しないでください。
Select Buttons
アラートは Cancel と OK の2つのボタンをサポートしている。それぞれのボタンのテキストは cancelText と okText プロパティを使ってカスタマイズすることができます。
action-sheet と popover インターフェースには OK ボタンがありません。オプションのいずれかをクリックすると自動的にオーバーレイが閉じ、その値が選択されます。 popover インターフェースには Cancel ボタンがなく、背景をクリックするとオーバーレイが閉じます。
インターフェイスオプション
Selectはalert、action sheet、popoverインタフェースを使用するので、interfaceOptionsプロパティを通してこれらのコンポーネントにオプションを渡すことができます。これを使用して、カスタムヘッダ、サブヘッダ、CSS クラスなどを渡すことができます。
各インタフェースが受け付けるプロパティについては、ion-alert docs, ion-action-sheet docs, ion-popover docs を参照してください。
注意: alert インターフェイスでは、interfaceOptions は inputs や buttons を上書きしません。
カスタマイズ
Selectコンポーネントには2つのユニットがあり、それぞれ別々にスタイルを設定する必要があります。 ion-select要素は、ビュー上で選択された値、ない場合はプレースホルダ、ドロップダウンのアイコンによって表現されます。インターフェイスは上記のインターフェイスセクションで定義されており、ion-selectをクリックしたときに開くダイアログです。インターフェイスには ion-select-option 要素を追加することで定義されるすべてのオプションが含まれています。以下のセクションでは、これらのスタイリングの違いについて説明します。
Select要素のスタイリング
前述の通り、ion-select要素は値、プレースホルダ、ビューに表示されるアイコンのみで構成されています。これをカスタマイズするには、CSSとCSSカスタムプロパティを組み合わせてスタイルを設定します。
また、必要なブラウザサポートによっては、CSSのシャドウパーツを使用してセレクトのスタイルを設定することもできます。 part を使用することで、要素上の任意の CSS プロパティを対象とすることができることに注意してください。
セレクトインターフェースのスタイリング
インターフェイスのダイアログをカスタマイズするには、そのインターフェイスのドキュメントのカスタマイズのセクションに従ってください：
しかし、セレクト・オプションは、スタイルを簡単にするためにクラスを設定し、オーバーレイ・オプションにクラスを渡すことができます。オプションをカスタマイズする使用例については、セレクト・オプションのドキュメントを参照してください。
Custom Toggle Icons
選択テキストの隣に表示されるアイコンは、toggleIcon プロパティと expandedIcon プロパティを使用して、任意の Ionicon に設定することができます。
アイコンの反転動作
デフォルトでは、セレクトを開いているとき、トグルアイコンは md モードでは自動的に回転し、ios モードでは静止します。この動作はCSSを使ってカスタマイズすることができます。
以下の例ではcustom toggleIconを使って、iosモードでのトグルアイコンの反転動作をより分かりやすく説明しています。
Typeahead Component
Typeaheadまたはオートコンプリート機能は、既存のIonicコンポーネントを使用して構築できます。利用可能なスクリーンスペースを最大限に活用するために、ion-modalを使用することをお勧めします。
Interfaces
SelectChangeEventDetail
interface SelectChangeEventDetail<T = any> {
value: T;
}
SelectCustomEvent
必須ではありませんが、このインターフェイスを CustomEvent インターフェイスの代わりに使用することで、このコンポーネントから発行される Ionic イベントをより強力に片付けすることができます。
interface SelectCustomEvent<T = any> extends CustomEvent {
detail: SelectChangeEventDetail<T>;
target: HTMLIonSelectElement;
}
従来のセレクト構文からの移行
Ionic 7.0では、よりシンプルなセレクト構文が導入されました。この新しい構文は、セレクトのセットアップに必要な定型文を減らし、アクセシビリティの問題を解決し、開発者のエクスペリエンスを向上させます。
開発者はこの移行をセレクトごとに行うことができます。開発者は従来の構文を使い続けることもできますが、できるだけ早く移行することをお勧めします。
最新構文の使用
最新の構文を使用するには、2つのステップがあります：
ion-labelを削除し、代わりにion-selectのlabelプロパティを使用する。ラベルの配置はion-selectのlabelPlacementプロパティで設定できる。
- fill
とshapeをion-itemからion-select` に移動する。
- JavaScript
- Angular
- React
- Vue
<!-- Label and Label Position -->
<!-- Before -->
<ion-item>
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<ion-item>
<ion-select label="Favorite Fruit:" label-placement="floating">...</ion-select>
</ion-item>
<!-- Fill -->
<!-- Before -->
<ion-item fill="outline" shape="round">
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" label-placement="floating">...</ion-select>
<!-- Label and Label Position -->
<!-- Before -->
<ion-item>
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<ion-item>
<ion-select label="Favorite Fruit:" labelPlacement="floating">...</ion-select>
</ion-item>
<!-- Fill -->
<!-- Before -->
<ion-item fill="outline" shape="round">
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" labelPlacement="floating">...</ion-select>
{/* Label and Label Position */}
{/* Before */}
<IonItem>
<IonLabel position="floating">Favorite Fruit:</IonLabel>
<IonSelect>...</IonSelect>
</IonItem>
{/* After */}
<IonItem>
<IonSelect label="Favorite Fruit:" labelPlacement="floating">...</IonSelect>
</IonItem>
{/* Fill */}
{/* Before */}
<IonItem fill="outline" shape="round">
<IonLabel position="floating">Favorite Fruit:</IonLabel>
<IonSelect>...</IonSelect>
</IonItem>
{/* After */}
{/* Inputs using `fill` should not be placed in IonItem */}
<IonSelect fill="outline" shape="round" label="Favorite Fruit:" labelPlacement="floating">...</IonSelect>
<!-- Label and Label Position -->
<!-- Before -->
<ion-item>
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<ion-item>
<ion-select label="Favorite Fruit:" label-placement="floating">...</ion-select>
</ion-item>
<!-- Fill -->
<!-- Before -->
<ion-item fill="outline" shape="round">
<ion-label position="floating">Favorite Fruit:</ion-label>
<ion-select>...</ion-select>
</ion-item>
<!-- After -->
<!-- Inputs using `fill` should not be placed in ion-item -->
<ion-select fill="outline" shape="round" label="Favorite Fruit:" label-placement="floating">...</ion-select>
レガシー構文の使用
Ionicは、アプリがモダンなセレクト構文を使用しているかどうかをヒューリスティックで検出します。場合によっては、レガシー構文を使い続けた方が望ましいこともあります。開発者は ion-select の legacy プロパティを true に設定することで、その入力インスタンスにレガシー構文を使用させることができます。
Accessibility
Keyboard Interactions
Ionic's keyboard interactions follow the implementation patterns of the web instead of the native iOS select for a consistent experience across all platforms.
These keyboard interactions apply to all ion-select elements when the following conditions are met:
- The select is closed.
- The select is focused.
- The select is not disabled.
| Key | Description |
|---|---|
| Enter | Opens the overlay and focuses on the first selected option. If there is no selected option, then it focuses on the first option. |
| Space | Opens the overlay and focuses on the first selected option. If there is no selected option, then it focuses on the first option. |
Single Selection
Single selection keyboard interaction follows the ARIA implementation patterns of a radio.
These keyboard interactions apply to ion-action-sheet, ion-alert, and ion-popover elements when the overlay is presented and focused.
| Key | Description |
|---|---|
| ArrowDown | Focuses and selects the next option in the list. If there is no next option, selection will cycle to the first option. |
| ArrowLeft | Focuses and selects the previous option in the list. If there is no previous option, selection will cycle to the last option. |
| ArrowRight | Focuses and selects the next option in the list. If there is no next option, selection will cycle to the first option. |
| ArrowUp | Focuses and selects the previous option in the list. If there is no previous option, selection will cycle to the last option. |
| Enter | If an option is focused, it will select the option. Overlays without an 'OK' button will commit the value immediately, dismiss the overlay and return focus to the ion-select element.If the 'OK' button is focused, it will save the user's selection, dismiss the overlay and return focus to the ion-select element. |
| Escape | Closes the overlay without changing the submitted option. Returns the focus back to the ion-select element. |
| Space | If the focused radio button is not checked, unchecks the currently checked radio button and checks the focused radio button. Otherwise, does nothing. If the overlay does not have an 'OK' button, the value will be committed immediately and the overlay will dismiss. |
| Tab | Moves focus to the next focusable element (cancel button, 'OK' button, or either the selection or the first option) on the overlay. If the next focusable element is an option, then it will focus on the selected option, otherwise it will focus the first option. |
Multiple Selection
Multiple selection keyboard interaction follows the ARIA implementation patterns of a checkbox.
These keyboard interactions apply to ion-alert and ion-popover elements when the overlay is presented and multiple selection is enabled.
| Key | Description |
|---|---|
| Enter | When the 'OK' button is focused, it will save the user's selection, dismiss the overlay, and return focus to the ion-select element. |
| Escape | Closes the overlay without changing the submitted option(s). Returns the focus back to the ion-select element. |
| Space | Selects or deselects the currently focused option. This does not deselect the other selected options. If the overlay does not have an 'OK' button, the value will be committed immediately. |
| Tab | Move focus to the next focusable element (cancel button, 'OK' button, or any of the options) on the overlay. If the next focusable element is the options list, then it should iterate through each option. |
Properties
cancelText
| Description | キャンセルボタンに表示するテキストです。 |
| Attribute | cancel-text |
| Type | string |
| Default | 'Cancel' |
color
| Description | アプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです："primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", と "dark" です．色についての詳細は theming を参照してください。 このプロパティは、modern select構文を使用する場合にのみ利用可能です。 |
| Attribute | color |
| Type | "danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined |
| Default | undefined |
compareWith
| Description | オブジェクトの値を比較するために使用されるプロパティ名または関数。 |
| Attribute | compare-with |
| Type | ((currentValue: any, compareValue: any) => boolean) ｜ null ｜ string ｜ undefined |
| Default | undefined |
disabled
| Description | trueの場合、ユーザはセレクトと対話することができません。 |
| Attribute | disabled |
| Type | boolean |
| Default | false |
expandedIcon
| Description | セレクトが開いているときに表示するトグルアイコン。定義されている場合、mdモードでのアイコン回転の動作は無効になる。未定義の場合、セレクトが開いているときも閉じているときも toggleIcon が使用される。 |
| Attribute | expanded-icon |
| Type | string ｜ undefined |
| Default | undefined |
fill
| Description | アイテムの塗りつぶし。もし "solid" ならば、アイテムは背景を持つようになります。もし "outline" ならば、アイテムはボーダー付きの透明なものになります。md`モードでのみ使用可能です。 |
| Attribute | fill |
| Type | "outline" ｜ "solid" ｜ undefined |
| Default | undefined |
interface
| Description | selectが使用するインターフェース。action-sheet, popoverまたはalert`. |
| Attribute | interface |
| Type | "action-sheet" ｜ "alert" ｜ "popover" |
| Default | 'alert' |
interfaceOptions
| Description | alert、action-sheet、popoverインターフェースが取ることができる追加オプション。各インターフェイスの作成オプションについては、 [ion-alert docs](./alert), [ion-action-sheet docs](./action-sheet), [ion-popover docs](./popover) を参照してください。 注意:interfaceOptionsはalertインターフェースでinputsやbuttons` をオーバーライドしません。 |
| Attribute | interface-options |
| Type | any |
| Default | {} |
justify
| Description | ラベルとセレクトを1行にまとめる方法。labelPlacementが "floating" または "stacked" に設定されている場合、ラベルとセレクトが異なる行にあるときは justify は適用されません。"start"：ラベルとセレクトはLTRでは左側に、RTLでは右側に表示されます。"end"：ラベルとセレクトはLTRでは右に、RTLでは左に表示されます。"space-between"`：ラベルとセレクトは行の反対側の端に表示され、2つの要素の間にはスペースがあります。 |
| Attribute | justify |
| Type | "end" ｜ "space-between" ｜ "start" |
| Default | 'space-between' |
label
| Description | セレクトに関連付けられた可視ラベル。 プレーンテキストのラベルをレンダリングする必要がある場合に使用する。 labelプロパティは label` スロットよりも優先される。 |
| Attribute | label |
| Type | string ｜ undefined |
| Default | undefined |
labelPlacement
| Description | セレクトに対してラベルを配置する位置。"start"：ラベルはLTRではセレクトの左側に、RTLでは右側に表示されます。"end"：ラベルはLTRではセレクトの右側に、RTLでは左側に表示されます。"floating"：ラベルは、セレクトがフォーカスされているか、セレクトに値がある場合、小さく表示され、セレクトの上に表示されます。それ以外の場合は、セレクトの上に表示されます。"stacked"：ラベルは、セレクトがぼやけた状態や値がない状態でも、小さく表示され、セレクトの上に表示されます。"fixed"：ラベルの幅が固定される以外は、"start"と同じ動作になります。長いテキストは省略記号（"..."）で切り捨てられます。"floating"や "stacked"を使用する場合は、selectに valueかplaceholder` のどちらかを指定して初期化することをお勧めします。 |
| Attribute | label-placement |
| Type | "end" ｜ "fixed" ｜ "floating" ｜ "stacked" ｜ "start" ｜ undefined |
| Default | 'start' |
legacy
| Description | legacyプロパティをtrueに設定すると、レガシーフォームコントロールのマークアップを強制的に使用することができます。Ionicは、コンポーネントがaria-label属性またはlabelプロパティを使用している場合にのみ、最新のフォームマークアップを選択します。そのため、legacyプロパティは、この自動オプトイン動作を回避したい場合にのみ、エスケープハッチとして使用する必要があります。なお、このプロパティはIonicの今後のメジャーリリースで削除され、すべてのフォームコンポーネントはモダンフォームマークアップを使用するようオプトインされる予定です。 |
| Attribute | legacy |
| Type | boolean ｜ undefined |
| Default | undefined |
mode
| Description | modeは、どのプラットフォームのスタイルを使用するかを決定します。 |
| Attribute | mode |
| Type | "ios" ｜ "md" |
| Default | undefined |
multiple
| Description | trueの場合、selectは複数の値を受け入れることができる。 |
| Attribute | multiple |
| Type | boolean |
| Default | false |
name
| Description | フォームデータとともに送信されるコントロールの名前。 |
| Attribute | name |
| Type | string |
| Default | this.inputId |
okText
| Description | okボタンに表示するテキストです。 |
| Attribute | ok-text |
| Type | string |
| Default | 'OK' |
placeholder
| Description | セレクトが空のときに表示するテキストです。 |
| Attribute | placeholder |
| Type | string ｜ undefined |
| Default | undefined |
selectedText
| Description | 選択されたオプションの値の代わりに表示するテキストです。 |
| Attribute | selected-text |
| Type | null ｜ string ｜ undefined |
| Default | undefined |
shape
| Description | セレクトの形状を指定します。roundの場合、境界線の半径が大きくなります。 |
| Attribute | shape |
| Type | "round" ｜ undefined |
| Default | undefined |
toggleIcon
| Description | 使用するトグルアイコン。デフォルトは ios モードの場合は chevronExpand で、md モードの場合は caretDownSharp である。 |
| Attribute | toggle-icon |
| Type | string ｜ undefined |
| Default | undefined |
value
| Description | セレクトの値です。 |
| Attribute | value |
| Type | any |
| Default | undefined |
イベント
| Name | Description |
|---|---|
ionBlur | セレクトのフォーカスが外れたときに発行されます。 |
ionCancel | 選択がキャンセルされたときに発行されます。 |
ionChange | 値が変更されたときに発行されます。 |
ionDismiss | オーバーレイが解除されたときに発行されます。 |
ionFocus | セレクトにフォーカスが当たったときに発行されます。 |
メソッド
open
| Description | セレクトオーバーレイを開きます。オーバーレイは ion-select の interface プロパティによって、アラート、アクションシート、ポップオーバーのいずれかになります。 |
| Signature | open(event?: UIEvent) => Promise<any> |
CSS Shadow Parts
| Name | Description |
|---|---|
container | 選択テキストまたはプレースホルダーのコンテナ。 |
icon | セレクトアイコンのコンテナです。 |
label | セレクトを表すラベルテキスト。 |
placeholder | 値がないときにセレクトに表示されるテキスト。 |
text | セレクトの表示値です。 |
CSS カスタムプロパティ
| Name | Description |
|---|---|
--background | セレクトの背景 |
--border-color | セレクトボーダーの色 |
--border-radius | 選択枠の半径。fill="outline "を使う場合、半径が大きいと表示が不 均一になることがあります。 |
--border-style | セレクトボーダーのスタイル |
--border-width | セレクトボーダーの幅 |
--highlight-color-focused | フォーカス時のセレクトのハイライトの色 |
--highlight-color-invalid | 無効時のセレクトのハイライトの色 |
--highlight-color-valid | 有効時のセレクトのハイライトの色 |
--padding-bottom | セレクトのBottom Padding |
--padding-end | セレクトの方向が左から右の場合はRight Padding、右から左の場合はLeft Paddingを行う |
--padding-start | セレクトの方向が左から右の場合はLeft Padding、右から左の場合はRight Padding |
--padding-top | セレクトのTop Padding |
--placeholder-color | セレクトPlaceholderテキストの色 |
--placeholder-opacity | 選択Placeholderテキストの不透明度 |
--ripple-color | MDモード時のリップルエフェクトの色です。 |
Slots
| Name | Description |
|---|---|
label | セレクトに関連付けるラベルテキスト。labelPlacement`プロパティを使用して、selectに対するラベルの位置を制御します。ラベルをカスタムHTMLでレンダリングする必要がある場合に使用します。 |