组件Overlays
HoverCard
@mox-hub/ui 组件 · Overlays · canonical
hover-card@mox-hub/uiOverlayscanonicalsrc/components/hover-card.tsx变体轴
sizesmmdlgxl
变体演示hover-card
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| defaultOpen | boolean | — | Whether the preview card is initially open. |
| open | boolean | — | 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. |
| actionsRef | React.RefObject<PreviewCardRootActions> | — | A ref to imperative actions. |
| handle | PreviewCardHandle<unknown> | — | A handle to associate the preview card with a trigger. |
| children | React.ReactNode | PayloadChildRenderFunction<unknown> | — | The content of the preview card. |
| triggerId | string | — | ID of the trigger that the preview card is associated with. |
| defaultTriggerId | string | — | ID of the trigger that the preview card is associated with. |
源码
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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
悬停预览卡,由 HoverCard、Trigger、Content 组合;触屏无悬停,关键信息不要只放在这里。