ion-modal

shadow

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 プロパティは、ハンドルがユーザーによってアクティブにされたときの振る舞いを設定するために使用されます。

スタイリング

モーダルはアプリケーションのルートで表示されるので、アプリ全体を覆うように表示されます。この動作は、インライン モーダルおよびコントローラから表示されるモーダルの両方に適用されます。その結果、カスタムのモーダルスタイルを特定のコンポーネントにスコープすることはできず、モーダルには適用されません。代わりに、スタイルはグローバルに適用する必要があります。ほとんどの開発者は、カスタムスタイルを 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 Navigation

Key	Function
Esc	Dismisses the modal

ラベル

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

スクリーンリーダー

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

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

See https://w3c.github.io/aria/#aria-modal for more information.

フォーカスのトラッピング

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

backdropBreakpoint プロパティによって背景が無効にされたシート モーダルは、フォーカスのトラッピングの対象にはなりません。

シートモーダル

シートモーダルでは、backdropBreakpoint プロパティが使用されているとき、ユーザがモーダルの後ろのコンテンツとインタラクトできるようにします。バックドロップは、指定された backdropBreakpoint までは無効になり、それ以降は有効になります。

バックドロップが無効になると、ユーザーはポインタやキーボードを使用して、シートモーダルの外側の要素を操作することができるようになります。入力支援は、aria-modal の使用により、デフォルトではシートモーダルの外側にフォーカスを当てないかもしれません。オートフォーカスなどの機能は、ユーザーに警告することなく、支援技術が 2つのインタラクティブなコンテキスト間をジャンプする原因となるため、ここでは避けることをお勧めします。

パフォーマンス

インナー コンテンツのマウント

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

開発者は keepContentsMounted を使用する際に、以下の点に注意する必要があります。

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

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

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

• インナー コンポーネントの JavaScript Framework ライフサイクル フックはすべて、モーダルが表示されたときではなく、モーダルがマウントされたときに実行されます。

プロパティ

animated

Description	If true, the modal will animate.
Attribute	animated
Type	boolean
Default	true

backdropBreakpoint

Description	A decimal value between 0 and 1 that indicates the point after which the backdrop will begin to fade in when using a sheet modal. Prior to this point, the backdrop will be hidden and the content underneath the sheet can be interacted with. This value is exclusive meaning the backdrop will become active after the value specified.
Attribute	backdrop-breakpoint
Type	number
Default	0

backdropDismiss

Description	If true, the modal will be dismissed when the backdrop is clicked.
Attribute	backdrop-dismiss
Type	boolean
Default	true

breakpoints

Description	The breakpoints to use when creating a sheet modal. Each value in the array must be a decimal between 0 and 1 where 0 indicates the modal is fully closed and 1 indicates the modal is fully open. Values are relative to the height of the modal, not the height of the screen. One of the values in this array must be the value of the initialBreakpoint property. For example: [0, .25, .5, 1]
Attribute	undefined
Type	number[] ｜ undefined
Default	undefined

canDismiss

Description	Determines whether or not a modal can dismiss when calling the dismiss method. If the value is true or the value's function returns true, the modal will close when trying to dismiss. If the value is false or the value's function returns false, the modal will not close when trying to dismiss. See https://ionicframework.com/docs/troubleshooting/runtime#accessing-this if you need to access this from within the callback.
Attribute	can-dismiss
Type	((data?: any, role?: string ｜ undefined) => Promise<boolean>) ｜ boolean
Default	true

enterAnimation

Description	Animation to use when the modal is presented.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

focusTrap

Description	If true, focus will not be allowed to move outside of this overlay. If false, focus will be allowed to move outside of the overlay. In most scenarios this property should remain set to true. Setting this property to false can cause severe accessibility issues as users relying on assistive technologies may be able to move focus into a confusing state. We recommend only setting this to false when absolutely necessary. Developers may want to consider disabling focus trapping if this overlay presents a non-Ionic overlay from a 3rd party library. Developers would disable focus trapping on the Ionic overlay when presenting the 3rd party overlay and then re-enable focus trapping when dismissing the 3rd party overlay and moving focus back to the Ionic overlay.
Attribute	focus-trap
Type	boolean
Default	true

handle

Description	The horizontal line that displays at the top of a sheet modal. It is true by default when setting the breakpoints and initialBreakpoint properties.
Attribute	handle
Type	boolean ｜ undefined
Default	undefined

handleBehavior

Description	The interaction behavior for the sheet modal when the handle is pressed. Defaults to "none", which means the modal will not change size or position when the handle is pressed. Set to "cycle" to let the modal cycle between available breakpoints when pressed. Handle behavior is unavailable when the handle property is set to false or when the breakpoints property is not set (using a fullscreen or card modal).
Attribute	handle-behavior
Type	"cycle" ｜ "none" ｜ undefined
Default	'none'

htmlAttributes

Description	Additional attributes to pass to the modal.
Attribute	undefined
Type	undefined ｜ { [key: string]: any; }
Default	undefined

initialBreakpoint

Description	A decimal value between 0 and 1 that indicates the initial point the modal will open at when creating a sheet modal. This value must also be listed in the breakpoints array.
Attribute	initial-breakpoint
Type	number ｜ undefined
Default	undefined

isOpen

Description	If true, the modal will open. If false, the modal will close. Use this if you need finer grained control over presentation, otherwise just use the modalController or the trigger property. Note: isOpen will not automatically be set back to false when the modal dismisses. You will need to do that in your code.
Attribute	is-open
Type	boolean
Default	false

keepContentsMounted

Description	If true, the component passed into ion-modal will automatically be mounted when the modal is created. The component will remain mounted even when the modal is dismissed. However, the component will be destroyed when the modal is destroyed. This property is not reactive and should only be used when initially creating a modal. Note: This feature only applies to inline modals in JavaScript frameworks such as Angular, React, and Vue.
Attribute	keep-contents-mounted
Type	boolean
Default	false

keyboardClose

Description	If true, the keyboard will be automatically dismissed when the overlay is presented.
Attribute	keyboard-close
Type	boolean
Default	true

leaveAnimation

Description	Animation to use when the modal is dismissed.
Attribute	undefined
Type	((baseEl: any, opts?: any) => Animation) ｜ undefined
Default	undefined

mode

Description	The mode determines which platform styles to use.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

presentingElement

Description	The element that presented the modal. This is used for card presentation effects and for stacking multiple modals on top of each other. Only applies in iOS mode.
Attribute	undefined
Type	HTMLElement ｜ undefined
Default	undefined

showBackdrop

Description	If true, a backdrop will be displayed behind the modal. This property controls whether or not the backdrop darkens the screen when the modal is presented. It does not control whether or not the backdrop is active or present in the DOM.
Attribute	show-backdrop
Type	boolean
Default	true

trigger

Description	An ID corresponding to the trigger element that causes the modal to open when clicked.
Attribute	trigger
Type	string ｜ undefined
Default	undefined

イベント

Name	Description	Bubbles
didDismiss	Emitted after the modal has dismissed. Shorthand for ionModalDidDismiss.	true
didPresent	Emitted after the modal has presented. Shorthand for ionModalDidPresent.	true
ionBreakpointDidChange	Emitted after the modal breakpoint has changed.	true
ionModalDidDismiss	Emitted after the modal has dismissed.	true
ionModalDidPresent	Emitted after the modal has presented.	true
ionModalWillDismiss	Emitted before the modal has dismissed.	true
ionModalWillPresent	Emitted before the modal has presented.	true
willDismiss	Emitted before the modal has dismissed. Shorthand for ionModalWillDismiss.	true
willPresent	Emitted before the modal has presented. Shorthand for ionModalWillPresent.	true

メソッド

dismiss

Description	Dismiss the modal overlay after it has been presented.
Signature	dismiss(data?: any, role?: string) => Promise<boolean>

getCurrentBreakpoint

Description	Returns the current breakpoint of a sheet style modal
Signature	getCurrentBreakpoint() => Promise<number ｜ undefined>

onDidDismiss

Description	Returns a promise that resolves when the modal did dismiss.
Signature	onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

Description	Returns a promise that resolves when the modal will dismiss.
Signature	onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

present

Description	Present the modal overlay after it has been created.
Signature	present() => Promise<void>

setCurrentBreakpoint

Description	Move a sheet style modal to a specific breakpoint. The breakpoint value must be a value defined in your breakpoints array.
Signature	setCurrentBreakpoint(breakpoint: number) => Promise<void>

CSS Shadow Parts

Name	Description
backdrop	The ion-backdrop element.
content	The wrapper element for the default slot.
handle	The handle that is displayed at the top of the sheet modal when handle="true".

CSSカスタムプロパティ

iOS

Name	Description
--backdrop-opacity	Opacity of the backdrop
--background	Background of the modal content
--border-color	Border color of the modal content
--border-radius	Border radius of the modal content
--border-style	Border style of the modal content
--border-width	Border width of the modal content
--height	Height of the modal
--max-height	Maximum height of the modal
--max-width	Maximum width of the modal
--min-height	Minimum height of the modal
--min-width	Minimum width of the modal
--width	Width of the modal

MD

Name	Description
--backdrop-opacity	Opacity of the backdrop
--background	Background of the modal content
--border-color	Border color of the modal content
--border-radius	Border radius of the modal content
--border-style	Border style of the modal content
--border-width	Border width of the modal content
--height	Height of the modal
--max-height	Maximum height of the modal
--max-width	Maximum width of the modal
--min-height	Minimum height of the modal
--min-width	Minimum width of the modal
--width	Width of the modal

Slots

Name	Description
``	Content is placed inside of the .modal-content element.