ion-popover

shadow

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" はシステムのデフォルトのコンテキストメニューを開かせないようにします。

注記

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> の外側でポップオーバーを使用する必要がある場合は、代わりにインラインポップオーバーを使用することを検討してください。

使い方

Console

Console messages will appear here when logged from the example above.

スタイリング

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

注記

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

注記

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	Describes how to align the popover content with the reference point. Defaults to "center" for ios mode, and "start" for md mode.
Attribute	alignment
Type	"center" ｜ "end" ｜ "start" ｜ undefined
Default	undefined

animated

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

arrow

Description	If true, the popover will display an arrow that points at the reference when running in ios mode. Does not apply in md mode.
Attribute	arrow
Type	boolean
Default	true

backdropDismiss

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

component

Description	The component to display inside of the popover. You only need to use this if you are not using a JavaScript framework. Otherwise, you can just slot your component inside of ion-popover.
Attribute	component
Type	Function ｜ HTMLElement ｜ null ｜ string ｜ undefined
Default	undefined

componentProps

Description	The data to pass to the popover component. You only need to use this if you are not using a JavaScript framework. Otherwise, you can just set the props directly on your component.
Attribute	undefined
Type	undefined ｜ { [key: string]: any; }
Default	undefined

dismissOnSelect

Description	If true, the popover will be automatically dismissed when the content has been clicked.
Attribute	dismiss-on-select
Type	boolean
Default	false

enterAnimation

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

event

Description	The event to pass to the popover animation.
Attribute	event
Type	any
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

htmlAttributes

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

isOpen

Description	If true, the popover will open. If false, the popover will close. Use this if you need finer grained control over presentation, otherwise just use the popoverController or the trigger property. Note: isOpen will not automatically be set back to false when the popover 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-popover will automatically be mounted when the popover is created. The component will remain mounted even when the popover is dismissed. However, the component will be destroyed when the popover is destroyed. This property is not reactive and should only be used when initially creating a popover. Note: This feature only applies to inline popovers 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 popover 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

reference

Description	Describes what to position the popover relative to. If "trigger", the popover will be positioned relative to the trigger button. If passing in an event, this is determined via event.target. If "event", the popover will be positioned relative to the x/y coordinates of the trigger action. If passing in an event, this is determined via event.clientX and event.clientY.
Attribute	reference
Type	"event" ｜ "trigger"
Default	'trigger'

showBackdrop

Description	If true, a backdrop will be displayed behind the popover. This property controls whether or not the backdrop darkens the screen when the popover 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

side

Description	Describes which side of the reference point to position the popover on. The "start" and "end" values are RTL-aware, and the "left" and "right" values are not.
Attribute	side
Type	"bottom" ｜ "end" ｜ "left" ｜ "right" ｜ "start" ｜ "top"
Default	'bottom'

size

Description	Describes how to calculate the popover width. If "cover", the popover width will match the width of the trigger. If "auto", the popover width will be set to a static default value.
Attribute	size
Type	"auto" ｜ "cover"
Default	'auto'

translucent

Description	If true, the popover will be translucent. Only applies when the mode is "ios" and the device supports backdrop-filter.
Attribute	translucent
Type	boolean
Default	false

trigger

Description	An ID corresponding to the trigger element that causes the popover to open. Use the trigger-action property to customize the interaction that results in the popover opening.
Attribute	trigger
Type	string ｜ undefined
Default	undefined

triggerAction

Description	Describes what kind of interaction with the trigger that should cause the popover to open. Does not apply when the trigger property is undefined. If "click", the popover will be presented when the trigger is left clicked. If "hover", the popover will be presented when a pointer hovers over the trigger. If "context-menu", the popover will be presented when the trigger is right clicked on desktop and long pressed on mobile. This will also prevent your device's normal context menu from appearing.
Attribute	trigger-action
Type	"click" ｜ "context-menu" ｜ "hover"
Default	'click'

イベント

Name	Description	Bubbles
didDismiss	Emitted after the popover has dismissed. Shorthand for ionPopoverDidDismiss.	true
didPresent	Emitted after the popover has presented. Shorthand for ionPopoverWillDismiss.	true
ionPopoverDidDismiss	Emitted after the popover has dismissed.	true
ionPopoverDidPresent	Emitted after the popover has presented.	true
ionPopoverWillDismiss	Emitted before the popover has dismissed.	true
ionPopoverWillPresent	Emitted before the popover has presented.	true
willDismiss	Emitted before the popover has dismissed. Shorthand for ionPopoverWillDismiss.	true
willPresent	Emitted before the popover has presented. Shorthand for ionPopoverWillPresent.	true

メソッド

dismiss

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

onDidDismiss

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

onWillDismiss

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

present

Description	Present the popover overlay after it has been created. Developers can pass a mouse, touch, or pointer event to position the popover relative to where that event was dispatched.
Signature	present(event?: MouseEvent ｜ TouchEvent ｜ PointerEvent ｜ CustomEvent) => Promise<void>

CSS Shadow Parts

Name	Description
arrow	The arrow that points to the reference element. Only applies on ios mode.
backdrop	The ion-backdrop element.
content	The wrapper element for the default slot.

CSSカスタムプロパティ

iOS

Name	Description
--backdrop-opacity	Opacity of the backdrop
--background	Background of the popover
--box-shadow	Box shadow of the popover
--height	Height of the popover
--max-height	Maximum height of the popover
--max-width	Maximum width of the popover
--min-height	Minimum height of the popover
--min-width	Minimum width of the popover
--offset-x	The amount to move the popover by on the x-axis
--offset-y	The amount to move the popover by on the y-axis
--width	Width of the popover

MD

Name	Description
--backdrop-opacity	Opacity of the backdrop
--background	Background of the popover
--box-shadow	Box shadow of the popover
--height	Height of the popover
--max-height	Maximum height of the popover
--max-width	Maximum width of the popover
--min-height	Minimum height of the popover
--min-width	Minimum width of the popover
--offset-x	The amount to move the popover by on the x-axis
--offset-y	The amount to move the popover by on the y-axis
--width	Width of the popover

Slots

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