ion-popover
弹出窗口是出现在当前页面顶部的对话框。它可以用于任何事情，但通常它用于不适合导航栏的溢出操作。
¥A Popover is a dialog that appears on top of the current page. It can be used for anything, but generally it is used for overflow actions that don't fit in the navigation bar.
ion-popover 有两种使用方法：内联或通过 popoverController。每种方法都有不同的注意事项，因此请务必使用最适合你的用例的方法。
¥There are two ways to use ion-popover: inline or via the popoverController. Each method comes with different considerations, so be sure to use the approach that best fits your use case.
内联弹出窗口
¥Inline Popovers
可以通过直接在模板中编写组件来使用 ion-popover。这减少了显示弹出窗口所需连接的处理程序的数量。
¥ion-popover can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the popover.
当将 ion-popover 与 Angular、React 或 Vue 结合使用时，你传入的组件将在弹出窗口关闭时被销毁。由于此功能是由 JavaScript 框架提供的，因此在没有 JavaScript 框架的情况下使用 ion-popover 不会破坏你传入的组件。如果这是必需的功能，我们建议使用 popoverController。
¥When using ion-popover with Angular, React, or Vue, the component you pass in will be destroyed when the popover is dismissed. As this functionality is provided by the JavaScript framework, using ion-popover without a JavaScript framework will not destroy the component you passed in. If this is a needed functionality, we recommend using the popoverController instead.
何时使用
¥When to use
当你不想显式连接单击事件来打开弹出窗口时，使用内联弹出窗口非常有用。例如，你可以使用 trigger 属性指定一个按钮，单击该按钮时应显示弹出窗口。你还可以使用 trigger-action 属性来自定义当左键单击、右键单击或悬停在触发器上时是否应显示弹出窗口。
¥Using a popover inline is useful when you do not want to explicitly wire up click events to open the popover. For example, you can use the trigger property to designate a button that should present the popover when clicked. You can also use the trigger-action property to customize whether the popover should be presented when the trigger is left clicked, right clicked, or hovered over.
如果你需要对弹出框的显示和关闭时间进行细粒度控制，我们建议你使用 popoverController。
¥If you need fine grained control over when the popover is presented and dismissed, we recommend you use the popoverController.
Angular
由于你传入的组件需要在弹出窗口出现时创建，并在弹出窗口关闭时销毁，因此我们无法在内部使用 <ng-content> 投影内容。相反，我们使用 <ng-container>，它期望传入 <ng-template>。因此，当传入组件时，你需要将其封装在 <ng-template> 中：
¥Since the component you passed in needs to be created when the popover is presented and destroyed when the popover is dismissed, we are unable to project the content using <ng-content> internally. Instead, we use <ng-container> which expects an <ng-template> to be passed in. As a result, when passing in your component you will need to wrap it in an <ng-template>:
<ion-popover [isOpen]="isPopoverOpen">
<ng-template>
<app-popover-content></app-popover-content>
</ng-template>
</ion-popover>
触发器
¥Triggers
内联 ion-popover 的触发器是在交互时打开弹出窗口的元素。可以通过设置 trigger-action 属性来自定义交互行为。请注意，trigger-action="context-menu" 将阻止打开系统的默认上下文菜单。
¥A trigger for an inline ion-popover is the element that will open a popover when interacted with. The interaction behavior can be customized by setting the trigger-action property. Note that trigger-action="context-menu" will prevent your system's default context menu from opening.
使用 popoverController 时触发器不适用，因为 ion-popover 不是提前创建的。
¥Triggers are not applicable when using the popoverController because the ion-popover is not created ahead of time.
isOpen 属性
¥isOpen Property
还可以通过将 isOpen 属性设置为 true 来打开内联弹出窗口。如果你需要对弹出框进行比触发器更细粒度的控制，则可以使用此方法。
¥Inline popovers can also be opened by setting the isOpen property to true. This method can be used if you need finer grained control over the popover than with a trigger.
isOpen 使用单向数据绑定，这意味着当弹出窗口关闭时，它不会自动设置为 false。开发者应该监听 ionPopoverDidDismiss 或 didDismiss 事件并将 isOpen 设置为 false。这样做的原因是它阻止了 ion-popover 的内部与应用的状态紧密耦合。通过单向数据绑定，弹出窗口只需要关心反应变量提供的布尔值。对于双向数据绑定，弹出窗口需要关注布尔值以及反应变量本身的存在。这可能会导致不确定的行为并使应用更难以调试。
¥isOpen uses a one-way data binding, meaning it will not automatically be set to false when the popover is dismissed. Developers should listen for the ionPopoverDidDismiss or didDismiss event and set isOpen to false. The reason for this is it prevents the internals of ion-popover from being tightly coupled with the state of the application. With a one way data binding, the popover only needs to concern itself with the boolean value that the reactive variable provides. With a two way data binding, the popover needs to concern itself with both the boolean value as well as the existence of the reactive variable itself. This can lead to non-deterministic behaviors and make applications harder to debug.
控制器弹出窗口
¥Controller Popovers
ion-popover 也可以通过使用从 Ionic Framework 导入的 popoverController 以编程方式渲染。这使你可以完全控制何时在上方显示弹出窗口，并且超出内联弹出窗口为你提供的自定义范围。
¥ion-popover can also be presented programmatically by using the popoverController imported from Ionic Framework. This allows you to have complete control over when a popover is presented above and beyond the customization that inline popovers give you.
何时使用
¥When to use
我们通常建议你内联编写弹出窗口，因为它可以简化应用中的代码量。你应该仅将 popoverController 用于复杂的用例，在这些用例中编写内联弹出框是不切实际的。使用控制器时，不会提前创建弹出窗口，因此 trigger 和 trigger-action 等属性在此不适用。此外，嵌套弹出窗口与控制器方法不兼容，因为调用 create 方法时弹出窗口会自动添加到应用的根目录中。
¥We typically recommend that you write your popovers inline as it streamlines the amount of code in your application. You should only use the popoverController for complex use cases where writing a popover inline is impractical. When using a controller, your popover is not created ahead of time, so properties such as trigger and trigger-action are not applicable here. In addition, nested popovers are not compatible with the controller approach because the popover is automatically added to the root of your application when the create method is called.
React
React 有一个名为 useIonPopover 的钩子，而不是控制器，其行为方式类似。请注意，useIonPopover 要求是 <IonApp> 的后代。如果你需要在 <IonApp> 之外使用弹出框，请考虑使用内联弹出框。
¥Instead of a controller, React has a hook called useIonPopover which behaves in a similar fashion. Note that useIonPopover requires being a descendant of <IonApp>. If you need to use a popover outside of an <IonApp>, consider using an inline popover instead.
用法
¥Usage
ConsoleConsole messages will appear here when logged from the example above.样式
¥Styling
弹出窗口显示在应用的根目录中，因此它们覆盖了整个应用。此行为适用于内联弹出窗口和从控制器渲染的弹出窗口。因此，自定义弹出框样式无法应用于特定组件，因为它们不适用于弹出框。相反，样式必须全局应用。对于大多数开发者来说，将自定义样式放在 global.css 中就足够了。
¥Popovers are presented at the root of your application so they overlay your entire app. This behavior applies to both inline popovers and popovers presented from a controller. As a result, custom popover styles can not be scoped to a particular component as they will not apply to the popover. Instead, styles must be applied globally. For most developers, placing the custom styles in global.css is sufficient.
如果你正在构建 Ionic Angular 应用，则需要将样式添加到全局样式表文件中。
¥If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file.
定位
¥Positioning
参考
¥Reference
渲染弹出框时，Ionic Framework 需要一个参考点来渲染相对于的弹出框。使用 reference="event"，弹出窗口将相对于在触发元素上分派的指针事件的 x-y 坐标渲染。使用 reference="trigger"，弹出窗口将相对于触发元素的边界框渲染。
¥When presenting a popover, Ionic Framework needs a reference point to present the popover relative to. With reference="event", the popover will be presented relative to the x-y coordinates of the pointer event that was dispatched on your trigger element. With reference="trigger", the popover will be presented relative to the bounding box of your trigger element.
端
¥Side
无论你为参考点选择什么，都可以使用 side 属性将弹出框定位到参考点的 top、right、left 或 bottom。如果你希望一侧根据 LTR 或 RTL 模式进行切换，你还可以使用 start 或 end 值。
¥Regardless of what you choose for your reference point, you can position a popover to the top, right, left, or bottom of your reference point by using the side property. You can also use the start or end values if you would like the side to switch based on LTR or RTL modes.
对齐
¥Alignment
alignment 属性允许你将弹出框的边缘与触发元素上的相应边缘对齐。使用的确切边缘取决于 side 属性的值。
¥The alignment property allows you to line up an edge of your popover with a corresponding edge on your trigger element. The exact edge that is used depends on the value of the side property.
侧面和对齐演示
¥Side and Alignment Demo
偏移量
¥Offsets
如果你需要对弹出窗口的位置进行更细粒度的控制，你可以使用 --offset-x 和 --offset-y CSS 变量。例如，--offset-x: 10px 会将你的弹出窗口内容向右移动 10px。
¥If you need finer grained control over the positioning of your popover you can use the --offset-x and --offset-y CSS Variables. For example, --offset-x: 10px will move your popover content to the right by 10px.
尺寸
¥Sizing
制作下拉菜单时，你可能希望弹出框的宽度与触发元素的宽度相匹配。在不提前知道触发宽度的情况下执行此操作是很棘手的。你可以将 size 属性设置为 'cover'，Ionic Framework 将确保弹出窗口的宽度与触发元素的宽度匹配。
¥When making dropdown menus, you may want to have the width of the popover match the width of the trigger element. Doing this without knowing the trigger width ahead of time is tricky. You can set the size property to 'cover' and Ionic Framework will ensure that the width of the popover matches the width of your trigger element.
如果你使用 popoverController，则必须通过 event 选项提供事件，Ionic Framework 将使用 event.target 作为参考元素。有关此模式的示例，请参阅 控制器演示。
¥If you are using the popoverController, you must provide an event via the event option and Ionic Framework will use event.target as the reference element. See the controller demo for an example of this pattern.
嵌套弹出窗口
¥Nested Popovers
使用 ion-popover 内联时，你可以嵌套弹出窗口来创建嵌套下拉菜单。执行此操作时，只会显示第一个弹出窗口上的背景，以便当你打开更多弹出窗口时屏幕不会逐渐变暗。
¥When using ion-popover inline, you can nested popovers to create nested dropdown menus. When doing this, only the backdrop on the first popover will appear so that the screen does not get progressively darker as you open more popovers.
你可以使用 dismissOnSelect 属性在单击弹出窗口内容时自动关闭弹出窗口。单击另一个弹出窗口的触发元素时，此行为不适用。
¥You can use the dismissOnSelect property to automatically close the popover when the popover content has been clicked. This behavior does not apply when clicking a trigger element for another popover.
使用 popoverController 时无法创建嵌套弹出窗口，因为调用 create 方法时弹出窗口会自动添加到应用的根目录中。
¥Nested popovers cannot be created when using the popoverController because the popover is automatically added to the root of your application when the create method is called.
接口
¥Interfaces
你将在下面找到使用 popoverController 时可用的所有选项。调用 popoverController.create() 时应提供这些选项。
¥Below you will find all of the options available to you when using the popoverController. These options should be supplied when calling 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 的所有自定义类型：
¥Below you will find all of the custom types for 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';
无障碍
¥Accessibility
键盘交互
¥Keyboard Interactions
ion-popover 具有基本的键盘支持，可在弹出窗口内的可聚焦元素之间进行导航。下表详细说明了每个键的作用：
¥ion-popover has basic keyboard support for navigating between focusable elements inside of the popover. The following table details what each key does:
| 密钥 | 描述 |
|---|---|
| Tab | 将焦点移至下一个可聚焦元素。 |
| Shift + Tab | 将焦点移至上一个可聚焦元素。 |
| Esc | 关闭弹出窗口。 |
| Space 或 Enter | 单击可聚焦元素。 |
ion-popover 具有完整的箭头键支持，可在具有 button 属性的 ion-item 元素之间导航。最常见的用例是作为桌面应用中的下拉菜单。除了基本键盘支持之外，下表详细介绍了下拉菜单的箭头键支持：
¥ion-popover has full arrow key support for navigating between ion-item elements with the button property. The most common use case for this is as a dropdown menu in a desktop-focused application. In addition to the basic keyboard support, the following table details arrow key support for dropdown menus:
| 密钥 | 描述 |
|---|---|
| ArrowUp | 将焦点移至上一个可聚焦元素。 |
| ArrowDown | 将焦点移至下一个可聚焦元素。 |
| Home | 将焦点移至第一个可聚焦元素。 |
| End | 将焦点移至最后一个可聚焦元素。 |
| ArrowLeft | 在子弹出窗口中使用时，关闭弹出窗口并将焦点返回到父弹出窗口。 |
| Space、Enter 和 ArrowRight | 当聚焦触发元素时，打开关联的弹出窗口。 |
性能
¥Performance
挂载内部内容
¥Mounting Inner Contents
关闭时，内联 ion-popover 的内容将被卸载。如果此内容的渲染成本很高，开发者可以在安装弹出窗口后立即使用 keepContentsMounted 属性来安装该内容。这可以帮助优化应用的响应能力，因为当弹出窗口打开时内部内容已经被安装。
¥The content of an inline ion-popover is unmounted when closed. If this content is expensive to render, developers can use the keepContentsMounted property to mount the content as soon as the popover is mounted. This can help optimize the responsiveness of your application as the inner contents will have already been mounted when the popover opens.
开发者在使用 keepContentsMounted 时应记住以下几点：
¥Developers should keep the following in mind when using keepContentsMounted:
-
此功能应作为解决现有性能问题的最后手段。在使用此功能之前尝试识别并解决性能瓶颈。此外，不要用它来预测性能问题。
¥This feature should be used as a last resort in order to deal with existing performance problems. Try to identify and resolve performance bottlenecks before using this feature. Additionally, do not use this to anticipate performance problems.
-
仅当使用 JavaScript 框架时才需要此功能。不使用框架的开发者可以将要渲染的内容传递到 popover 中，内容将自动渲染。
¥This feature is only needed when using a JavaScript Framework. Developers not using a framework can pass the contents to be rendered into the popover, and the contents will be rendered automatically.
-
此功能仅适用于内联弹出窗口。使用
popoverController创建的弹出窗口不会提前创建，因此内部内容也不会创建。¥This feature only works with inline popovers. Popovers created with the
popoverControllerare not created ahead of time, so the inner contents are not created either. -
内部组件上的任何 JavaScript 框架生命周期钩子都会在弹出窗口安装后立即运行，而不是在弹出窗口显示时运行。
¥Any JavaScript Framework lifecycle hooks on the inner component will run as soon as the popover is mounted, not when the popover is presented.
属性
¥Properties
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' |
事件
¥Events
| 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 |
方法
¥Methods
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 阴影部分
¥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 自定义属性
¥CSS Custom Properties
- iOS
- 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 |
| 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. |