Popover 将其内容渲染在浮动模态框中。如果未通过 props 传递显式锚点，它默认锚定到其父元素。
可以通过 props 控制当 Popover 超出视口边缘时的行为。
用法
在容器旁边渲染一个 Popover。
如果你的组件返回了一个 Popover，它将会显示。要隐藏 Popover，只需从组件的渲染值中省略它即可。
import { useState } from 'react';
import { Button, Popover } from '@wordpress/components';
const MyPopover = () => {
const [ isVisible, setIsVisible ] = useState( false );
const toggleVisible = () => {
setIsVisible( ( state ) => ! state );
};
return (
<Button variant="secondary" onClick={ toggleVisible }>
Toggle Popover!
{ isVisible && <Popover>Popover is toggled!</Popover> }
</Button>
);
};
为了传递显式锚点，你可以使用 anchor prop。在这种情况下，锚点元素应存储在局部状态中，而不是普通的 React ref，以确保在更改时进行响应式更新。
import { useState } from 'react';
import { Button, Popover } from '@wordpress/components';
const MyPopover = () => {
// Use internal state instead of a ref to make sure that the component
// re-renders when the popover's anchor updates.
const [ popoverAnchor, setPopoverAnchor ] = useState();
const [ isVisible, setIsVisible ] = useState( false );
const toggleVisible = () => {
setIsVisible( ( state ) => ! state );
};
return (
<p ref={ setPopoverAnchor }>Popover s anchor</p>
<Button variant="secondary" onClick={ toggleVisible }>
Toggle Popover!
</Button>
{ isVisible && (
<Popover
anchor={ popoverAnchor }
>
Popover is toggled!
</Popover>
) }
);
};
默认情况下，Popovers 会渲染在文档 body 的末尾。如果你希望 Popover 元素渲染到页面的特定位置，你必须在元素树的上层渲染一个 Popover.Slot：
import { createRoot } from 'react-dom/client';
import { Popover } from '@wordpress/components';
import Content from './Content';
const app = document.getElementById( 'app' );
const root = createRoot( app );
root.render(
<div>
<Content />
<Popover.Slot />
</div>
);
Props
该组件接受以下 props。未包含在此集合中的 props 将应用于包裹 Popover 内容的元素。
anchor: Element | VirtualElement | null
Popover 应用作其锚点的元素。它可以是一个 Element，或者 alternatively，一个 VirtualElement——即一个定义了 getBoundingClientRect() 和 ownerDocument 属性的对象。
该元素应存储在状态中而不是普通的 ref 中，以确保在更改时进行响应式更新。
- Required: No
anchorRect: DomRectWithOwnerDocument
Note: this prop is deprecated. Please use the anchor prop instead.
一个扩展了 DOMRect 并带有额外可选 ownerDocument 属性的对象，用于指定固定的 Popover 位置。
- Required: No
anchorRef: Element | PopoverAnchorRefReference | PopoverAnchorRefTopBottom | Range
Note: this prop is deprecated. Please use the anchor prop instead.
用于指定固定的 Popover 位置。它可以是一个 Element、对 element 的 React 引用、一个具有 top 和 bottom 属性（都指向元素）的对象，或者一个 range。
- Required: No
animate: boolean
Whether the popover should animate when opening.
- Required: No
- Default:
true
children: ReactNode
The children elements rendered as the popover’s content.
- Required: Yes
expandOnMobile: boolean
Show the popover fullscreen on mobile viewports.
- Required: No
flip: boolean
Specifies whether the popover should flip across its axis if there isn’t space for it in the normal placement.
When using a ‘top’ placement, the popover will switch to a ‘bottom’ placement. When using a ‘left’ placement, the popover will switch to a ‘right’ placement.
The popover will retain its alignment of ‘start’ or ‘end’ when flipping.
- Required: No
- Default:
true
focusOnMount: ‘firstElement’ | boolean
By default, the first tabbable element in the popover will receive focus when it mounts. This is the same as setting this prop to "firstElement".
Specifying a true value will focus the container instead.
Specifying a false value disables the focus handling entirely (this should only be done when an appropriately accessible substitute behavior exists).
- Required: No
- Default:
"firstElement"
onFocusOutside: ( event: SyntheticEvent ) => void
A callback invoked when the focus leaves the opened popover. This should only be provided in advanced use-cases when a popover should close under specific circumstances (for example, if the new document.activeElement is content of or otherwise controlling popover visibility).
When not provided, the onClose callback will be called instead.
- Required: No
getAnchorRect: ( fallbackReferenceElement: Element | null ) => DomRectWithOwnerDocument
Note: this prop is deprecated. Please use the anchor prop instead.
A function returning the same value as the one expected by the anchorRect prop, used to specify a dynamic popover position.
- Required: No
headerTitle: string
Used to customize the header text shown when the popover is toggled to fullscreen on mobile viewports (see the expandOnMobile prop).
- Required: No
isAlternate: boolean
Note: this prop is deprecated. Please use the variant prop with the 'toolbar' values instead.
Used to enable a different visual style for the popover.
- Required: No
noArrow: boolean
Used to show/hide the arrow that points at the popover’s anchor.
- Required: No
- Default:
true
offset: number | { mainAxis?: number; crossAxis?: number }
The distance (in px) between the anchor and the popover. A number displaces the popover along its main axis; pass an object to also displace it along its cross axis.
- Required: No
onClose: () => void
A callback invoked when the popover should be closed.
- Required: No
placement: ‘top’ | ‘top-start’ | ‘top-end’ | ‘right’ | ‘right-start’ | ‘right-end’ | ‘bottom’ | ‘bottom-start’ | ‘bottom-end’ | ‘left’ | ‘left-start’ | ‘left-end’ | ‘overlay’
Used to specify the popover’s position with respect to its anchor.
overlay is a special case that places the popover over the reference element.
Please note that other placement related props may not behave as excepted.
- Required: No
- Default:
"bottom-start"
position: [yAxis] [xAxis] [optionalCorner]
Note: use the placement prop instead when possible.
Legacy way to specify the popover’s position with respect to its anchor.
Possible values:
yAxis:'top' | 'middle' | 'bottom'xAxis:'left' | 'center' | 'right'corner:'top' | 'right' | 'bottom' | 'left'- Required: No
resize: boolean
Adjusts the size of the popover to prevent its contents from going out of view when meeting the viewport edges.
Note: The resize and shift props are not intended to be used together. Enabling both can cause unexpected behavior.
- Required: No
- Default:
true
shift: boolean
Enables the Popover to shift in order to stay in view when meeting the viewport edges.
Note: The shift and resize props are not intended to be used together. If you enable shift, set resize to false.
- Required: No
- Default:
false
variant: ‘toolbar’ | ‘unstyled’
Specifies the popover’s style.
Leave undefined for the default style. Possible values are:
– unstyled: The popover is essentially without any visible style, it has no background, border, outline or drop shadow, but the popover contents are still displayed.
– toolbar: A style that has no elevation, but a high contrast with other elements. This matches the style of the Toolbar component.
– Required: No