Ordo UI
组件Overlays

HoverCard

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

hover-card@mox-hub/uiOverlayscanonicalsrc/components/hover-card.tsx

变体轴

size
smmdlgxl
变体演示hover-card

Props API

Prop类型默认值说明
defaultOpenboolean—Whether the preview card is initially open.
openboolean—Whether the preview card is currently open.
onOpenChange(open: boolean, eventDetails: PreviewCardRoot.ChangeEventDetails) => void—Event handler called when the preview card is opened or closed.
onOpenChangeComplete(open: boolean) => void—Event handler called after any animations complete when the preview card is opened or closed.
actionsRefReact.RefObject<PreviewCardRootActions>—A ref to imperative actions.
handlePreviewCardHandle<unknown>—A handle to associate the preview card with a trigger.
childrenReact.ReactNode | PayloadChildRenderFunction<unknown>—The content of the preview card.
triggerIdstring—ID of the trigger that the preview card is associated with.
defaultTriggerIdstring—ID of the trigger that the preview card is associated with.

源码

packages/ui/src/components/hover-card.tsx
import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "../lib/utils"
import { SURFACE_POPOVER_CLASS } from "./menu-styles"

const hoverCardContentVariants = cva(
  `z-modal w-64 max-h-(--available-height) max-w-[calc(100vw-2rem)] overflow-y-auto overscroll-contain p-4 origin-(--transform-origin) text-sm outline-hidden duration-fast 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}`,
  {
    variants: {
      /** 宽度四档,对齐 route-preview 既有覆写值(w-72)与弹层宽度梯度 */
      size: {
        sm: "w-56",
        md: "w-64",
        lg: "w-72",
        xl: "w-80",
      },
    },
    defaultVariants: {
      size: "md",
    },
  }
)

function HoverCard({ ...props }: PreviewCardPrimitive.Root.Props) {
  return <PreviewCardPrimitive.Root data-slot="hover-card" {...props} />
}

function HoverCardTrigger({ ...props }: PreviewCardPrimitive.Trigger.Props) {
  return (
    <PreviewCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
  )
}

function HoverCardContent({
  className,
  size,
  side = "bottom",
  sideOffset = 4,
  align = "center",
  alignOffset = 4,
  ...props
}: PreviewCardPrimitive.Popup.Props &
  VariantProps<typeof hoverCardContentVariants> &
  Pick<
    PreviewCardPrimitive.Positioner.Props,
    "align" | "alignOffset" | "side" | "sideOffset"
  >) {
  return (
    <PreviewCardPrimitive.Portal data-slot="hover-card-portal">
      <PreviewCardPrimitive.Positioner
        align={align}
        alignOffset={alignOffset}
        side={side}
        sideOffset={sideOffset}
        className="isolate z-modal"
      >
        <PreviewCardPrimitive.Popup
          data-slot="hover-card-content"
          className={cn(hoverCardContentVariants({ size }), className)}
          {...props}
        />
      </PreviewCardPrimitive.Positioner>
    </PreviewCardPrimitive.Portal>
  )
}

/**
 * 可选箭头(默认不渲染):显式放进 HoverCardContent children 中才会出现。
 * 样式沿用 repo 内 tooltip 箭头配方,仅换 popover 底色。
 */
function HoverCardArrow({ className, ...props }: PreviewCardPrimitive.Arrow.Props) {
  return (
    <PreviewCardPrimitive.Arrow
      data-slot="hover-card-arrow"
      className={cn(
        "z-modal size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-xs bg-(--surface-popover-bg) fill-(--surface-popover-bg) data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5",
        className
      )}
      {...props}
    />
  )
}

export {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
  HoverCardArrow,
  hoverCardContentVariants,
}

可访问性与 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。

用法说明

悬停预览卡,由 HoverCard、Trigger、Content 组合;触屏无悬停,关键信息不要只放在这里。