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
がフェードインし始めるポイントをカスタマイズするために使用することができます。これは、シートの下にインタラクティブなコンテンツがあるようなインタフェースを作成する際に便利です。よくある使用例としては、シートが完全に展開されるまでマップがインタラクティブになるような、マップをオーバーレイするシートモーダルです。
背景コンテンツとのインタラクション
任意の高さのシート
Developers should use the --height
CSS Variable to change the height of the sheet modal instead of changing the last breakpoint in the breakpoints
array. The reason for this is changing the last breakpoint in the breakpoints
array to a value less than 1
will cause some of the modal to be inaccessible outside of the viewport.
The following example shows how to get a sheet modal that is automatically sized based on its content. Note that by keeping the maximum breakpoint at 1
we ensure that the entire modal is accessible in the viewport.
ハンドルの動作
シートモーダルでは、ブレークポイント間でシートをドラッグするために使用されるハンドルインジケータをオプションでレンダリングすることができます。 handleBehavior
プロパティは、ハンドルがユーザーによってアクティブにされたときの振る舞いを設定するために使用されます。
Scrolling content at all breakpoints
Sheet modals can be configured to allow scrolling content at all breakpoints, making them ideal for displaying content larger than the viewport. By setting the expandToScroll
property to false
, the content remains scrollable at every breakpoint. Otherwise, by default, scrolling is only enabled when the sheet modal is fully expanded.
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);
}