ion-modal
Modalは、アプリのコンテンツの上に表示されるダイアログであり、インタラクションを再開する前にはアプリによって消されなければならない。選択できるオプションが多い場合や、リスト内の項目をフィルタする場合、およびその他の多くのユースケースで、Selectコンポーネントとして役立ちます。
インラインモーダル(推奨)
テンプレートに直接コンポーネントを記述することで、 ion-modal を使用 することができます。これにより、モーダルを表示するために必要なハンドラの数を減らすことができます。
Angular、React、Vue で ion-modal を使用する場合、渡されたコンポーネントはモーダルが解除されると破棄されます。この機能は JavaScript フレームワークによって提供されるので、JavaScript フレームワークなしで ion-modal を使用しても、渡されたコンポーネントは破棄されません。この機能が必要な場合は、代わりに modalController を使用することをお勧めします。
isOpen の使用
ion-modal の isOpen プロパティを使用すると、開発者がアプリケーションの状態からモーダルの表示状態を制御することができます。つまり、 isOpen を true に設定するとモーダルが表示され、 isOpen を false に設定するとモーダルが解除されます。
isOpen は一方向のデータバインディングを使用します。つまり、モーダルが解除されたときに自動的に false にセットされることはありません。開発者は ionModalDidDismiss または didDismiss イベントを監視して、 isOpen を false に設定する必要があります。この理由は、ion-modal の内部がアプリケーションの状態と密に結合するのを防ぐためである。一方通行のデータバインディングでは、モーダルはリアクティブ変数が提供するboolean値だけを気にすればいいです。双方向のデータバインディングでは、モーダルはboolean値とリアクティブ変数の存在の両方を考慮する必要があります。これは、非決定的な動作につながり、アプリケーションのデバッグを困難にします。
モーダルコントローラ
ModalController を使用すると、開発者はプログラムによって ion-modal を表示させることができます。開発者は、モーダルの表示と非表示を完全に制御することができます。
モーダルの終了を防止する
モーダルにデータを入力しているとき、誤ってデータが失われないようにする方法があると便利です。 ion-modal の canDismiss プロパティは、モーダルをいつ終了させるかを開発者がコントロールできるようにします。
canDismiss`プロパティの使用方法には、boolean値の設定とコールバック関数の設定の2種類があります。
Note: シートモーダルでは、0 ブレークポイントが設定されていない場合、スワイプ時に canDismiss はチェックされません。しかし、Esc やハードウェアのバックボタンを押すと、チェックされます。
boolean値の設定
開発者は canDismiss にboolean値を設定することができます。 canDismiss が true の場合、ユーザーがモーダルを閉じようとすると、モーダルは閉じます。 canDismiss が false の場合、ユーザーがモーダルを閉じようとしても、モーダルは閉じません。
boolean値を設定するのは、モーダルが終了する前に特定のアクションを実行する必要がある場合に使用する必要があります。たとえば、開発者がモーダルを閉じる前に "利用規約" チェックボックスをチェックすることを要求したい場合、最初は canDismiss を false に設定し、チェックボックスがチェックされたら true に更新することが可能です。
コールバック関数を設定する
開発者は canDismiss を関数として設定することができます。この関数は、 true か false のどちらかに解決する Promise を返さなければなりません。もし、約束が true に解決されたら、モーダルは解除されます。もし、プロミスが false に解決された場合、モーダルは解除されません。
コールバック関数を設定するのは、モーダルを終了する前に確認ダイアログを表示するなど、終了条件が複雑な場合に使用する必要があります。ユーザーがこのダイアログで選択したオプションは、モーダルの終了を続行するかどうかの判断に使用されます。
コールバック関数を設定すると、カードまたはシートモーダルの使用時にスワイプジェスチャが中断されることに注意してください。これは、Ionicが、あなたのコールバック関数が何を解決するか事前に知らないためです。
スワイプで閉じないようにする
開発者は、ユーザがスワイプしてカードやシートのモーダルを閉じないようにしたい場合があります。これは canDismiss にコールバック関数を設定し、role が gesture でないかチェックすることで実現できます。
子コンポーネントでのdismiss動作の変更
あるシナリオでは、開発者は提示されたモーダルの状態に基づいて canDismiss コールバックの動作をカスタマイズする必要があるかもしれません。このカスタマイズは、たとえば、モーダル内のフォームが無効な場合にモーダルが却下されないようにしたい場合に特に便利です。
このカスタマイズを実現するために、子コンポーネントは、親コンポーネントと通信して canDismiss コールバックを管理する条件を更新するために、関数コールバック、イベントエミッション、その他のリアクティビティメカニズムなどのさまざまなテクニックを使用できます。
以下は、子コンポーネントが親コンポーネントとどのように通信して canDismiss コールバックを変更できるかを示す簡単な例です:
Card Modal
開発者は、アプリのメインコンテンツの上にカードが積み重なったようにモーダルが表示されるカードモーダルエフェクトを作成できます。カードモーダルを作成するには、開発者は ion-modal に presentingElement プロパティを設定する必要があります。
開発者は、アプリのメインコンテンツの上にカードが積み重なったように表示されるカードモーダル効果を作成することができます。カードモーダルを作成するには、開発者は ion-modal に presentingElement プロパティと swipeToClose プロパティを設定する必要があります。
canDismiss プロパティを使用して、カードモーダルをスワイプして閉じることができるかどうかを制御することができます。
The card display style is only available on iOS.
Sheet Modal
Content should be used inside of the sheet modal if you want your modal content to be scrollable.
開発者は、マップアプリケーションで利用可能なドロワーコンポーネントに似たシートモーダルエフェクトを作成することができます。シートモーダルを作成するには、ion-modal の breakpoints プロパティと initialBreakpoint プロパティを設定する必要があります。
breakpointsプロパティには、スワイプしたときにシートがスナップすることができる各ブレークポイントを示す配列が渡されます。 breakpoints プロパティが [0, 0.5, 1] の場合、シートをスワイプすると、モーダルの 0%、50%、100%を表示することができることを示します。モーダルが0%にスワイプされると、モーダルは自動的にディスクローズされます。 0 ブレークポイントが含まれていない場合、スワイプ時にモーダルを解除することはできませんが、Esc またはハードウェアの戻るボタンを押すことで解除 することができることに注意してください。
initialBreakpoint プロパティは、シート モーダルが表示されるときに、どのブレークポイントから開始するかを知るために必要なものです。 initialBreakpoint の値は、 breakpoints 配列にも存在する必要があります。例えば、 breakpoints の値が [0, 0.5, 1] である場合、 initialBreakpoint の値が 0.5 であれば、 breakpoints 配列に 0.5 が存在するため有効であると考えられます。 0.25 は breakpoints 配列に存在しないので、 initialBreakpoint の値は無効になります。
backdropBreakpoint プロパティは、 ion-backdrop がフェードインし始めるポイントをカスタマイズするために使用することができます。これは、シートの下にインタラクティブなコンテンツがあるようなインタフェースを作成する際に便利です。よくある使用例としては、シートが完全に展開されるまでマップがインタラクティブになるような、マップをオーバーレイするシートモーダルです。
背景コンテンツとのインタラクション
任意の高さのシート
開発者は、breakpoints配列の最後のブレークポイントを変更する代わりに、--height CSS変数を使用してシートモーダルの高さを変更すべきです。その理由は、breakpoints配列の最後のブレークポイントを1未満の値に変更すると、モーダルの一部がビューポート外でアクセスできなくなるためです。
次の例は、コンテンツに基づいて自動的にサイズ調整されるシートモーダルを取得する方法を示しています。最大ブレークポイントを1に保つことで、モーダル全体がビューポート内でアクセス可能であることを保証することに注意してください。
ハンドルの動作
シートモーダルでは、ブレークポイント間でシートをドラッグするために使用されるハンドルインジケータをオプションでレンダリングすることができます。 handleBehavior プロパティは、ハンドルがユーザーによってアクティブにされたときの振る舞いを設定するために使用されます。
Scrolling content at all breakpoints
シートモーダルは、すべてのブレークポイントでコンテンツのスクロールを許可するように設定でき、ビューポートより大きいコンテンツを表示するのに理想的です。expandToScrollプロパティをfalseに設定すると、コンテンツはすべてのブレークポイントでスクロール可能なままです。それ以外の場合、デフォルトでは、シートモーダルが完全に展開されている場合にのみスクロールが有効になります。
Styling
モーダルはアプリケーションのルートで表示されるので、アプリ全体を覆うように表示されます。この動作は、インライン モーダルおよびコントローラから表示されるモーダルの両方に適用されます。その結果、カスタムのモーダルスタイルを特定のコンポーネントにスコープすることはできず、モーダルには適用されません。代わりに、スタイルはグローバルに適用する必要があります。ほとんどの開発者は、カスタムスタイルを global.css に配置すれば十分です。
IonicのAngularアプリを構築する場合、スタイルはグローバルなスタイルシートファイルに追加する必要があります。詳しくは、以下のAngularセクションの Style Placement をお読みください。
ion-modal は、積み重ねられたモーダルは同じサイズであるという前提で動作します。その結果、後続の各モーダルはボックスシャドウを持たず、背景の不透明度は 0 になります。これは、モーダルが追加されるたびに影や背景が濃くなるのを避けるためです。これは、CSS 変数 --box-shadow と --backdrop-opacity を設定することで変更することができます。
ion-modal.stack-modal {
--box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);
--backdrop-opacity: var(--ion-backdrop-opacity, 0.32);
}
アニメーション
アニメーションビルダーを使用し、enterAnimation と leaveAnimation にアニメーションを割り当てることで、表示時、非表示時のアニメーションをカスタマイズすることができます。
Custom Dialogs
ion-modalは、フルページビュー、カード、シートに使用されることが多いですが、カスタムダイアログに使用することも可能です。これは、ion-alertやion-loadingなどのコンポーネントが提供するものより複雑なインターフェースを必要とする開発者に便利です。
カスタムダイアログを作成する際に注意すべき点がいくつかあります。
ion-contentは、フルページモダル、カード、シートで使用することを意図しています。カスタムダイアログのサイズが動的であったり、不明であったりする場合は、ion-contentを使用するべきではありません。- カスタムダイアログを作成することは、デフォルトのモーダルエクスペリエンスから逃れる方法を提供します。そのため、カスタムダイアログは、カードやシートのモーダルでは使用しないでください。
Interfaces
ModalOptions
下記は modalController を使用する際に利用できるすべてのオプションです。これらのオプションは、 modalController.create() を呼び出す際に指定します。
interface ModalOptions {
component: any;
componentProps?: { [key: string]: any };
presentingElement?: HTMLElement;
showBackdrop?: boolean;
backdropDismiss?: boolean;
cssClass?: string | string[];
animated?: boolean;
canDismiss?: boolean | ((data?: any, role?: string) => Promise<boolean>);
mode?: 'ios' | 'md';
keyboardClose?: boolean;
id?: string;
htmlAttributes?: { [key: string]: any };
enterAnimation?: AnimationBuilder;
leaveAnimation?: AnimationBuilder;
breakpoints?: number[];
initialBreakpoint?: number;
backdropBreakpoint?: number;
handle?: boolean;
}
ModalCustomEvent
必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent インターフェースの代わりにこのインターフェースを使用することが可能です。
interface ModalCustomEvent extends CustomEvent {
target: HTMLIonModalElement;
}
アクセシビリティ
Keyboard Interactions
| Key | Description |
|---|---|
| Esc | Dismisses the modal |
ラベル
モーダルには dialog という役割があります。そのため、開発者はモーダルに適切なラベル付けを行う必要があります。モーダルが ion-title を使用している場合、 ion-modal で aria-labelledby を設定すると、内部のテキスト をモーダル自体のラベルに使用することができます。モーダルに追加の説明テキストが含まれている場合、このテキストは aria-describedby を使ってモーダルと関連付けることができます。
スクリーンリーダー
モーダルには aria-modal 属性が適用されています。この属性は、支援技術によるナビゲーションをモーダル要素のコンテンツに制限させることがあります。その結果、次や前の項目に移動するジェスチャを使用しても、モーダルの外側の要素にフォーカスが当たらない場合があります。これは、backdropBreakpoint プロパティを使用して、シート モーダルでバックドロップを無効にした場合にも当てはまります。
開発者が手動でフォーカスを移動しても、アシストはモーダル要素のコンテンツへのナビゲーションを制限しません。ただし、Ionic では、フォーカスのトラッピングが有効になっているモーダルに対して、モーダルの外側に手動でフォーカスを移動することはサポートされていません。
詳細については、https://w3c.github.io/aria/#aria-modal を参照してください。