Ordo UI
组件Overlays

Popover

@mox-hub/ui 组件 · Overlays · canonical

popover@mox-hub/uiOverlayscanonicalsrc/components/popover.tsx

变体轴

size
smdefaultlgxl宽度档:16 / 18 / 20 / 24rem
变体演示popover

Props API

Prop类型默认值说明
defaultOpenboolean—Whether the popover is initially open.
openboolean—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.
actionsRefReact.RefObject<PopoverRootActions>—A ref to imperative actions.
modalboolean | "trap-focus"—Determines if the popover enters a modal state when open.
triggerIdstring—ID of the trigger that the popover is associated with.
defaultTriggerIdstring—ID of the trigger that the popover is associated with.
handlePopoverHandle<unknown>—A handle to associate the popover with a trigger.
childrenReact.ReactNode | PayloadChildRenderFunction<unknown>—The content of the popover.

源码

packages/ui/src/components/popover.tsx
"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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

点击触发的浮层容器,由 Popover、Trigger、Content 组合;表单与筛选面板常用,注意焦点管理。