バージョン: v8

ion-popover

ポップオーバーは、現在のページの上に表示されるダイアログです。様々な用途に使用できますが、一般的にはナビゲーションバーに収まらないオーバーフローアクションに使用されます。

ion-popoverを使用するには、インラインまたはpopoverControllerを使用する2つの方法があります。それぞれ異なる考慮事項があるため、ユースケースに最適なアプローチを使用してください。

インラインポップオーバー

ion-popoverは、コンポーネントをテンプレートに直接記述することで使用できます。これにより、ポップオーバーを表示するために接続する必要があるハンドラの数が少なくなります。

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

いつ使用するのか

インラインでポップオーバーを使用すると、ポップオーバーを開くために明示的にクリックイベントを接続する必要がないため便利です。たとえば、triggerプロパティを使用して、クリックされたときにポップオーバーを表示するボタンを指定できます。また、trigger-actionプロパティを使用して、トリガーが左クリック、右クリック、またはホバーされたときにポップオーバーを表示するかどうかをカスタマイズすることもできます。

ポップオーバーの表示と閉じ方を細かく制御する必要がある場合は、popoverControllerを使用することをお勧めします。

Angular

ポップオーバーが表示されるときに渡されたコンポーネントを作成し、ポップオーバーが閉じられるときに破棄する必要があるため、内部で<ng-content>を使用してコンテンツを投影することはできません。代わりに、<ng-template>を渡すことを期待する<ng-container>を使用します。その結果、コンポーネントを渡す際には、<ng-template>でラップする必要があります。

<ion-popover [isOpen]="isPopoverOpen">
  <ng-template>
    <app-popover-content></app-popover-content>
  </ng-template>
</ion-popover>

トリガー

インラインion-popoverのトリガーは、操作されるとポップオーバーを開く要素です。操作の動作は、trigger-actionプロパティを設定することでカスタマイズできます。trigger-action="context-menu"を設定すると、システムのデフォルトコンテキストメニューが開かなくなります。

注記

popoverControllerを使用する場合は、ion-popoverが事前に作成されないため、トリガーは適用できません。

isOpenプロパティ

インラインポップオーバーは、isOpenプロパティをtrueに設定することでも開くことができます。この方法は、トリガーよりも細かい制御が必要な場合に使用できます。

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

コントローラーポップオーバー

ion-popoverは、Ionic FrameworkからインポートされたpopoverControllerを使用してプログラムで表示することもできます。これにより、インラインポップオーバーが提供するカスタマイズを超えて、ポップオーバーの表示を完全に制御できます。

いつ使用するのか

通常、インラインでポップオーバーを作成することをお勧めします。これは、アプリケーション内のコードの量を合理化するためです。popoverControllerは、インラインでポップオーバーを作成することが非現実的な複雑なユースケースでのみ使用してください。コントローラーを使用する場合、ポップオーバーは事前に作成されないため、triggerやtrigger-actionなどのプロパティはここで適用されません。さらに、ネストされたポップオーバーは、createメソッドが呼び出されるとポップオーバーがアプリケーションのルートに自動的に追加されるため、コントローラーアプローチと互換性がありません。

React

コントローラーの代わりに、Reactには同様の動作をするuseIonPopoverというフックがあります。useIonPopoverは<IonApp>の子孫である必要があります。<IonApp>の外側でポップオーバーを使用する必要がある場合は、代わりにインラインポップオーバーを使用することを検討してください。

使用方法

コンソール

上記の例からログ出力されたコンソールメッセージが表示されます。

スタイル設定

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

注記

Ionic Angularアプリを構築する場合、スタイルはグローバルスタイルシートファイルに追加する必要があります。

配置

参照

Popoverを表示する際、Ionic FrameworkはPopoverを基準となるポイントを必要とします。`reference="event"`の場合、Popoverはトリガー要素でディスパッチされたポインターイベントのx-y座標を基準に表示されます。`reference="trigger"`の場合、Popoverはトリガー要素の境界ボックスを基準に表示されます。

側

基準点として何を設定するかに関わらず、`side`プロパティを使用して、Popoverを基準点の上部(`top`)、右側(`right`)、左側(`left`)、または下部(`bottom`)に配置できます。LTRまたはRTLモードに基づいて側を切り替えたい場合は、`start`または`end`の値を使用することもできます。

位置合わせ

`alignment`プロパティを使用すると、Popoverのエッジとトリガー要素の対応するエッジを揃えることができます。使用される正確なエッジは、`side`プロパティの値によって異なります。

側と位置合わせのデモ

オフセット

Popoverの位置をより細かく制御する必要がある場合は、`--offset-x`と`--offset-y`のCSS変数を使用できます。たとえば、`--offset-x: 10px`はPopoverの内容を10px右に移動します。

サイズ調整

ドロップダウンメニューを作成する場合、Popoverの幅をトリガー要素の幅と一致させたい場合があります。トリガーの幅を事前に知らずにこれを行うのは困難です。`size`プロパティを`'cover'`に設定すると、Ionic FrameworkはPopoverの幅がトリガー要素の幅と一致するようにします。

`popoverController`を使用する場合は、`event`オプションを介してイベントを提供する必要があります。Ionic Frameworkは`event.target`を参照要素として使用します。このパターンの例については、コントローラーのデモを参照してください。

ネストされたPopover

`ion-popover`をインラインで使用する場合、ネストされたPopoverをネストしてネストされたドロップダウンメニューを作成できます。この場合、画面がPopoverを開くたびに暗くなるのを防ぐため、最初のPopoverのバックドロップのみが表示されます。

`dismissOnSelect`プロパティを使用して、Popoverの内容がクリックされたときにPopoverを自動的に閉じることができます。この動作は、別のPopoverのトリガー要素をクリックしたときには適用されません。

注記

`popoverController`を使用する場合は、ネストされたPopoverを作成できません。`create`メソッドが呼び出されると、Popoverはアプリケーションのルートに自動的に追加されるためです。

インターフェース

`popoverController`を使用する場合に使用できるすべてのオプションを以下に示します。これらのオプションは、`popoverController.create()`を呼び出す際に提供する必要があります。

interface PopoverOptions {
  component: any;
  componentProps?: { [key: string]: any };
  showBackdrop?: boolean;
  backdropDismiss?: boolean;
  translucent?: boolean;
  cssClass?: string | string[];
  event?: Event;
  animated?: boolean;

  mode?: 'ios' | 'md';
  keyboardClose?: boolean;
  id?: string;
  htmlAttributes?: { [key: string]: any };

  enterAnimation?: AnimationBuilder;
  leaveAnimation?: AnimationBuilder;

  size?: PopoverSize;
  dismissOnSelect?: boolean;
  reference?: PositionReference;
  side?: PositionSide;
  alignment?: PositionAlign;
  arrow?: boolean;
}

型

`ion-popover`のカスタム型を以下に示します。

type PopoverSize = 'cover' | 'auto';
type TriggerAction = 'click' | 'hover' | 'context-menu';
type PositionReference = 'trigger' | 'event';
type PositionSide = 'top' | 'right' | 'bottom' | 'left' | 'start' | 'end';
type PositionAlign = 'start' | 'center' | 'end';

アクセシビリティ

キーボード操作

`ion-popover`は、Popover内のフォーカス可能な要素間を移動するための基本的なキーボードサポートを備えています。次の表に、各キーの機能の詳細を示します。

キー	説明
`Tab`	フォーカスを次のフォーカス可能な要素に移動します。
`Shift` + `Tab`	フォーカスを前のフォーカス可能な要素に移動します。
`Esc`	Popoverを閉じます。
`Space`または`Enter`	フォーカス可能な要素をクリックします。

`ion-popover`は、`button`プロパティを持つ`ion-item`要素間を移動するための完全な矢印キーサポートを備えています。これは、デスクトップ中心のアプリケーションでのドロップダウンメニューとして最も一般的に使用されます。基本的なキーボードサポートに加えて、次の表にドロップダウンメニューの矢印キーサポートの詳細を示します。

キー	説明
`ArrowUp`	フォーカスを前のフォーカス可能な要素に移動します。
`ArrowDown`	フォーカスを次のフォーカス可能な要素に移動します。
`Home`	フォーカスを最初のフォーカス可能な要素に移動します。
`End`	フォーカスを最後のフォーカス可能な要素に移動します。
`ArrowLeft`	子Popoverで使用されている場合、Popoverを閉じ、フォーカスを親Popoverに戻します。
`Space`、`Enter`、および`ArrowRight`	トリガー要素にフォーカスを当てると、関連付けられたPopoverが開きます。

パフォーマンス

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

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

`keepContentsMounted`を使用する際は、次の点に注意してください。

この機能は、既存のパフォーマンスの問題に対処するための最後の手段として使用する必要があります。この機能を使用する前に、パフォーマンスのボトルネックを特定して解決してください。さらに、パフォーマンスの問題を予測するためにこれを使用しないでください。
この機能は、JavaScriptフレームワークを使用する場合にのみ必要です。フレームワークを使用していない開発者は、レンダリングするコンテンツをPopoverに渡すことができ、コンテンツは自動的にレンダリングされます。
この機能はインラインPopoverでのみ機能します。`popoverController`で作成されたPopoverは事前に作成されないため、内部コンテンツも作成されません。
内部コンポーネントのJavaScriptフレームワークのライフサイクルフックは、Popoverが表示されるときにではなく、Popoverがマウントされるとすぐに実行されます。

プロパティ

alignment

説明	Popoverの内容と`reference`ポイントの位置合わせ方法を説明します。`ios`モードでは` "center"`、`md`モードでは` "start"`がデフォルトです。
属性	`alignment`
型	`"center" ｜ "end" ｜ "start" ｜ undefined`
デフォルト	`undefined`

animated

説明	`true`の場合、Popoverはアニメーション化されます。
属性	`animated`
型	`boolean`
デフォルト	`true`

arrow

説明	`true`の場合、`ios`モードで実行されている場合、Popoverは`reference`を指す矢印を表示します。`md`モードでは適用されません。
属性	`arrow`
型	`boolean`
デフォルト	`true`

backdropDismiss

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

component

説明	Popover内に表示するコンポーネント。JavaScriptフレームワークを使用していない場合にのみこれを使用する必要があります。それ以外の場合は、`ion-popover`内にコンポーネントを配置するだけで済みます。
属性	`component`
型	`Function ｜ HTMLElement ｜ null ｜ string ｜ undefined`
デフォルト	`undefined`

componentProps

説明	Popoverコンポーネントに渡すデータ。JavaScriptフレームワークを使用していない場合にのみこれを使用する必要があります。それ以外の場合は、コンポーネントのプロパティを直接設定するだけで済みます。
属性	`undefined`
型	`undefined ｜ { [key: string]: any; }`
デフォルト	`undefined`

dismissOnSelect

説明	`true`の場合、コンテンツがクリックされるとPopoverは自動的に閉じられます。
属性	`dismiss-on-select`
型	`boolean`
デフォルト	`false`

enterAnimation

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

event

説明	Popoverアニメーションに渡すイベント。
属性	`event`
型	`any`
デフォルト	`undefined`

focusTrap

説明	`true`の場合、フォーカスはオーバーレイの外に移動できません。`false`の場合、フォーカスはオーバーレイの外に移動できます。ほとんどの場合、このプロパティは`true`に設定しておく必要があります。このプロパティを`false`に設定すると、アクセシビリティに深刻な問題が発生する可能性があります。補助技術に依存するユーザーは、フォーカスを混乱した状態に移動できる可能性があります。絶対に必要な場合にのみ、これを`false`に設定することをお勧めします。このオーバーレイがサードパーティライブラリから非Ionicオーバーレイを表示する場合、開発者はフォーカストラップを無効にすることを検討する必要があります。開発者は、サードパーティオーバーレイを表示するときにIonicオーバーレイのフォーカストラップを無効にし、サードパーティオーバーレイを閉じ、フォーカスをIonicオーバーレイに戻すときにフォーカストラップを再度有効にします。
属性	`focus-trap`
型	`boolean`
デフォルト	`true`

htmlAttributes

説明	Popoverに渡す追加の属性。
属性	`undefined`
型	`undefined ｜ { [key: string]: any; }`
デフォルト	`undefined`

isOpen

説明	`true`の場合、ポップオーバーが開きます。`false`の場合、ポップオーバーが閉じます。プレゼンテーションをより細かく制御する必要がある場合に使用します。それ以外の場合は、popoverControllerまたは`trigger`プロパティを使用してください。注：ポップオーバーが閉じても、`isOpen`は自動的に`false`に設定されません。コード内でその処理を行う必要があります。
属性	`is-open`
型	`boolean`
デフォルト	`false`

keepContentsMounted

説明	`true`の場合、`ion-popover`に渡されたコンポーネントは、ポップオーバーの作成時に自動的にマウントされます。ポップオーバーが閉じても、コンポーネントはマウントされたままです。ただし、ポップオーバーが破棄されると、コンポーネントも破棄されます。このプロパティはリアクティブではなく、ポップオーバーを最初に作成する場合にのみ使用してください。注：この機能は、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`

reference

説明	ポップオーバーの基準となる位置を記述します。`"trigger"`の場合、ポップオーバーはトリガーボタンを基準に配置されます。イベントを渡す場合、これはevent.targetによって決定されます。`"event"`の場合、ポップオーバーはトリガーアクションのx/y座標を基準に配置されます。イベントを渡す場合、これはevent.clientXとevent.clientYによって決定されます。
属性	`reference`
型	`"event" ｜ "trigger"`
デフォルト	`'trigger'`

showBackdrop

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

side

説明	`reference`ポイントのどの辺にポップオーバーを配置するかを記述します。`"start"`と`"end"`の値はRTL対応で、`"left"`と`"right"`の値はRTL対応ではありません。
属性	`side`
型	`"bottom" ｜ "end" ｜ "left" ｜ "right" ｜ "start" ｜ "top"`
デフォルト	`'bottom'`

size

説明	ポップオーバーの幅の計算方法を記述します。`"cover"`の場合、ポップオーバーの幅はトリガーの幅と一致します。`"auto"`の場合、ポップオーバーの幅は静的なデフォルト値に設定されます。
属性	`size`
型	`"auto" ｜ "cover"`
デフォルト	`'auto'`

translucent

説明	`true`の場合、ポップオーバーは半透明になります。モードが`"ios"`で、デバイスが`backdrop-filter`をサポートする場合にのみ適用されます。
属性	`translucent`
型	`boolean`
デフォルト	`false`

trigger

説明	ポップオーバーを開くトリガー要素に対応するID。`trigger-action`プロパティを使用して、ポップオーバーが開く操作をカスタマイズします。
属性	`trigger`
型	`文字列｜ undefined`
デフォルト	`undefined`

triggerAction

説明	トリガーとのどのようなインタラクションでポップオーバーを開くかを記述します。`trigger`プロパティが`undefined`の場合は適用されません。`"click"`の場合、トリガーが左クリックされるとポップオーバーが表示されます。`"hover"`の場合、ポインタがトリガーの上にホバーするとポップオーバーが表示されます。`"context-menu"`の場合、デスクトップではトリガーを右クリックし、モバイルでは長押しするとポップオーバーが表示されます。これにより、デバイスの通常のコンテキストメニューが表示されることもなくなります。
属性	`trigger-action`
型	`"click" ｜ "context-menu" ｜ "hover"`
デフォルト	`'click'`

イベント

名前	説明	バブル
`didDismiss`	ポップオーバーが閉じられた後に発生します。ionPopoverDidDismissの省略形です。	`true`
`didPresent`	ポップオーバーが表示された後に発生します。ionPopoverWillDismissの省略形です。	`true`
`ionPopoverDidDismiss`	ポップオーバーが閉じられた後に発生します。	`true`
`ionPopoverDidPresent`	ポップオーバーが表示された後に発生します。	`true`
`ionPopoverWillDismiss`	ポップオーバーが閉じられる前に発生します。	`true`
`ionPopoverWillPresent`	ポップオーバーが表示される前に発生します。	`true`
`willDismiss`	ポップオーバーが閉じられる前に発生します。ionPopoverWillDismissの省略形です。	`true`
`willPresent`	ポップオーバーが表示される前に発生します。ionPopoverWillPresentの省略形です。	`true`

メソッド

dismiss

説明	表示された後にポップオーバーオーバーレイを閉じます。
シグネチャ	`dismiss(data?: any, role?: string, dismissParentPopover?: boolean) => Promise<boolean>`

onDidDismiss

説明	ポップオーバーが閉じられたときに解決されるPromiseを返します。
シグネチャ	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

説明	ポップオーバーが閉じられるときに解決されるPromiseを返します。
シグネチャ	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

説明	作成後にポップオーバーオーバーレイを表示します。開発者は、マウス、タッチ、またはポインタイベントを渡して、そのイベントがディスパッチされた場所を基準にポップオーバーを配置できます。
シグネチャ	`present(event?: MouseEvent ｜ TouchEvent ｜ PointerEvent ｜ CustomEvent) => Promise<void>`

CSSシャドウパーツ

名前	説明
`arrow`	参照要素を指す矢印。`ios`モードでのみ適用されます。
`backdrop`	`ion-backdrop`要素。
`content`	デフォルトスロットのラッパー要素。

CSSカスタムプロパティ

名前	説明
`--backdrop-opacity`	背景の不透明度
`--background`	ポップオーバーの背景
`--box-shadow`	ポップオーバーのボックスシャドウ
`--height`	ポップオーバーの高さ
`--max-height`	ポップオーバーの最大高さ
`--max-width`	ポップオーバーの最大幅
`--min-height`	ポップオーバーの最小高さ
`--min-width`	ポップオーバーの最小幅
`--offset-x`	x軸方向にポップオーバーを移動する量
`--offset-y`	y軸方向にポップオーバーを移動する量
`--width`	ポップオーバーの幅

名前	説明
`--backdrop-opacity`	背景の不透明度
`--background`	ポップオーバーの背景
`--box-shadow`	ポップオーバーのボックスシャドウ
`--height`	ポップオーバーの高さ
`--max-height`	ポップオーバーの最大高さ
`--max-width`	ポップオーバーの最大幅
`--min-height`	ポップオーバーの最小高さ
`--min-width`	ポップオーバーの最小幅
`--offset-x`	x軸方向にポップオーバーを移動する量
`--offset-y`	y軸方向にポップオーバーを移動する量
`--width`	ポップオーバーの幅

スロット

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

インラインポップオーバー​

いつ使用するのか​

Angular​

トリガー​

isOpenプロパティ​

コントローラーポップオーバー​

いつ使用するのか​

React​

使用方法​

スタイル設定​

配置​

参照​

側​

位置合わせ​

側と位置合わせのデモ​

オフセット​

サイズ調整​

ネストされたPopover​

インターフェース​

型​

アクセシビリティ​

キーボード操作​

パフォーマンス​

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

プロパティ​

alignment​

animated​

arrow​

backdropDismiss​

component​

componentProps​

dismissOnSelect​

enterAnimation​

event​

focusTrap​

htmlAttributes​

isOpen​

keepContentsMounted​

keyboardClose​

leaveAnimation​

mode​

reference​

showBackdrop​

side​

size​

translucent​

trigger​

triggerAction​

イベント​

メソッド​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSSシャドウパーツ​

CSSカスタムプロパティ​

スロット​

目次

インラインポップオーバー

いつ使用するのか

Angular

トリガー

isOpenプロパティ

コントローラーポップオーバー

いつ使用するのか

React

使用方法

スタイル設定

配置

参照

側

位置合わせ

側と位置合わせのデモ

オフセット

サイズ調整

ネストされたPopover

インターフェース

型

アクセシビリティ

キーボード操作

パフォーマンス

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

プロパティ

alignment

animated

arrow

backdropDismiss

component

componentProps

dismissOnSelect

enterAnimation

event

focusTrap

htmlAttributes

isOpen

keepContentsMounted

keyboardClose

leaveAnimation

mode

reference

showBackdrop

side

size

translucent

trigger

triggerAction

イベント

メソッド

dismiss

onDidDismiss

onWillDismiss

present

CSSシャドウパーツ

CSSカスタムプロパティ

スロット