悬停卡片 · HoverCard

通过悬停或聚焦展示内容摘要。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 悬停卡片 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
• 悬停卡片 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 悬停卡片 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 悬停卡片 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 悬停卡片 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Hover Card

HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.

使用建议

• Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.
• Provide a dashed underline on text triggers so users know the element is hoverable.
• Use the hook API (useHoverCard) when you need more control over timing or placement.
• Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.
• 避免：Place critical actions or required information inside a hover card; users may miss content that only appears on hover.
• 避免：Use a hover card when a simple Tooltip or Popover would suffice.
• 避免：Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.
• Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.

主题 API

{
  "targets": [
    {
      "className": "astryx-hover-card"
    }
  ],
  "vars": [
    {
      "name": "--_hovercard-radius",
      "description": "Border radius of the hover card",
      "default": "var(--radius-container)",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "borderRadius",
      "vars": [
        "--_hovercard-radius"
      ]
    }
  ]
}

Hover Card

悬浮卡片显示的组件包装器，在悬停或聚焦时触发更丰富、更大的浮层。

组件结构

• Trigger: The element that opens the hover card on hover or focus: a button, link, or inline text.
• Card: The floating overlay with the preview content, anchored to the trigger.
• Body: The main content area: profile info, link summary, or any rich content.
• Actions: Optional buttons inside the card for follow-up actions like Follow or Message.

useHoverCard

Headless hook for hover-triggered floating cards. Builds on useLayer with hover/focus intent detection, configurable delays, safe hover behavior, and accessible aria-describedby linking. Use for rich previews on hover when you need full control over the trigger or rendered content.

Parameters

Returns

[
  {
    "name": "ref",
    "type": "RefCallback<HTMLElement>",
    "description": "Combined ref that sets both position and interaction on the same trigger element."
  },
  {
    "name": "positionRef",
    "type": "RefCallback<HTMLElement>",
    "description": "Ref for the positioning anchor element. Use when position and interaction live on different elements."
  },
  {
    "name": "interactionRef",
    "type": "RefCallback<HTMLElement>",
    "description": "Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns."
  },
  {
    "name": "anchorId",
    "type": "string",
    "description": "CSS anchor name for advanced positioning cases."
  },
  {
    "name": "describedBy",
    "type": "string",
    "description": "ID to compose into aria-describedby on the trigger."
  },
  {
    "name": "renderHoverCard",
    "type": "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
    "description": "Render function for the anchor-positioned hover card content. The positioning opt-out is excluded: the hover card always derives its position from placement/alignment."
  },
  {
    "name": "show",
    "type": "() => void",
    "description": "Imperatively show the hover card immediately."
  },
  {
    "name": "hide",
    "type": "() => void",
    "description": "Imperatively hide the hover card immediately."
  }
]

使用建议

• Use for rich content previews such as user profiles, entity summaries, and link previews.
• Prefer the HoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.
• 避免：Use for simple text hints: use Tooltip or useTooltip instead.

完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

npm install @heroicons/react@2.2.0