组件Overlays
Popover
@mox-hub/ui 组件 · Overlays · canonical
popover@mox-hub/uiOverlayscanonicalsrc/components/popover.tsx变体轴
sizesmdefaultlgxl宽度档:16 / 18 / 20 / 24rem
变体演示popover
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| defaultOpen | boolean | — | Whether the popover is initially open. |
| open | boolean | — | Whether the popover is currently open. |
| onOpenChange | (open: boolean, eventDetails: PopoverRoot.ChangeEventDetails) => void | — | Event handler called when the popover is opened or closed. |
| onOpenChangeComplete | (open: boolean) => void | — | Event handler called after any animations complete when the popover is opened or closed. |
| actionsRef | React.RefObject<PopoverRootActions> | — | A ref to imperative actions. |
| modal | boolean | "trap-focus" | — | Determines if the popover enters a modal state when open. |
| triggerId | string | — | ID of the trigger that the popover is associated with. |
| defaultTriggerId | string | — | ID of the trigger that the popover is associated with. |
| handle | PopoverHandle<unknown> | — | A handle to associate the popover with a trigger. |
| children | React.ReactNode | PayloadChildRenderFunction<unknown> | — | The content of the popover. |
源码
"use client"
import * as React from "react"
import { Popover as PopoverPrimitive } from "@base-ui/react/popover"
import { cn } from "../lib/utils"
import { SURFACE_POPOVER_CLASS } from "./menu-styles"
/** 宽度档(审计 P2-04):默认档保持既有 18rem,其余沿用 HoverCard 的四档词表。 */
const POPOVER_WIDTH_CLASS = {
sm: "w-64",
default: "w-72",
lg: "w-80",
xl: "w-96",
} as const
function Popover({ ...props }: PopoverPrimitive.Root.Props) {
return <PopoverPrimitive.Root data-slot="popover" {...props} />
}
function PopoverTrigger({ ...props }: PopoverPrimitive.Trigger.Props) {
return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />
}
function PopoverContent({
className,
align = "center",
alignOffset = 0,
side = "bottom",
sideOffset = 4,
size = "default",
...props
}: PopoverPrimitive.Popup.Props &
Pick<
PopoverPrimitive.Positioner.Props,
"align" | "alignOffset" | "side" | "sideOffset"
> & {
/** 宽度档:sm 16rem / default 18rem / lg 20rem / xl 24rem */
size?: keyof typeof POPOVER_WIDTH_CLASS
}) {
return (
<PopoverPrimitive.Portal>
<PopoverPrimitive.Positioner
align={align}
alignOffset={alignOffset}
side={side}
sideOffset={sideOffset}
className="isolate z-modal"
>
<PopoverPrimitive.Popup
data-slot="popover-content"
className={cn(
"z-modal flex max-h-[var(--available-height)] max-w-[calc(100vw-2rem)] origin-(--transform-origin) flex-col gap-4 overflow-y-auto overscroll-contain p-4 text-sm outline-hidden duration-fast",
POPOVER_WIDTH_CLASS[size],
"data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
SURFACE_POPOVER_CLASS,
className
)}
{...props}
/>
</PopoverPrimitive.Positioner>
</PopoverPrimitive.Portal>
)
}
function PopoverHeader({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
data-slot="popover-header"
className={cn("flex flex-col gap-1 text-sm", className)}
{...props}
/>
)
}
function PopoverTitle({ className, ...props }: PopoverPrimitive.Title.Props) {
return (
<PopoverPrimitive.Title
data-slot="popover-title"
className={cn("font-medium", className)}
{...props}
/>
)
}
function PopoverDescription({
className,
...props
}: PopoverPrimitive.Description.Props) {
return (
<PopoverPrimitive.Description
data-slot="popover-description"
className={cn("text-muted-foreground", className)}
{...props}
/>
)
}
// 项目扩展:锚点容器(历史 API)
function PopoverAnchor({ children, ...props }: React.ComponentProps<"div">) {
return (
<div data-slot="popover-anchor" {...props}>
{children}
</div>
)
}
export {
Popover,
PopoverAnchor,
PopoverContent,
PopoverDescription,
PopoverHeader,
PopoverTitle,
PopoverTrigger,
}
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
点击触发的浮层容器,由 Popover、Trigger、Content 组合;表单与筛选面板常用,注意焦点管理。