Version: v7

ion-popover

Popoverは、現在のページの上部に表示されるダイアログです。これは何にでも使用できますが、通常はナビゲーションバーに収まらないオーバーフローアクションに使用されます。

ion-popover を使用するには、インラインで使用する方法と popoverController を使用する方法がります。それぞれの方法には異なる考慮点があるので、あなたのユースケースに最も適した方法を使用するようにしましょう。

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

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

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

いつ使うか

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

もし、ポップオーバーの表示と非表示を細かく制御したい場合は、 popoverController を使用することをお勧めします。

Angular

渡されたコンポーネントは、ポップオーバーが表示されたときに作成され、ポップオーバーが解除されたときに破棄される必要があるため、内部で <ng-content> を使用してコンテンツを投影することはできません。代わりに、<ng-container> を使用します。これは、<ng-template> が渡されることを想定しています。そのため、コンポーネントを渡す際には、<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" はシステムのデフォルトのコンテキストメニューを開かせないようにします。

note

popoverController を使用する場合、ion-popover は前もって作成されないので、トリガーは適用されません。

isOpen プロパティ

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

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

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

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

どのような場合に使用するのか

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

React

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

使い方

スタイリング

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

note

If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file.

配置

リファレンス

ポップオーバーを表示するとき、Ionic Framework はポップオーバーを相対的に表示するための参照点を必要とします。reference="event" を指定すると、ポップオーバーはトリガー要素で dispatch されたポインターイベントのx-y座標に相対的に表示されます。 reference="trigger" を指定すると、ポップオーバーはトリガー要素のバウンディングボックスに対して相対的に表示されます。

Side

side プロパティを使用することで、基準点の上、右、左、下のいずれかにポップオーバーを配置することができます。また、LTRやRTLのモードに応じてサイドを切り替えたい場合は、 start や end を使用することができます。

Alignment

alignment プロパティは、ポップオーバーのエッジをトリガーエレメントの対応するエッジに揃えることができます。使用される正確なエッジは side プロパティの値に依存します。

Side and Alignment Demo

オフセット

ポップオーバーの位置をより細かく制御したい場合は、CSS 変数 --offset-x と --offset-y を使用することができます。例えば、--offset-x: 10px はポップオーバーのコンテンツを 10px だけ右側に移動させます。

サイズ調整

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

popoverController を使用する場合は、event オプションでイベントを指定する必要があり、Ionic Framework は event.target を参照要素に使用します。このパターンの例は controller demo を参照してください。

ポップオーバーをネスト

インラインで ion-popover を使用する場合、ポップオーバーを入れ子にして入れ子のドロップダウンメニューを作成することができます。このとき、最初のポップオーバーの背景だけが表示されるので、ポップオーバーを開くたびに画面がだんだん暗くなっていくことはありません。

dismissOnSelect プロパティを使用すると、ポップオーバーのコンテンツがクリックされたときに自動的にポップオーバーを閉じることができます。この動作は、他のポップオーバーのトリガー要素をクリックしたときには適用されません。

note

popoverController を使用する場合、ネストしたポップオーバーは作成できません。なぜなら、ポップオーバーは create メソッドが呼ばれたときに、自動的にアプリケーションのルートに追加されるからです。

Interfaces

以下に、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;
}

Types

以下に、ion-popover のすべてのカスタムTypeを紹介します。

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 は、ポップオーバー内のフォーカス可能な要素間を移動するための基本的なキーボードをサポートしています。次の表は、それぞれのキーが何をするのかの詳細です:

Key	Function
`Tab`	Moves focus to the next focusable element.
`Shift` + `Tab`	Moves focus to the previous focusable element.
`Esc`	Closes the popover.
`Space` or `Enter`	Clicks the focusable element.

ion-popover は、 button プロパティを持つ ion-item 要素間を移動するための矢印キーを完全にサポートしています。最も一般的な使用例としては、デスクトップにフォーカスしたアプリケーションにおけるドロップダウンメニューとして使用することができます。基本的なキーボードのサポートに加え、次の表ではドロップダウンメニューの矢印キーのサポートについて詳しく説明します。

Key	Function
`ArrowUp`	Moves focus to the previous focusable element.
`ArrowDown`	Moves focus to the next focusable element.
`Home`	Moves focus to the first focusable element.
`End`	Moves focus to the last focusable element.
`ArrowLeft`	When used in a child popover, closes the popover and returns focus to the parent popover.
`Space`, `Enter`, and `ArrowRight`	When focusing a trigger element, opens the associated popover.

Performance

Innerコンテンツのマウント

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

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

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

プロパティ

alignment

Description	ポップオーバーのコンテンツを `reference` ポイントに揃える方法を記述します。デフォルトは `ios` モードでは `"center"` で、`md` モードでは `"start"` です。
Attribute	`alignment`
Type	`"center" ｜ "end" ｜ "start" ｜ undefined`
Default	`undefined`

animated

Description	`true`の場合、ポップオーバーはアニメーションを行います。
Attribute	`animated`
Type	`boolean`
Default	`true`

arrow

Description	`true`の場合、`ios` modeで動作しているとき、ポップオーバーは `reference` を指し示す矢印を表示します。 `md` modeでは適用されない。
Attribute	`arrow`
Type	`boolean`
Default	`true`

backdropDismiss

Description	`true`の場合、バックドロップがクリックされたときにポップオーバーが解除される。
Attribute	`backdrop-dismiss`
Type	`boolean`
Default	`true`

component

Description	ポップオーバーの内側に表示するコンポーネントです。これを使う必要があるのは、JavaScriptフレームワークを使用していない場合だけです。そうでない場合は、`ion-popover`の中にコンポーネントを入れるだけでいいです。
Attribute	`component`
Type	`Function ｜ HTMLElement ｜ null ｜ string ｜ undefined`
Default	`undefined`

componentProps

Description	ポップオーバー・コンポーネントに渡すデータです。これを使う必要があるのは、JavaScriptフレームワークを使用していない場合だけです。そうでなければ、コンポーネントに直接propsを設定すればよいのです。
Attribute	`undefined`
Type	`undefined ｜ { [key: string]: any; }`
Default	`undefined`

dismissOnSelect

Description	`true`の場合、コンテンツがクリックされると、ポップオーバーは自動的に解除される。
Attribute	`dismiss-on-select`
Type	`boolean`
Default	`false`

enterAnimation

Description	ポップオーバーが表示されたときに使用するアニメーションです。
Attribute	`undefined`
Type	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
Default	`undefined`

event

Description	ポップオーバー・アニメーションに渡すイベントです。
Attribute	`event`
Type	`any`
Default	`undefined`

htmlAttributes

Description	ポップオーバーに渡す追加属性。
Attribute	`undefined`
Type	`undefined ｜ { [key: string]: any; }`
Default	`undefined`

isOpen

Description	`true`の場合、ポップオーバーは開く。もし `false` ならば、ポップオーバーは閉じます。より細かく表示を制御する必要がある場合はこれを使用し、そうでない場合は popoverController または `trigger` プロパティを使用します。注意: ポップオーバーが閉じると `isOpen` は自動的に `false` に戻されません。あなたのコードでそれを行う必要があります。
Attribute	`is-open`
Type	`boolean`
Default	`false`

keepContentsMounted

Description	`true`の場合、ポップオーバーの作成時に `ion-popover` に渡されたコンポーネントが自動的にマウントされます。このコンポーネントは、ポップオーバーが削除されてもマウントされたままです。ただし、ポップオーバーが破棄されると、コンポーネントは破棄されます。このプロパティはリアクティブではないので、ポップオーバーを最初に作成するときにのみ使用する必要があります。注：この機能は、Angular、React、VueなどのJavaScriptフレームワークのインラインポップオーバーにのみ適用されます。
Attribute	`keep-contents-mounted`
Type	`boolean`
Default	`false`

keyboardClose

Description	`true`の場合、オーバーレイが表示されたときにキーボードが自動的に解除されます。
Attribute	`keyboard-close`
Type	`boolean`
Default	`true`

leaveAnimation

Description	ポップオーバーが解除されたときに使用するアニメーションです。
Attribute	`undefined`
Type	`((baseEl: any, opts?: any) => Animation) ｜ undefined`
Default	`undefined`

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。
Attribute	`mode`
Type	`"ios" ｜ "md"`
Default	`undefined`

reference

Description	ポップオーバーを何に対して相対的に配置するかを記述します。もし `"trigger"` ならば、ポップオーバーはトリガーボタンに相対して配置されます。イベントを渡すと、event.targetによって決定されます。もし `"event"` ならば、ポップオーバーはトリガーアクションのx/y座標に相対的に配置されます。イベントを渡す場合、これはevent.clientXとevent.clientYを介して決定されます。
Attribute	`reference`
Type	`"event" ｜ "trigger"`
Default	`'trigger'`

showBackdrop

Description	`true`の場合、ポップオーバーの後ろに背景が表示されます。このプロパティは、ポップオーバーが表示されたときに背景が画面を暗くするかどうかを制御します。このプロパティは、背景がアクティブであるかどうか、またはDOMに存在するかどうかを制御しません。
Attribute	`show-backdrop`
Type	`boolean`
Default	`true`

side

Description	ポップオーバーを `reference` ポイントのどちら側に配置するかを記述します。`"start"` と `"end"` の値はRTLを意識しており、`"left"` と `"right"` の値はそうではない。
Attribute	`side`
Type	`"bottom" ｜ "end" ｜ "left" ｜ "right" ｜ "start" ｜ "top"`
Default	`'bottom'`

size

Description	ポップオーバーの幅を計算する方法を記述します。もし `"cover"` ならば、ポップオーバーの幅はトリガーの幅と一致します。auto"` の場合、ポップオーバーの幅はポップオーバー内のコンテンツによって決定される。
Attribute	`size`
Type	`"auto" ｜ "cover"`
Default	`'auto'`

translucent

Description	`true`の場合、ポップオーバーは半透明になります。modeが `"ios"` で、デバイスが `backdrop-filter` をサポートしている場合にのみ適用されます。
Attribute	`translucent`
Type	`boolean`
Default	`false`

trigger

Description	ポップオーバーを開かせるトリガー要素に対応するIDです。trigger-action`プロパティを使用して、ポップオーバーを開くためのインタラクションをカスタマイズすることができます。
Attribute	`trigger`
Type	`string ｜ undefined`
Default	`undefined`

triggerAction

Description	どのようなトリガーとの相互作用でポップオーバーを開くべきかを記述します。 `trigger`プロパティが `undefined` の場合は適用されません。`"click"` の場合、トリガーが左クリックされたときにポップオーバーが表示されます。`"hover"` の場合、ポインタがトリガーの上に乗ったときにポップオーバーが表示されます。コンテキストメニューの場合、デスクトップでは右クリック、モバイルでは長押しでポップオーバーが表示されます。これは、デバイスの通常のコンテキストメニューが表示されるのを防ぐことにもなります。
Attribute	`trigger-action`
Type	`"click" ｜ "context-menu" ｜ "hover"`
Default	`'click'`

イベント

Name	Description
`didDismiss`	ポップオーバーが解散した後に発行されます。ionPopoverDidDismissの略記です。
`didPresent`	ポップオーバーが提示された後に発行されます。ionPopoverWillDismissの略記です。
`ionPopoverDidDismiss`	ポップオーバーが解除された後に発行されます。
`ionPopoverDidPresent`	ポップオーバーが表示された後に発行されます。
`ionPopoverWillDismiss`	ポップオーバーが解除される前に発行されます。
`ionPopoverWillPresent`	ポップオーバーが表示される前に発行されます。
`willDismiss`	ポップオーバーが解散する前に発行されます。ionPopoverWillDismissの略記です。
`willPresent`	ポップオーバーが提示される前に発行されます。ionPopoverWillPresentの略記です。

メソッド

dismiss

Description	ポップオーバーオーバーレイが提示された後、それを解除します。
Signature	`dismiss(data?: any, role?: string, dismissParentPopover?: boolean) => Promise<boolean>`

onDidDismiss

Description	ポップオーバーが解除されたタイミングを解決するPromiseを返します。
Signature	`onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

onWillDismiss

Description	ポップオーバーが解除されるタイミングを解決するPromiseを返します。
Signature	`onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>`

present

Description	ポップオーバーが作成された後に、ポップオーバーを表示します。開発者は、マウス、タッチ、またはポインタイベントを渡すことで、そのイベントがディスパッチされた場所と相対的にポップオーバーを配置することができます。
Signature	`present(event?: MouseEvent ｜ TouchEvent ｜ PointerEvent ｜ CustomEvent) => Promise<void>`

CSS Shadow Parts

Name	Description
`arrow`	参照要素を指し示す矢印。`ios` mode時のみ適用される。
`backdrop`	ion-backdrop`要素です。
`content`	デフォルトslotのラッパー要素です。

CSSカスタムプロパティ

Name	Description
`--backdrop-opacity`	背景の不透明度
`--background`	ポップオーバーの背景
`--box-shadow`	ポップオーバーのボックスシャドウ
`--height`	ポップオーバーの高さ
`--max-height`	ポップオーバーの最大の高さ
`--max-width`	ポップオーバーの最大幅
`--min-height`	ポップオーバーの高さの最小値
`--min-width`	ポップオーバーの最小幅
`--offset-x`	ポップオーバーをX軸方向に移動させる量
`--offset-y`	ポップオーバーをY軸方向に移動させる量を指定します。
`--width`	ポップオーバーの幅

Slots

Name	Description
``	コンテンツは `.popover-content` 要素の内部に配置される。

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

いつ使うか​

Angular​

トリガー​

note

isOpen プロパティ​

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

どのような場合に使用するのか​

React​

使い方​

スタイリング​

note

配置​

リファレンス​

Side​

Alignment​

Side and Alignment Demo​

オフセット​

サイズ調整​

ポップオーバーをネスト​

note

Interfaces​

Types​

アクセシビリティ​

キーボードナビゲーション​

Performance​

Innerコンテンツのマウント​

プロパティ​

alignment​

animated​

arrow​

backdropDismiss​

component​

componentProps​

dismissOnSelect​

enterAnimation​

event​

htmlAttributes​

isOpen​

keepContentsMounted​

keyboardClose​

leaveAnimation​

mode​

reference​

showBackdrop​

side​

size​

translucent​

trigger​

triggerAction​

イベント​

メソッド​

dismiss​

onDidDismiss​

onWillDismiss​

present​

CSS Shadow Parts​

CSSカスタムプロパティ​

Slots​

Contents

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

いつ使うか

Angular

トリガー

isOpen プロパティ

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

どのような場合に使用するのか

React

使い方

スタイリング

配置

リファレンス

Side

Alignment

Side and Alignment Demo

オフセット

サイズ調整

ポップオーバーをネスト

Interfaces

Types

アクセシビリティ

キーボードナビゲーション

Performance

Innerコンテンツのマウント

プロパティ

alignment

animated

arrow

backdropDismiss

component

componentProps

dismissOnSelect

enterAnimation

event

htmlAttributes

isOpen

keepContentsMounted

keyboardClose

leaveAnimation

mode

reference

showBackdrop

side

size

translucent

trigger

triggerAction

イベント

メソッド

dismiss

onDidDismiss

onWillDismiss

present

CSS Shadow Parts

CSSカスタムプロパティ

Slots