ion-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 的内部与应用程序的状态紧密耦合。使用单向数据绑定，弹出式窗口只需要关注反应式变量提供的布尔值。使用双向数据绑定，弹出式窗口需要关注布尔值以及反应式变量本身的存在。这会导致不确定的行为，并使应用程序更难调试。

控制器弹出式窗口

ion-popover 也可以通过使用从 Ionic Framework 导入的 popoverController 以编程方式呈现。这使您可以完全控制何时呈现弹出式窗口，超出了内联弹出式窗口提供的自定义功能。

何时使用

我们通常建议您内联编写弹出式窗口，因为它简化了应用程序中的代码量。您只应在内联编写弹出式窗口不切实际的复杂用例中使用 popoverController。使用控制器时，您的弹出式窗口不会提前创建，因此 trigger 和 trigger-action 等属性在这里不适用。此外，嵌套弹出式窗口与控制器方法不兼容，因为在调用 create 方法时，弹出式窗口会自动添加到应用程序的根目录。

React

React 没有控制器，而是一个名为 useIonPopover 的钩子，它的行为类似。请注意，useIonPopover 要求是 <IonApp> 的后代。如果您需要在 <IonApp> 之外使用弹出式窗口，请考虑改用内联弹出式窗口。

用法

控制台

从上面示例中记录的控制台消息将显示在此处。

样式

弹出式窗口在应用程序的根目录中呈现，因此它们覆盖整个应用程序。此行为适用于内联弹出式窗口和从控制器呈现的弹出式窗口。因此，自定义弹出式窗口样式无法作用域到特定组件，因为它们不会应用于弹出式窗口。相反，样式必须全局应用。对于大多数开发人员来说，将自定义样式放在 global.css 中就足够了。

注意

如果您正在构建 Ionic Angular 应用程序，则需要将样式添加到全局样式表文件中。

定位

参考

在呈现弹出式窗口时，Ionic Framework 需要一个参考点来呈现相对于该参考点的弹出式窗口。使用 reference="event"，弹出式窗口将相对于在触发器元素上分派的指针事件的 x-y 坐标呈现。使用 reference="trigger"，弹出式窗口将相对于触发器元素的边界框呈现。

侧边

无论您为参考点选择什么，您都可以通过使用 side 属性将弹出式窗口定位到参考点的 top、right、left 或 bottom。如果您希望侧边根据 LTR 或 RTL 模式切换，也可以使用 start 或 end 值。

对齐

alignment 属性允许您将弹出式窗口的边缘与触发器元素上的相应边缘对齐。使用的确切边缘取决于 side 属性的值。

侧边和对齐演示

偏移量

如果您需要更细粒度的控制弹出式窗口的定位，可以使用 --offset-x 和 --offset-y CSS 变量。例如，--offset-x: 10px 将使您的弹出式窗口内容向右移动 10px。

大小

在创建下拉菜单时，您可能希望弹出框的宽度与触发元素的宽度匹配。在不知道触发器宽度的情况下提前这样做很棘手。您可以将size属性设置为'cover'，Ionic 框架将确保弹出框的宽度与您的触发器元素的宽度匹配。

如果您使用的是popoverController，则必须通过event选项提供一个事件，Ionic 框架将使用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元素之间的导航提供了完整的箭头键支持。最常见的用例是在以桌面为中心的应用程序中用作下拉菜单。除了基本键盘支持外，下表还详细说明了下拉菜单的箭头键支持。

键	描述
ArrowUp	将焦点移至上一个可聚焦元素。
ArrowDown	将焦点移至下一个可聚焦元素。
Home	将焦点移至第一个可聚焦元素。
End	将焦点移至最后一个可聚焦元素。
ArrowLeft	在子弹出框中使用时，关闭弹出框并将焦点返回到父弹出框。
Space、Enter 和 ArrowRight	聚焦触发器元素时，打开关联的弹出框。

性能

安装内部内容

内联ion-popover的内容在关闭时会卸载。如果此内容的渲染成本很高，开发人员可以使用keepContentsMounted属性在弹出框挂载后立即挂载内容。这有助于优化应用程序的响应能力，因为内部内容将在弹出框打开时已经挂载。

开发人员在使用keepContentsMounted时应牢记以下几点

• 此功能应作为最后的手段来解决现有的性能问题。在使用此功能之前，尝试识别并解决性能瓶颈。此外，不要使用它来预测性能问题。

• 此功能仅在使用 JavaScript 框架时需要。不使用框架的开发人员可以将要渲染的内容传递到弹出框，并且内容将自动渲染。

• 此功能仅适用于内联弹出框。使用popoverController创建的弹出框不会提前创建，因此内部内容也不会创建。

• 内部组件上的任何 JavaScript 框架生命周期钩子将在弹出框挂载后立即运行，而不是弹出框呈现时。

属性

alignment

描述	描述如何将弹出框内容与reference点对齐。对于ios模式，默认为"center"；对于md模式，默认为"start"。
属性	alignment
类型	"center" ｜ "end" ｜ "start" ｜ undefined
默认值	undefined

animated

描述	如果为true，弹出框将进行动画处理。
属性	animated
类型	boolean
默认值	true

arrow

描述	如果为true，弹出框将在ios模式下显示一个指向reference的箭头。在md模式下不适用。
属性	arrow
类型	boolean
默认值	true

backdropDismiss

描述	如果为true，单击背景时将关闭弹出框。
属性	backdrop-dismiss
类型	boolean
默认值	true

component

描述	在弹出框内显示的组件。如果您没有使用 JavaScript 框架，则只需要使用它。否则，您可以直接将组件插入到ion-popover中。
属性	component
类型	Function ｜ HTMLElement ｜ null ｜ string ｜ undefined
默认值	undefined

componentProps

描述	要传递给弹出框组件的数据。如果您没有使用 JavaScript 框架，则只需要使用它。否则，您可以直接在组件上设置 props。
属性	undefined
类型	undefined ｜ { [key: string]: any; }
默认值	undefined

dismissOnSelect

描述	如果为true，单击内容时将自动关闭弹出框。
属性	dismiss-on-select
类型	boolean
默认值	false

enterAnimation

描述	呈现弹出框时使用的动画。
属性	undefined
类型	((baseEl: any, opts?: any) => Animation) ｜ undefined
默认值	undefined

event

描述	要传递给弹出框动画的事件。
属性	event
类型	any
默认值	undefined

focusTrap

描述	如果为true，则不允许焦点移出此叠加层。如果为false，则允许焦点移出叠加层。 在大多数情况下，此属性应保持为true。将此属性设置为false会导致严重的辅助功能问题，因为依赖辅助技术的用户可能会将焦点移至混乱状态。我们建议仅在绝对必要时将其设置为false。 如果此叠加层从第三方库呈现了一个非 Ionic 叠加层，则开发人员可能希望考虑禁用焦点捕获。开发人员在呈现第三方叠加层时会在 Ionic 叠加层上禁用焦点捕获，然后在关闭第三方叠加层并将焦点移回 Ionic 叠加层时重新启用焦点捕获。
属性	focus-trap
类型	boolean
默认值	true

htmlAttributes

描述	要传递给弹出框的额外属性。
属性	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" 值不是。
属性	side
类型	"bottom" ｜ "end" ｜ "left" ｜ "right" ｜ "start" ｜ "top"
默认值	'bottom'

size

描述	描述如何计算弹出框宽度。如果为"cover"，弹出框宽度将与触发器的宽度匹配。如果为"auto"，弹出框宽度将设置为静态默认值。
属性	size
类型	"auto" ｜ "cover"
默认值	'auto'

translucent

描述	如果为true，弹出框将是半透明的。仅在模式为"ios"且设备支持backdrop-filter时适用。
属性	translucent
类型	boolean
默认值	false

触发器

描述	与触发器元素相对应的 ID，触发器元素会导致弹出框打开。使用 trigger-action 属性自定义导致弹出框打开的交互行为。
属性	触发器
类型	字符串 ｜ 未定义
默认值	undefined

触发器动作

描述	描述与触发器的何种交互行为会导致弹出框打开。当 trigger 属性为 undefined 时，不适用。如果为 "click"，则在左键单击触发器时会显示弹出框。如果为 "hover"，则在指针悬停在触发器上时会显示弹出框。如果为 "context-menu"，则在桌面环境中右键单击触发器或在移动设备上长按触发器时会显示弹出框。这还会阻止设备的正常上下文菜单出现。
属性	触发器-动作
类型	"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(data?: any, role?: string, dismissParentPopover?: boolean) => Promise<boolean>

onDidDismiss

描述	返回一个承诺，该承诺在弹出框关闭时解析。
签名	onDidDismiss<T = any>() => Promise<OverlayEventDetail<T>>

onWillDismiss

描述	返回一个承诺，该承诺在弹出框即将关闭时解析。
签名	onWillDismiss<T = any>() => Promise<OverlayEventDetail<T>>

显示

描述	在弹出框创建后显示弹出框覆盖层。开发人员可以传递鼠标、触摸或指针事件，以便将弹出框相对于该事件分发的位置进行定位。
签名	present(event?: MouseEvent ｜ TouchEvent ｜ PointerEvent ｜ CustomEvent) => Promise<void>

CSS 阴影部分

名称	描述
arrow	指向参考元素的箭头。仅在 ios 模式下适用。
背景	ion-backdrop 元素。
内容	默认插槽的包装元素。

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 元素内部。