メインコンテンツへスキップ
バージョン: v8

ion-modal

モーダルは、アプリのコンテンツの上に表示されるダイアログで、操作を再開する前にアプリによって閉じられる必要があります。多くのオプションから選択する場合や、リスト内のアイテムをフィルタリングする場合など、多くのユースケースでセレクトコンポーネントとして役立ちます。

ion-modal は、テンプレートに直接コンポーネントを記述することで使用できます。これにより、モーダルを表示するために配線する必要があるハンドラーの数を減らすことができます。

Angular、React、またはVueでion-modalを使用する場合、渡したコンポーネントはモーダルが閉じられると破棄されます。この機能はJavaScriptフレームワークによって提供されるため、JavaScriptフレームワークなしでion-modalを使用すると、渡したコンポーネントは破棄されません。これが必須の機能である場合は、代わりにmodalControllerを使用することをお勧めします。

isOpen の使用

ion-modalisOpen プロパティを使用すると、開発者はアプリケーションの状態からモーダルの表示状態を制御できます。つまり、isOpentrue に設定されている場合、モーダルが表示され、isOpenfalse に設定されている場合、モーダルが閉じられます。

isOpen は一方向のデータバインディングを使用します。つまり、モーダルが閉じられたときに自動的に false に設定されることはありません。開発者は、ionModalDidDismiss または didDismiss イベントをリッスンし、isOpenfalse に設定する必要があります。この理由は、ion-modal の内部がアプリケーションの状態と密接に結合するのを防ぐためです。一方向のデータバインディングでは、モーダルはリアクティブ変数が提供するブール値のみを考慮する必要があります。双方向のデータバインディングでは、モーダルはブール値とリアクティブ変数自体の存在の両方を考慮する必要があります。これにより、非決定的な動作が発生し、アプリケーションのデバッグが困難になる可能性があります。

コントローラーモーダル

modalController を使用すると、開発者はプログラムで ion-modal を表示できます。開発者は、モーダルが表示および閉じられるタイミングを完全に制御できます。

モーダルの破棄の防止

モーダルにデータを入力する場合、データの偶発的な損失を防ぐ方法があると望ましいことがよくあります。ion-modalcanDismiss プロパティを使用すると、開発者はモーダルを閉じることができるタイミングを制御できます。

canDismiss プロパティの使用方法には、ブール値を設定する方法と、コールバック関数を設定する方法の2つの異なる方法があります。

注: シートモーダルを使用する場合、0 ブレークポイントが設定されていない場合、スワイプ時に canDismiss はチェックされません。ただし、Esc キーまたはハードウェアの戻るボタンを押した場合は、チェックされます。

ブール値の設定

開発者は canDismiss をブール値に設定できます。canDismisstrue の場合、ユーザーがモーダルを閉じようとすると、モーダルが閉じます。canDismissfalse の場合、ユーザーがモーダルを閉じようとしても、モーダルは閉じません。

ブール値の設定は、モーダルを閉じる前に特定のアクションを実行する必要がある場合に使用する必要があります。たとえば、開発者がモーダルを閉じる前に「利用規約」チェックボックスをオンにする必要がある場合、最初に canDismissfalse に設定し、チェックボックスがオンになったときに true に更新できます。

コールバック関数の設定

開発者は canDismiss を関数に設定できます。この関数は、true または false に解決される Promise を返す必要があります。プロミスが true に解決されると、モーダルが閉じます。プロミスが false に解決されると、モーダルは閉じません。

コールバック関数の設定は、モーダルを閉じる前に確認ダイアログを表示するなど、複雑な破棄基準がある場合に使用する必要があります。このダイアログでユーザーが選択したオプションを使用して、モーダルを閉じるかどうかを判断できます。

コールバック関数を設定すると、カードまたはシートモーダルを使用している場合、スワイプジェスチャーが中断されることに注意してください。これは、Ionicがコールバック関数が事前に解決する内容を把握していないためです。

スワイプして閉じるのを防ぐ

開発者は、ユーザーがカードまたはシートモーダルをスワイプして閉じるのを防ぎたい場合があります。これは、canDismiss のコールバック関数を設定し、rolegesture でないかどうかをチェックすることで実現できます。

子コンポーネントでの破棄動作の変更

特定のシナリオでは、開発者は表示されたモーダルの状態に基づいて canDismiss コールバックの動作をカスタマイズする必要がある場合があります。このカスタマイズは、たとえば、開発者がモーダル内のフォームが無効な場合にモーダルが閉じられないようにしたい場合に特に役立ちます。

このカスタマイズを実現するために、子コンポーネントは、関数コールバック、イベント発生、またはその他のリアクティビティメカニズムなどのさまざまな手法を使用して、親コンポーネントと通信し、canDismiss コールバックを制御する条件を更新できます。

子コンポーネントが親コンポーネントと対話して canDismiss コールバックを変更する方法を示す簡単な例を次に示します。

カードモーダル

開発者は、モーダルがアプリのメインコンテンツの上に積み重ねられたカードとして表示されるカードモーダル効果を作成できます。カードモーダルを作成するには、開発者は ion-modalpresentingElement プロパティを設定する必要があります。

presentingElement プロパティは、モーダルの下に表示される要素への参照を受け入れます。これは通常、ion-router-outlet への参照です。

canDismiss プロパティは、カードモーダルをスワイプして閉じることができるかどうかを制御するために使用できます。

カード表示スタイルは、iOSでのみ使用できます。

シートモーダル

情報

モーダルコンテンツをスクロール可能にしたい場合は、シートモーダル内でContentを使用する必要があります。

開発者は、地図アプリケーションで利用可能なドロワーコンポーネントと同様のシートモーダルエフェクトを作成できます。シートモーダルを作成するには、開発者はion-modalbreakpointsおよびinitialBreakpointプロパティを設定する必要があります。

breakpointsプロパティは、スワイプしたときにシートがスナップできる各ブレークポイントを示す配列を受け入れます。breakpointsプロパティが[0, 0.5, 1]の場合、シートをスワイプしてモーダルの0%、50%、および100%を表示できることを示します。モーダルが0%までスワイプされると、モーダルは自動的に閉じられます。0ブレークポイントが含まれていない場合、スワイプでモーダルを閉じることができないことに注意してください。ただし、Escキーまたはハードウェアの戻るボタンを押すことで閉じることができます。

initialBreakpointプロパティは、シートモーダルが表示時にどのブレークポイントから開始するかを認識するために必要です。initialBreakpointの値は、breakpoints配列にも存在する必要があります。breakpointsの値が[0, 0.5, 1]の場合、initialBreakpointの値が0.5であることは、0.5breakpoints配列内にあるため有効です。initialBreakpointの値が0.25であることは、0.25breakpoints配列に存在しないため無効です。

backdropBreakpointプロパティは、ion-backdropがフェードインを開始するポイントをカスタマイズするために使用できます。これは、シートの下にコンテンツがあり、インタラクティブなままにする必要があるインターフェイスを作成する場合に役立ちます。一般的なユースケースは、シートが完全に展開されるまでマップがインタラクティブであるマップをオーバーレイするシートモーダルです。

背景コンテンツの操作

カスタムシート高さ

開発者は、breakpoints配列の最後のブレークポイントを変更する代わりに、--height CSS変数を使用してシートモーダルの高さを変更する必要があります。この理由は、breakpoints配列の最後のブレークポイントを1未満の値に変更すると、モーダルの一部がビューポート外でアクセスできなくなるためです。

次の例は、コンテンツに基づいて自動的にサイズが調整されるシートモーダルを取得する方法を示しています。最大のブレークポイントを1に維持することで、モーダル全体がビューポート内でアクセス可能であることを保証します。

ハンドルの動作

シートモーダルは、オプションで、シートをブレークポイント間でドラッグするために使用されるハンドルインジケーターをレンダリングできます。handleBehaviorプロパティを使用して、ユーザーがハンドルをアクティブ化するタイミングの動作を構成できます。

スタイリング

モーダルはアプリケーションのルートに表示されるため、アプリケーション全体をオーバーレイします。この動作は、インラインモーダルとコントローラーから表示されるモーダルの両方に適用されます。その結果、カスタムモーダルスタイルは、モーダルに適用されないため、特定のコンポーネントにスコープを設定することはできません。代わりに、スタイルはグローバルに適用する必要があります。ほとんどの開発者にとって、カスタムスタイルをglobal.cssに配置することで十分です。

Ionic Angularアプリを構築している場合は、グローバルスタイルシートファイルにスタイルを追加する必要があります。詳細については、以下のAngularセクションのスタイルの配置をお読みください。

ion-modalは、積み重ねられたモーダルが同じサイズであることを前提に動作します。その結果、後続の各モーダルにはボックスシャドウがなく、背景の不透明度が0になります。これは、追加されたモーダルごとにシャドウと背景が濃くなるのを防ぐためです。これは、--box-shadowおよび--backdrop-opacity CSS変数を設定することで変更できます。

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に割り当てることでカスタマイズできます。

カスタムダイアログ

ion-modalは、フルページビュー、カード、またはシートによく使用されますが、カスタムダイアログに使用することもできます。これは、開発者がion-alertion-loadingなどのコンポーネントが提供するよりも複雑なインターフェイスを必要とする場合に役立ちます。

カスタムダイアログを作成する際に留意すべき点がいくつかあります

  • ion-contentは、フルページモーダル、カード、およびシートで使用することを目的としています。カスタムダイアログのサイズが動的または不明な場合は、ion-contentを使用しないでください。
  • カスタムダイアログを作成すると、デフォルトのモーダルエクスペリエンスから切り離す方法が提供されます。その結果、カスタムダイアログは、カードモーダルまたはシートモーダルと一緒に使用しないでください。

インターフェース

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;
}

アクセシビリティ

キーボード操作

キー説明
Escモーダルを閉じます

ラベル

モーダルには、dialogロールがあります。その結果、開発者はモーダルに適切なラベルを付ける必要があります。モーダルがion-titleを使用している場合、ion-modalaria-labelledbyを設定することにより、内部のテキストを使用してモーダル自体にラベルを付けることができます。モーダルに追加の説明テキストが含まれている場合、aria-describedbyを使用することにより、このテキストをモーダルに関連付けることができます。

スクリーンリーダー

モーダルには、aria-modal属性が適用されています。この属性により、支援技術は、ナビゲーションをモーダル要素のコンテンツに制限する可能性があります。その結果、次の項目または前の項目に移動するジェスチャーを使用しても、モーダルの外側の要素にフォーカスが当たらない場合があります。これは、backdropBreakpointプロパティを使用してシートモーダルで背景が無効になっている場合でも適用されます。

開発者が手動でフォーカスを移動した場合、支援技術はナビゲーションをモーダル要素のコンテンツに制限しません。ただし、モーダル外に手動でフォーカスを移動することは、フォーカストラップが有効になっているモーダルではIonicではサポートされていません。

詳細については、https://w3c.github.io/aria/#aria-modalを参照してください。

フォーカストラップ

モーダルが表示されると、フォーカスは表示されたモーダル内にトラップされます。ユーザーはモーダル内の他のインタラクティブ要素にフォーカスできますが、モーダルが表示されている間は、モーダルの外側のインタラクティブ要素にフォーカスすることはできません。複数の積み重ねられたモーダルを表示するアプリケーションの場合、フォーカスは最後に表示されたモーダルでトラップされます。

backdropBreakpointプロパティによって背景が無効になっているシートモーダルは、フォーカストラップの対象ではありません。

シートモーダル

シートモーダルでは、backdropBreakpointプロパティが使用されている場合、ユーザーはモーダルの背後にあるコンテンツを操作できます。背景は、指定されたbackdropBreakpointまで、または指定されたbackdropBreakpointを含めて無効になり、その後有効になります。

背景が無効になっている場合、ユーザーはポインターまたはキーボードを使用してシートモーダルの外側の要素を操作できます。支援技術は、aria-modalの使用により、デフォルトではシートモーダルの外側にフォーカスしない可能性があります。ここでは、ユーザーに警告せずに支援技術が2つのインタラクティブなコンテキスト間をジャンプさせる可能性があるため、自動フォーカスなどの機能は避けることをお勧めします。

パフォーマンス

内部コンテンツのマウント

インラインion-modalのコンテンツは、閉じるとアンマウントされます。このコンテンツのレンダリングにコストがかかる場合、開発者はkeepContentsMountedプロパティを使用して、モーダルがマウントされるとすぐにコンテンツをマウントできます。これにより、モーダルが開いたときに内部コンテンツがすでにマウントされているため、アプリケーションの応答性を最適化できます。

開発者は、keepContentsMountedを使用する際に、次の点を考慮する必要があります

  • この機能は、既存のパフォーマンスの問題に対処するために、最後の手段として使用する必要があります。この機能を使用する前に、パフォーマンスのボトルネックを特定して解決するようにしてください。また、パフォーマンスの問題を予測するためにこれを使用しないでください。

  • この機能は、JavaScriptフレームワークを使用している場合にのみ必要です。フレームワークを使用していない開発者は、レンダリングするコンテンツをモーダルに渡すことができ、コンテンツは自動的にレンダリングされます。

  • この機能はインラインモーダルでのみ動作します。modalController で作成されたモーダルは事前に作成されないため、内部コンテンツも作成されません。

  • 内部コンポーネントの JavaScript フレームワークのライフサイクルフックは、モーダルが表示されるときではなく、モーダルがマウントされるとすぐに実行されます。

プロパティ

animated

説明trueの場合、モーダルはアニメーションします。
属性animated
boolean
デフォルトtrue

backdropBreakpoint

説明シートモーダルを使用する場合に、バックドロップがフェードインを開始する時点を示す 0 から 1 の間の 10 進数値です。この時点より前は、バックドロップは非表示になり、シートの下のコンテンツを操作できます。この値は排他的であり、指定された値の後でバックドロップがアクティブになります。
属性backdrop-breakpoint
number
デフォルト0

backdropDismiss

説明trueの場合、バックドロップをクリックするとモーダルが閉じます。
属性backdrop-dismiss
boolean
デフォルトtrue

breakpoints

説明シートモーダルを作成する際に使用するブレークポイント。配列内の各値は 0 から 1 の間の 10 進数である必要があり、0 はモーダルが完全に閉じている状態を示し、1 はモーダルが完全に開いている状態を示します。値は、画面の高さではなく、モーダルの高さに対する相対的な値です。この配列の値の 1 つは、initialBreakpoint プロパティの値である必要があります。例:[0, .25, .5, 1]
属性undefined
number[] | undefined
デフォルトundefined

canDismiss

説明dismiss メソッドを呼び出したときにモーダルを閉じることができるかどうかを決定します。

値が true であるか、値の関数が true を返す場合、モーダルは閉じようとすると閉じます。値が false であるか、値の関数が false を返す場合、モーダルは閉じようとしても閉じません。

コールバック内から this にアクセスする必要がある場合は、https://ionic.dokyumento.jp/docs/troubleshooting/runtime#accessing-this を参照してください。
属性can-dismiss
((data?: any, role?: string | undefined) => Promise<boolean>) | boolean
デフォルトtrue

enterAnimation

説明モーダルが表示されるときに使用するアニメーション。
属性undefined
((baseEl: any, opts?: any) => Animation) | undefined
デフォルトundefined

focusTrap

説明trueの場合、フォーカスはこのオーバーレイの外に移動できません。falseの場合、フォーカスはオーバーレイの外に移動できます。

ほとんどの場合、このプロパティは true に設定したままにする必要があります。このプロパティを false に設定すると、支援技術を利用しているユーザーがフォーカスを混乱した状態に移動させてしまう可能性があるため、重大なアクセシビリティの問題が発生する可能性があります。絶対に必要な場合にのみ、これを false に設定することをお勧めします。

開発者は、このオーバーレイがサードパーティライブラリの Ionic 以外のオーバーレイを表示する場合に、フォーカストラップを無効にすることを検討する必要があります。開発者は、サードパーティのオーバーレイを表示するときに Ionic オーバーレイのフォーカストラップを無効にし、サードパーティのオーバーレイを閉じるときにフォーカストラップを再度有効にして、フォーカスを Ionic オーバーレイに戻します。
属性focus-trap
boolean
デフォルトtrue

handle

説明シートモーダルの上部に表示される水平線。breakpoints および initialBreakpoint プロパティを設定すると、デフォルトで true になります。
属性handle
boolean | undefined
デフォルトundefined

handleBehavior

説明ハンドルが押されたときのシートモーダルのインタラクション動作。

デフォルトは "none" で、これはハンドルが押されてもモーダルのサイズや位置が変わらないことを意味します。押されたときにモーダルが使用可能なブレークポイントを循環するようにするには、"cycle" に設定します。

handle プロパティが false に設定されている場合、または breakpoints プロパティが設定されていない場合(フルスクリーンまたはカードモーダルを使用している場合)、ハンドル動作は使用できません。
属性handle-behavior
"cycle" | "none" | undefined
デフォルト'none'

htmlAttributes

説明モーダルに渡す追加の属性。
属性undefined
undefined | { [key: string]: any; }
デフォルトundefined

initialBreakpoint

説明シートモーダルを作成するときに、モーダルが開く初期点を示す 0 から 1 の間の 10 進数値。この値は、breakpoints 配列にもリストされている必要があります。
属性initial-breakpoint
number | undefined
デフォルトundefined

isOpen

説明trueの場合、モーダルが開きます。falseの場合、モーダルは閉じます。表示を細かく制御する必要がある場合はこれを使用します。それ以外の場合は、modalController または trigger プロパティを使用してください。注: モーダルが閉じても、isOpen は自動的に false に戻りません。コード内でそれを行う必要があります。
属性is-open
boolean
デフォルトfalse

keepContentsMounted

説明true の場合、ion-modal に渡されたコンポーネントは、モーダルが作成されたときに自動的にマウントされます。コンポーネントは、モーダルが閉じられた場合でもマウントされたままになります。ただし、モーダルが破棄されると、コンポーネントも破棄されます。このプロパティはリアクティブではなく、モーダルを最初に作成する場合にのみ使用する必要があります。

注: この機能は、Angular、React、Vue などの JavaScript フレームワークのインラインモーダルにのみ適用されます。
属性keep-contents-mounted
boolean
デフォルトfalse

keyboardClose

説明trueの場合、オーバーレイが表示されると、キーボードが自動的に閉じられます。
属性keyboard-close
boolean
デフォルトtrue

leaveAnimation

説明モーダルが閉じるときに使用するアニメーション。
属性undefined
((baseEl: any, opts?: any) => Animation) | undefined
デフォルトundefined

mode

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

presentingElement

説明モーダルを表示した要素。これは、カード表示効果や、複数のモーダルを互いに重ねて表示するために使用されます。iOS モードでのみ適用されます。
属性undefined
HTMLElement | undefined
デフォルトundefined

showBackdrop

説明trueの場合、モーダルの背後にバックドロップが表示されます。このプロパティは、モーダルが表示されたときにバックドロップが画面を暗くするかどうかを制御します。バックドロップがアクティブであるか、DOM に存在するかどうかは制御しません。
属性show-backdrop
boolean
デフォルトtrue

trigger

説明クリックするとモーダルが開くトリガー要素に対応する ID。
属性trigger
string | undefined
デフォルトundefined

イベント

名前説明バブル
didDismissモーダルが閉じた後に発行されます。ionModalDidDismiss の省略形。true
didPresentモーダルが表示された後に発行されます。ionModalDidPresent の省略形。true
ionBreakpointDidChangeモーダルのブレークポイントが変更された後に発行されます。true
ionModalDidDismissモーダルが閉じた後に発行されます。true
ionModalDidPresentモーダルが表示された後に発行されます。true
ionModalWillDismissモーダルが閉じる前に発行されます。true
ionModalWillPresentモーダルが表示される前に発行されます。true
willDismissモーダルが閉じる前に発行されます。ionModalWillDismiss の省略形。true
willPresentモーダルが表示される前に発行されます。ionModalWillPresent の省略形。true

メソッド

dismiss

説明表示されたモーダルオーバーレイを閉じます。
シグネチャdismiss(data?: any, role?: string) => Promise<boolean>

getCurrentBreakpoint

説明シートスタイルのモーダルの現在のブレークポイントを返します
シグネチャgetCurrentBreakpoint() => Promise<number | undefined>

onDidDismiss

説明モーダルが閉じたときに解決される Promise を返します。
シグネチャonDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

説明モーダルが閉じようとしているときに解決される Promise を返します。
シグネチャonWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

説明作成された後、モーダルオーバーレイを表示します。
シグネチャpresent() => Promise<void>

setCurrentBreakpoint

説明シートスタイルのモーダルを特定のブレークポイントに移動します。ブレークポイントの値は、breakpoints配列で定義されている値である必要があります。
シグネチャsetCurrentBreakpoint(breakpoint: number) => Promise<void>

CSSシャドウパーツ

名前説明
backdropion-backdrop要素。
contentデフォルトスロットのラッパー要素。
handlehandle="true"の場合に、シートモーダルの上部に表示されるハンドル。

CSSカスタムプロパティ

名前説明
--backdrop-opacity背景の不透明度
--backgroundモーダルコンテンツの背景
--border-colorモーダルコンテンツのボーダー色
--border-radiusモーダルコンテンツのボーダー半径
--border-styleモーダルコンテンツのボーダースタイル
--border-widthモーダルコンテンツのボーダー幅
--heightモーダルの高さ
--max-heightモーダルの最大高さ
--max-widthモーダルの最大幅
--min-heightモーダルの最小高さ
--min-widthモーダルの最小幅
--widthモーダルの幅

スロット

名前説明
``コンテンツは.modal-content要素内に配置されます。