Popover
Popover 是一个 非模态 对话框，它漂浮在其显示区域周围。它通常用于在某物之上显示额外的丰富内容。
安装
npx nextui-cli@latest add popover
以上命令仅用于单独安装。如果 @nextui-org/react 已全局安装，则可以跳过此步骤。
导入
NextUI 导出 3 个与弹出框相关的组件
- Popover: 用于显示弹出框的主要组件。
- PopoverTrigger: 触发弹出框的组件。
- PopoverContent: 包含弹出框内容的组件。
使用
使用箭头
颜色
位置
偏移
受控
标题属性
为了确保弹出框向辅助技术显示正确的标题，您应该在 PopoverContent 组件上使用 titleProps 属性。要使用此属性，您必须将一个函数作为子元素传递。
使用表单
Popover 处理弹出框内容中的焦点。这意味着您可以毫无问题地将弹出框与表单元素一起使用。当弹出框关闭时，焦点将返回到触发器。
注意：您可以将
autoFocus属性添加到第一个Input组件，以便在弹出框打开时将其聚焦。
背景
Popover 组件有一个 backdrop 属性，用于在弹出框后面显示背景。背景可以是 transparent、opaque 或 blur。默认值为 transparent。
自定义动画
Popover 提供了一个 motionProps 属性来定制 enter / exit 动画。
了解更多关于 Framer motion 变体的信息 这里.
自定义触发器
插槽
- base: 主要的 popover 插槽，它包裹 popover 内容并包含箭头作为伪元素 (::before)。
- trigger: popover 触发器插槽，它有一些小的样式来确保触发器正常工作。
- backdrop: 背景插槽，它包含背景样式。
- 内容: 内容插槽，包含弹出框的内容。
自定义样式
您可以通过将自定义 Tailwind CSS 类传递给组件插槽来自定义 Popover 组件。
数据属性
Popover 在 PopoverContent 元素上具有以下属性
- data-open: 当弹出框打开时。基于弹出框状态。
- data-placement: 弹出框的位置。基于
placement属性。箭头元素根据此属性定位。 - data-focus: 当弹出框被聚焦时。基于 useFocusRing。
- data-focus-visible: 当弹出框使用键盘获得焦点时。基于 useFocusRing.
无障碍性
- 触发器和弹出框通过 ARIA 自动关联语义。
- 弹出框之外的内容在弹出框打开时对辅助技术隐藏。
- 在弹出框外部交互或按下 Escape 键时，弹出框会关闭。
- 焦点在挂载时移动到弹出框内，并在卸载时恢复到触发元素。
- 弹出框相对于触发元素定位，并自动翻转和调整以避免与浏览器窗口边缘重叠。
- 在弹出框之外阻止滚动，以避免意外地重新定位或关闭弹出框。
API
Popover 属性
| 属性 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| children* | ReactNode[] | 弹出框的内容。通常是 PopoverTrigger 和 PopoverContent. | - |
| size | sm | md | lg | 弹出框内容的字体大小。 | md |
| color | default | primary | secondary | success | warning | danger | 弹出框的颜色主题。 | default |
| radius | none | sm | md | lg | full | 弹出框的圆角。 | lg |
| shadow | none | sm | md | lg | 弹出框的阴影。 | lg |
| backdrop | transparent | opaque | blur | 弹出框的背景类型。 | 透明 |
| 放置位置 | PopoverPlacement | 弹出框相对于其触发器参考的放置位置。 | 底部 |
| 状态 | OverlayTriggerState | 弹出框的受控状态。参见 覆盖状态 | - |
| isOpen | 布尔值 | 弹出框是否默认打开（受控）。 | - |
| defaultOpen | 布尔值 | 弹出框是否默认打开（不受控）。 | - |
| 偏移量（px） | 数字 | 参考和弹出框之间的距离或边距。它用于在内部创建偏移量修饰符。 | 7 |
| 容器填充（px） | 数字 | 应在元素与其周围容器之间应用的放置填充。 | 12 |
| 交叉偏移量（px） | 数字 | 沿元素与其锚元素之间的交叉轴应用的额外偏移量。 | 0 |
| 触发器类型 | dialog | menu | listbox | tree | grid; | 由触发器打开的弹出框类型。 | 对话框 |
| showArrow | 布尔值 | 弹出框是否应该有箭头。 | false |
| shouldFlip | 布尔值 | 是否应在弹出框即将溢出边界区域时更改其位置并翻转。 | true |
| triggerScaleOnOpen | 布尔值 | 弹出框打开时，触发器是否应缩小。 | true |
| shouldBlockScroll | 布尔值 | 是否阻止弹出框外部滚动。 | false |
| isKeyboardDismissDisabled | 布尔值 | 是否应禁用按 Esc 键关闭弹出框。 | false |
| shouldCloseOnBlur | 布尔值 | 失去焦点或焦点移出弹出框时，弹出框是否应关闭。 | false |
| motionProps | MotionProps | 用于修改 framer motion 动画的 props。使用 variants API 创建您自己的动画。 | |
| portalContainer | HTMLElement | 将放置覆盖层门户的容器元素。 | document.body |
| updatePositionDeps | any[] | 强制弹出框位置更新的依赖项。 | [] |
| triggerRef | RefObject<HTMLElement> | 弹出框相对于其定位的元素的 ref。 | - |
| scrollRef | RefObject<HTMLElement> | 弹出框内可滚动区域的 ref。 | overlayRef |
| disableAnimation | 布尔值 | 弹出框是否具有动画效果。 | false |
| classNames | Record<"base"｜ "trigger"｜ "backdrop"｜ "content", string> | 允许为弹出框插槽设置自定义类名。 | - |
Popover 事件
| 属性 | 类型 | 描述 |
|---|---|---|
| onOpenChange | (isOpen: boolean) => void | 弹出框的打开状态发生变化时调用的处理程序。 |
| shouldCloseOnInteractOutside | (e: HTMLElement) => void | 当用户在弹出框 ref 外部与参数元素交互时，如果应调用 onClose，则返回 true。这使您有机会过滤掉不应关闭弹出框的元素的交互。默认情况下，onClose 将始终在覆盖层 ref 外部交互时被调用。 |
| onClose | () => void | 当弹出框应该关闭时调用的处理程序。 |
PopoverTrigger 属性
| 属性 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| children* | ReactNode | 弹出框触发组件，确保传递的子元素可聚焦。用户可以使用键盘 Tab 键切换到它，并且它可以接受 ref。这对可访问性至关重要。 | - |
PopoverContent 属性
| 属性 | 类型 | 描述 | 默认值 |
|---|---|---|---|
| children | ReactNode | 当触发器被按下时显示的内容。 | - |
弹出框类型
弹出框位置
type PopoverPlacement =| "top"| "bottom"| "right"| "left"| "top-start"| "top-end"| "bottom-start"| "bottom-end"| "left-start"| "left-end"| "right-start"| "right-end";
运动属性
export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/
