ion-popover

陰影

Popover 是一種顯示在目前頁面上方的對話框。它可以用於任何用途，但通常用於不適合放在導覽列中的溢位動作。

有兩種方法可以使用 ion-popover：內嵌或透過 popoverController。每種方法都有不同的考量，因此請務必使用最適合您使用案例的方法。

內嵌 Popover

您可以透過直接在範本中撰寫元件來使用 ion-popover。這樣可以減少您需要連接以呈現 popover 的處理常式數量。

當將 ion-popover 與 Angular、React 或 Vue 一起使用時，您傳入的元件將在 popover 關閉時被銷毀。由於此功能由 JavaScript 框架提供，因此在沒有 JavaScript 框架的情況下使用 ion-popover 不會銷毀您傳入的元件。如果這是需要的功能，我們建議改用 popoverController。

何時使用

當您不想明確連接點擊事件以開啟 popover 時，內嵌使用 popover 會很有用。例如，您可以使用 trigger 屬性來指定一個按鈕，該按鈕應在點擊時呈現 popover。您也可以使用 trigger-action 屬性來自訂 popover 應在觸發器被左鍵點擊、右鍵點擊或懸停時呈現。

如果您需要對 popover 何時呈現和關閉進行細微的控制，我們建議您使用 popoverController。

Angular

由於您傳入的元件需要在呈現 popover 時建立，並在 popover 關閉時銷毀，因此我們無法在內部使用 <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 的觸發器是在與之互動時會開啟 popover 的元素。可以透過設定 trigger-action 屬性來自訂互動行為。請注意，trigger-action="context-menu" 將阻止您的系統開啟預設的上下文選單。

注意

當使用 popoverController 時，觸發器不適用，因為 ion-popover 不是預先建立的。

isOpen 屬性

也可以透過將 isOpen 屬性設定為 true 來開啟內嵌 popover。如果您需要比觸發器更精細地控制 popover，可以使用此方法。

isOpen 使用單向資料繫結，這表示當 popover 關閉時，它不會自動設定為 false。開發人員應監聽 ionPopoverDidDismiss 或 didDismiss 事件，並將 isOpen 設定為 false。這樣做的原因是它可以防止 ion-popover 的內部與應用程式的狀態緊密耦合。透過單向資料繫結，popover 只需要關心反應變數提供的布林值。透過雙向資料繫結，popover 需要關心布林值以及反應變數本身的存在。這可能會導致非決定性的行為，並使應用程式更難以偵錯。

控制器 Popover

也可以透過使用從 Ionic Framework 匯入的 popoverController 以程式方式呈現 ion-popover。這可讓您完全控制 popover 何時呈現，超出內嵌 popover 為您提供的自訂功能。

何時使用

我們通常建議您內嵌撰寫 popover，因為它可以簡化應用程式中的程式碼量。您應該只在撰寫內嵌 popover 不切實際的複雜用例中使用 popoverController。當使用控制器時，您的 popover 不是預先建立的，因此諸如 trigger 和 trigger-action 之類的屬性在這裡不適用。此外，巢狀 popover 與控制器方法不相容，因為當呼叫 create 方法時，popover 會自動新增至應用程式的根目錄。

React

React 沒有控制器，而是有一個名為 useIonPopover 的 Hook，其行為類似。請注意，useIonPopover 需要是 <IonApp> 的後代。如果您需要在 <IonApp> 之外使用 popover，請考慮改用內嵌 popover。

用法

主控台

當從上面的範例記錄時，主控台訊息將會顯示在這裡。

樣式

Popover 會呈現於應用程式的根目錄，因此它們會覆蓋整個應用程式。此行為適用於內嵌 popover 和從控制器呈現的 popover。因此，自訂 popover 樣式無法限制於特定元件，因為它們不會套用至 popover。相反，樣式必須全域套用。對於大多數開發人員來說，將自訂樣式放在 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。

尺寸

在製作下拉式選單時，您可能會希望彈出視窗的寬度與觸發元素的寬度相符。在不知道觸發元素寬度的情況下執行此操作會比較棘手。您可以將 size 屬性設定為 'cover'，Ionic Framework 會確保彈出視窗的寬度與您的觸發元素寬度相符。

如果您正在使用 popoverController，您必須透過 event 選項提供一個事件，而 Ionic Framework 將會使用 event.target 作為參考元素。請參閱控制器示範以了解此模式的範例。

巢狀彈出視窗

當內嵌使用 ion-popover 時，您可以巢狀彈出視窗來建立巢狀下拉式選單。這樣做時，只會顯示第一個彈出視窗的背景，因此當您開啟更多彈出視窗時，螢幕不會逐漸變暗。

您可以使用 dismissOnSelect 屬性，在點擊彈出視窗內容時自動關閉彈出視窗。此行為不適用於點擊另一個彈出視窗的觸發元素時。

注意

使用 popoverController 時無法建立巢狀彈出視窗，因為在呼叫 create 方法時，彈出視窗會自動新增到應用程式的根目錄。

介面

以下列出使用 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 具有基本的鍵盤支援，可於彈出視窗內的可聚焦元素之間導覽。下表詳細說明了每個按鍵的功能

按鍵	說明
Tab	將焦點移至下一個可聚焦元素。
Shift + Tab	將焦點移至上一個可聚焦元素。
Esc	關閉彈出視窗。
Space 或 Enter	點擊可聚焦元素。

ion-popover 具有完整的方向鍵支援，可在具有 button 屬性的 ion-item 元素之間導覽。這最常見的使用案例是在以桌面為主的應用程式中作為下拉式選單。除了基本的鍵盤支援外，下表詳細說明了下拉式選單的方向鍵支援

按鍵	說明
向上箭頭	將焦點移至上一個可聚焦元素。
向下箭頭	將焦點移至下一個可聚焦元素。
Home	將焦點移至第一個可聚焦元素。
End	將焦點移至最後一個可聚焦元素。
向左箭頭	在子彈出視窗中使用時，關閉彈出視窗並將焦點返回到父彈出視窗。
Space、Enter 和 向右箭頭	當聚焦於觸發元素時，開啟相關聯的彈出視窗。

效能

掛載內部內容

當關閉內嵌 ion-popover 時，其內容會卸載。如果此內容的渲染成本很高，開發人員可以使用 keepContentsMounted 屬性在彈出視窗掛載後立即掛載內容。這可以幫助優化應用程式的反應速度，因為當彈出視窗開啟時，內部內容已經掛載。

開發人員在使用 keepContentsMounted 時應注意以下事項

• 此功能應作為解決現有效能問題的最後手段。請先嘗試找出並解決效能瓶頸，再使用此功能。此外，請勿使用此功能來預期效能問題。

• 只有在使用 JavaScript 框架時才需要此功能。未使用框架的開發人員可以將要渲染的內容傳遞到彈出視窗中，並且內容會自動渲染。

• 此功能僅適用於內嵌彈出視窗。使用 popoverController 建立的彈出視窗不會提前建立，因此內部內容也不會建立。

• 內部元件上的任何 JavaScript 框架生命週期掛鉤都會在彈出視窗掛載時立即執行，而不是在彈出視窗呈現時執行。

屬性

對齊方式

說明	描述如何將彈出視窗內容與 reference 點對齊。對於 ios 模式，預設值為 "center"，對於 md 模式，預設值為 "start"。
屬性	對齊方式
類型	"center" ｜ "end" ｜ "start" ｜ undefined
預設值	undefined

動畫

說明	如果為 true，則彈出視窗將會產生動畫。
屬性	動畫
類型	布林值
預設值	true

箭頭

說明	如果為 true，彈出視窗將會顯示指向 reference 的箭頭，僅於 ios 模式下執行。不適用於 md 模式。
屬性	箭頭
類型	布林值
預設值	true

背景點擊關閉

說明	如果為 true，當點擊背景時，彈出視窗將會關閉。
屬性	背景點擊關閉
類型	布林值
預設值	true

元件

說明	要在彈出視窗內顯示的元件。只有在您未使用 JavaScript 框架時才需要使用此選項。否則，您可以直接將您的元件放入 ion-popover 中。
屬性	元件
類型	函式 ｜ HTMLElement ｜ null ｜ 字串 ｜ undefined
預設值	undefined

元件屬性

說明	要傳遞到彈出視窗元件的資料。只有在您未使用 JavaScript 框架時才需要使用此選項。否則，您可以直接在您的元件上設定屬性。
屬性	undefined
類型	undefined ｜ { [key: string]: any; }
預設值	undefined

點擊選取關閉

說明	如果為 true，當點擊內容時，彈出視窗將會自動關閉。
屬性	點擊選取關閉
類型	布林值
預設值	false

進入動畫

說明	彈出視窗呈現時要使用的動畫。
屬性	undefined
類型	((baseEl: any, opts?: any) => Animation) ｜ undefined
預設值	undefined

事件

說明	要傳遞到彈出視窗動畫的事件。
屬性	事件
類型	any
預設值	undefined

焦點陷阱

說明	如果為 true，焦點將無法移至此覆蓋層之外。如果為 false，焦點將可以移至覆蓋層之外。 在大多數情況下，此屬性應保持設定為 true。將此屬性設定為 false 可能會導致嚴重的無障礙功能問題，因為依賴輔助技術的使用者可能會將焦點移至混亂的狀態。我們建議僅在絕對必要時才將此設定為 false。 如果此覆蓋層呈現來自第三方程式庫的非 Ionic 覆蓋層，開發人員可能會考慮停用焦點陷阱。當呈現第三方覆蓋層時，開發人員將停用 Ionic 覆蓋層上的焦點陷阱，然後在關閉第三方覆蓋層並將焦點移回 Ionic 覆蓋層時重新啟用焦點陷阱。
屬性	焦點陷阱
類型	布林值
預設值	true

html 屬性

說明	要傳遞到彈出視窗的其他屬性。
屬性	undefined
類型	undefined ｜ { [key: string]: any; }
預設值	undefined

已開啟

說明	如果為 true，彈出視窗將會開啟。如果為 false，彈出視窗將會關閉。如果您需要對呈現進行更精細的控制，請使用此選項，否則請使用 popoverController 或 trigger 屬性。請注意：當彈出視窗關閉時，isOpen 不會自動設定回 false。您需要在程式碼中執行此操作。
屬性	已開啟
類型	布林值
預設值	false

保持內容掛載

說明	如果為 true，當建立彈出視窗時，傳遞到 ion-popover 的元件將會自動掛載。即使關閉彈出視窗，元件也會保持掛載。但是，當彈出視窗銷毀時，元件也會被銷毀。此屬性不具反應性，只應在最初建立彈出視窗時使用。 注意：此功能僅適用於 Angular、React 和 Vue 等 JavaScript 框架中的內嵌彈出視窗。
屬性	保持內容掛載
類型	布林值
預設值	false

鍵盤關閉

說明	如果為 true，當呈現覆蓋層時，鍵盤將會自動關閉。
屬性	鍵盤關閉
類型	布林值
預設值	true

離開動畫

說明	關閉彈出視窗時要使用的動畫。
屬性	undefined
類型	((baseEl: any, opts?: any) => Animation) ｜ undefined
預設值	undefined

模式

說明	模式決定要使用的平台樣式。
屬性	模式
類型	"ios" ｜ "md"
預設值	undefined

參考

說明	描述彈出視窗要相對於什麼位置。如果為 "trigger"，彈出視窗將會相對於觸發按鈕定位。如果傳遞事件，則會透過 event.target 確定。如果為 "event"，彈出視窗將會相對於觸發動作的 x/y 座標定位。如果傳遞事件，則會透過 event.clientX 和 event.clientY 確定。
屬性	參考
類型	"event" ｜ "trigger"
預設值	'trigger'

顯示背景

說明	如果為 true，彈出視窗後面將會顯示背景。此屬性控制在呈現彈出視窗時，背景是否會使螢幕變暗。它不控制背景是否處於活動狀態或是否存在於 DOM 中。
屬性	顯示背景
類型	布林值
預設值	true

側邊

說明	描述彈出視窗要放置在 reference 點的哪一側。"start" 和 "end" 值是 RTL 感知的，而 "left" 和 "right" 值則不是。
屬性	側邊
類型	"bottom" ｜ "end" ｜ "left" ｜ "right" ｜ "start" ｜ "top"
預設值	'bottom'

大小

說明	描述如何計算彈出視窗寬度。如果為 "cover"，彈出視窗寬度將會與觸發元素的寬度相符。如果為 "auto"，彈出視窗寬度將會設定為靜態預設值。
屬性	大小
類型	"auto" ｜ "cover"
預設值	'auto'

半透明

說明	如果為 true，彈出視窗將會是半透明的。僅當模式為 "ios" 且裝置支援 backdrop-filter 時適用。
屬性	半透明
類型	布林值
預設值	false

觸發

說明	一個對應到觸發彈出視窗開啟的觸發元素的 ID。 使用 trigger-action 屬性來自訂導致彈出視窗開啟的互動行為。
屬性	trigger
類型	字串 ｜ 未定義
預設值	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 Shadow Parts

名稱	說明
箭頭	指向參考元素的箭頭。僅適用於 ios 模式。
backdrop	ion-backdrop 元素。
content	預設插槽的包裝元素。

CSS 自訂屬性

iOS

名稱	說明
--backdrop-opacity	背景遮罩的不透明度
--background	彈出視窗的背景
--box-shadow	彈出視窗的陰影
--height	彈出視窗的高度
--max-height	彈出視窗的最大高度
--max-width	彈出視窗的最大寬度
--min-height	彈出視窗的最小高度
--min-width	彈出視窗的最小寬度
--offset-x	在 X 軸上移動彈出視窗的距離
--offset-y	在 Y 軸上移動彈出視窗的距離
--width	彈出視窗的寬度

MD

名稱	說明
--backdrop-opacity	背景遮罩的不透明度
--background	彈出視窗的背景
--box-shadow	彈出視窗的陰影
--height	彈出視窗的高度
--max-height	彈出視窗的最大高度
--max-width	彈出視窗的最大寬度
--min-height	彈出視窗的最小高度
--min-width	彈出視窗的最小寬度
--offset-x	在 X 軸上移動彈出視窗的距離
--offset-y	在 Y 軸上移動彈出視窗的距離
--width	彈出視窗的寬度

插槽

名稱	說明
``	內容放置在 .popover-content 元素內。