跳转至

HoverCard 组件合约

合约概览

领域 合约
公开合约 HoverCard 与 children(触发器)、content、label、placement(above)、alignment(center)、delay(300)、hideDelay(200)、focusTrigger、touchTrigger(auto)、isEnabled、isOpen、isDefaultOpen、onOpenChange 以及 hasHoverIndication;目标为 hover-card。useHoverCard 接受相同的 touchTrigger。
行为 一个浮动的卡片,包含丰富且可能可交互的内容,并锚定到触发器。它会在悬停经过 delay 后、获得焦点时,以及 touchTrigger 允许的点击时打开;当指针停留在触发器或卡片上时保持打开,并在离开、按 Escape 或在外部点击时关闭。有 label 时,它是一个命名对话框,触发器在打开时命名(并在触发器的角色支持时进行播报);没有时,则是一个描述触发器的分组。当 touchTrigger="none" 时,触摸永远不会打开它。
终端用户影响 鼠标、键盘和触摸用户都可以打开预览,移入其中使用其操作,并将其关闭;屏幕阅读器用户会将其听为一个命名对话框,在按钮或链接触发器上播报为弹出项,或作为触发器的描述。在默认的 touchTrigger="auto" 下,点击一个执行操作的触发器只会执行该操作。
构建者影响 touchTrigger 回答是否安全地消耗一次点击来显示卡片(DEC-1):在执行操作的触发器上保留默认的 auto,在点击仅显示卡片的地方传入 tap,在点击绝不能显示卡片的地方传入 none。
兼容性/就绪度 无公开 API 变更:touchTrigger 保留其已发布的值及其默认值 auto。有三个实现缺口(参见「当前状态影响」)。
审查检查 拒绝未命名的 dialog、无法被悬停或关闭的卡片(WCAG 1.4.13)、页面中同时关闭底层图层的 Escape、在角色不支持的触发器上设置 aria-expanded,或者在 touchTrigger="auto" 下同时执行触发器操作并显示卡片的点击。
治理规则 WCAG 1.4.13、2.1.1;family:overlay-dismissal;spec:AST-003 FR4;spec:AST-017(生命周期);architecture:public-component-api INV9、INV21;architecture:layer-runtime;architecture:interaction-modality;architecture:component-theming-surface。

在 none 下,触摸或笔点击不会打开卡片。

此表是一个审查投影;以下正文具有权威性。

意图

HoverCard 在不离开当前页面的情况下预览关于触发器的更多信息,例如个人资料或链接摘要。它负责触发器的接线、卡片针对每种输入的打开和关闭时机、卡片的语义以及其表面。消费者用法位于 HoverCard.doc.mjs。

兼容性与迁移

  • 已发布默认值保留:是。touchTrigger 保留其已发布的值及其默认值 auto。被禁用的控件不是动作,因此它会在点击时打开(FR5);该修复会单独作为一个补丁 [fix] 发布。
  • 兼容性类别:没有公开 prop、默认值或样式变更。围绕表达式编写的文本,例如 Edited {when},现在像单个字符串一样渲染带有文本悬停提示的可聚焦触发器 span;这也会作为一个补丁 [fix] 发布。
  • 受控/非受控行为:默认非受控;isOpen 强制状态,受控卡片通过 onOpenChange(false) 报告关闭请求,但不会自行关闭(FR7)。
  • 迁移决策:无

消费者迁移说明属于消费者文档和发布说明。

当前状态影响

  • 悬停计时不使用共享悬停识别器。 该卡片运行自己的显示和隐藏计时器。architecture:interaction-modality INV11 让 useHoverCard 从共享悬停识别器获取其悬停计时。
  • 在另一个文档中打字会被计为键盘输入。 触摸保护只读取页面自身窗口中的文本输入字段。点击触发器后,在 iframe 或画中画窗口中的字段中输入的按键会计为键盘输入,因此关闭对话框返回到那里的焦点会打开卡片(FR12)。
  • 保持仅跟随指针。 只有当指针停留在触发器或卡片上时,卡片才会保持打开。由键盘焦点打开的卡片,一旦指针越过触发器并离开,就会关闭,而触发器保持焦点;用户已通过 Tab 进入的悬停打开的卡片,会在指针离开触发器时关闭,并将焦点抛回页面。WCAG 1.4.13 要求聚焦时显示的内容持续存在,直到焦点移走或用户将其关闭。

所有权边界

拥有

  • 触发器接线、每种输入方式下的打开与关闭行为、卡片语义,以及 hover-card 表面(FR1–FR8)。

不拥有 / 非目标

  • 触发器元素以及卡片的正文和操作——由调用方拥有。
  • 层托管、定位和内联安全传送——由 architecture:layer-runtime 拥有;共享的 Escape 顺序——由 family:overlay-dismissal 拥有。
  • useHoverCard 钩子的公共契约——一个未订立契约的模块;本记录涵盖 HoverCard 的可观察行为。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
弹窗角色 命名的 dialog、group label 使卡片成为命名的 dialog;没有它时卡片是 group。 每张卡片。 group component:HoverCard 稳定 不适用。
焦点触发器 auto、always、never 焦点是否打开卡片:对于可聚焦的触发器,在焦点到达时判定(FR4)、始终或从不。 每个触发器。 auto component:HoverCard 稳定 TypeScript 会拒绝其他值。
触摸触发器 auto、tap、none 消费一次点按来显示卡片是否安全(DEC-1):auto 在点按时显示卡片,除非触发器本身会执行某个操作,禁用控件除外(FR5);tap 在每次点按时显示;none 在任何点按时都不显示。 触控和无悬停的笔输入。 auto component:HoverCard 稳定 TypeScript 会拒绝其他值。

行为与布局契约

ID 不变量 依据
FR1 打开的卡片是一个表面,仅承载 hover-card 目标,每个逻辑边缘均设有内边距,内部包含 content,并使用主题的正文字体。xstyle、className 和 style 均应用于该卡片。 当前源码和测试
FR2 触发器接线:文本子元素——字符串和数字(可以是单个,也可以是多个围绕表达式(如 Edited {when})书写的子元素),其中 false 和 null 之类的空洞会被忽略——会被包裹在一个可聚焦的内联 span 中;元素 children 在 inline-safe 包装器内挂载到其第一个元素上;若第一个元素在挂载后被新的子元素或更换了自身根节点的子元素替换,则会被接线以取代旧元素。 当前源码和测试
FR3 使用 label 时,卡片是名为 label 的 role="dialog"。有标签的触发器通过 aria-controls 命名打开的卡片,并与触发器自身的 aria-controls 合并;只有当其角色支持时(button、link 及类似角色),触发器才会获得 aria-haspopup="dialog" 和 aria-expanded,绝不会出现在无角色元素上;卡片接线期间,每个属性都会替换触发器自身的值;清理时,触发器自身的值会恢复。没有 label 时,卡片是 role="group",触发器的 aria-describedby 会获得卡片的 id。 当前源码和测试
FR4 在支持悬停的指针上,进入触发器会在 delay 毫秒后打开卡片;离开触发器或卡片会在 hideDelay 毫秒后关闭它,而在两者之间移动则保持打开。任何对触发器的聚焦(键盘、指针或程序性)都会按照 focusTrigger 打开它,但轻触留下的焦点、Escape 关闭后的重新聚焦(FR6)以及受控关闭后的重新聚焦(FR7)除外。在 auto 下,焦点是否算数是在其到达时判断的:聚焦在触发器本身,或聚焦在那一刻可聚焦的触发器内部,因此当箭头键到达漫游式 tabindex 成员时,它会打开。 WCAG 1.4.13;测试
FR5 在触摸和触控笔上,一次完整的轻触会在抬起时按照 touchTrigger 打开卡片;变成滚动的触摸则不会。在 auto 下,轻触会打开卡片,除非触发器本身执行操作;aria-disabled 控件或禁用控件的标签不属于操作,因此禁用控件的原因提示会在轻触时打开(DEC-1)。在 tap 下,每次轻触都会打开它;在 none 下,任何轻触都不会打开。轻触卡片内容会保持其打开;在卡片打开时轻触触发器、在外部轻触,或从外部开始滚动,都会关闭它。auto 是否在轻触作用于触发器周围的控件时也保持卡片关闭,仍是未决问题(component:Tooltip OQ1)。 当前源代码和测试
FR6 当可见卡片是其触发器文档中的最顶层图层时,Escape 会通过共享的关闭堆栈将其关闭,因此下方的图层保持打开;渲染到另一个文档(例如 iframe 或 Picture-in-Picture 窗口)中的卡片,会接收在那里按下的 Escape。当焦点在卡片内部时,它会返回触发器,且该重新聚焦不会重新打开卡片。 WCAG 1.4.13;测试
FR7 isOpen 强制卡片显示或隐藏,且 isOpen={true} 会抑制悬停和聚焦隐藏;受控卡片通过调用 onOpenChange(false) 而不隐藏来响应 Escape,在焦点位于卡片内时设置 isOpen={false} 会将焦点返回触发器。isDefaultOpen 在挂载时打开它,仍可关闭。isEnabled={false} 禁用触发器。onOpenChange 报告每次显示和隐藏。 当前源代码和测试
FR8 内容仅在打开时渲染;服务器标记与首次客户端渲染匹配,包括默认打开的卡片。hasHoverIndication(auto:文本子项:字符串和数字,忽略 false 和 null 等空位)会为内联触发器添加悬停提示。 当前源代码和测试
FR11 在打开的 HoverCard 表面内的按压仅作用于该表面内部:它永远不会激活触发器、其周围的可点击容器或标签所指的控件。卡片内的交互内容(链接、按钮)保持其自身的激活。该按压仍会到达页面级监听器,因此表面内的菜单或 Typeahead 继续工作。architecture:layer-runtime INV17 声明了每个图层根部的这一停止行为。 component:Tooltip FR11;architecture:layer-runtime INV17
FR12 在手指或触控笔按下触发器后,键入文本输入字段的按键属于文本输入,而非键盘输入,如 component:Tooltip FR13 所列,因此关闭对话框后返回的焦点不会打开任何卡片(FR4);Tab、Escape、方向键和其他具名按键属于键盘输入。实现差距:另一个文档(例如 iframe 或 Picture-in-Picture 窗口)中的字段不会被识别为文本输入字段,因此在那里键入仍会在关闭对话框返回的焦点上打开卡片(当前状态影响)。 当前源代码和测试

允许的变化

  • AV1 — 内容。 任意内容,包括交互操作。
  • AV2 — 主题样式。 主题可重新设置 hover-card 的样式。

代表性状态

状态 必需不变量 允许的变化
未标记 role="group";触发器由卡片来描述。 内容。
已标记 命名为 dialog;触发器在打开时为其命名,并且仅当该角色支持时才会通告弹出层。 内容。
悬停进入卡片 保持打开;操作可用。 延迟。
从内容中按 Escape 退出 关闭;焦点回到触发器;不重新打开。 —
点按打开 在抬起时打开;在其内容上点按不会将其关闭。 —

转换与优先级顺序

  • ORD1 — 打开状态。 先有 isOpen,再由输入触发器触发。

性能与资源

  • PR1 — 监听器。 未变化的重新渲染不会重新绑定触发器的监听器;元素触发器在每次打开和关闭时都会重新绑定它们;当 onOpenChange 的标识发生变化时,任何触发器都会重新绑定它们。

无障碍契约

  • AR1 — 弹出层语义。 FR3。
  • AR2 — 悬停或聚焦时的内容。 FR4–FR6 使卡片可悬停、可关闭且持久,符合 WCAG 1.4.13,仅指针按住的情况除外(当前状态影响)。

设计关系

结构或状态 设计要求 表示权威 层级角色 组件契约
触发器 打开卡片的调用方元素。 调用方内容 视上下文而定 FR2
卡片 锚定到触发器上的带内边距浮动表面。 当前源代码与公开文档 突出 FR1
主体 卡片内部的调用方内容。 调用方内容 突出 FR1
操作 卡片内可选的调用方按钮。 调用方内容 辅助 FR4

主题化结构

{
  "Trigger": {
    "none": {
      "reason": "intentional: The trigger is the caller's element and carries its own component's target."
    }
  },
  "Card": {"target": "hover-card"},
  "Body": {"inherits": "hover-card"},
  "Actions": {
    "none": {
      "reason": "intentional: Actions are caller-rendered controls that carry their own components' targets."
    }
  }
}

家族与系统关系

  • family:overlay-dismissal 负责 Escape 路由和最上层处理。
  • architecture:layer-runtime 负责托管、定位和 Portal 渲染。
  • architecture:interaction-modality 负责 FR4 使用的焦点模态,并通过 INV11 负责 FR4 的悬停计时来源。
  • architecture:component-theming-surface 负责 hover-card 目标。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1、FR2、FR8 HoverCard.test.tsx 渲染、包装器、混合文本及其悬停提示、传送门、主题字体、SSR、替换触发器以及卡片 xstyle/className/style 测试;针对单一目标、每个逻辑边缘上的等距内边距和文本触发器虚线悬停提示的 HoverCard / Open States 的 HoverCardAudit Chromium 框架 文本和元素触发器;默认打开 多余目标、字体丢失或水合不匹配均会失败;未能应用到卡片的 xstyle、className 或 style、卡片内边距缺失或不均,或文本触发器上的虚线提示丢失,也同样失败。 audit:HoverCard/anatomy
FR3、AR1 HoverCard.test.tsx 角色、触发器属性和属性恢复测试;popupTrigger.test.ts 角色支持和属性测试;HoverCardTriggerRoles.a11y.browser.spec.ts 属性检查以及已标记的无角色触发器打开时的 axe 通过;HoverCardAudit 框架以及对 HoverCard / Open States 的审计 axe 通过 已标记和未标记;受支持和不支持的角色 错误的角色、未按所述替换和恢复的触发器属性,或打开卡片上出现新的 axe 违规,均会失败。 audit:HoverCard/accessibility
FR4–FR6、AR2 HoverCard.test.tsx 悬停、延迟和隐藏延迟计时、触发器到卡片的保持、Escape、重新聚焦和触摸测试,以及其 focusTrigger="auto" 焦点漫游、<summary>、包装器、移出标签页顺序和聚焦在可聚焦触发器内部的情况,及其在“第二个文档”中的 Escape、重新聚焦、聚焦进入卡片、延迟触发器和移动触发器情况,及其焦点陷阱容器的 Escape 情况;HoverCardAudit 在 Chromium 中的悬停与键盘通过;useTouchTrigger.test.ts 和 touchTriggerTargets.test.tsx 的禁用控件情况 悬停、聚焦、点击、在页面中和第二个文档中从触发器及内容按 Escape;在钩子挂载后附加的触发器,以及移入框架再移回的触发器;焦点陷阱容器内的触发器;touchTrigger auto、tap 和 none;操作触发器;可点击行内的禁用控件 无法到达或无法关闭、在 delay 之前打开或在 hideDelay 之前关闭、指针从触发器移入卡片时关闭,或在 auto 下点击执行操作的触发器时打开、在 none 下任何点击时打开的卡片,均会失败。 audit:HoverCard/behavior
FR7 HoverCard.test.tsx isEnabled, isDefaultOpen, onOpenChange、isOpen 强制以及受控关闭时的焦点返回测试;layerDismissalFamilies.test.tsx 受控 HoverCard 用例 禁用、默认打开、保持打开、保持关闭、调用者在焦点位于内部时关闭 错误的状态报告、悬停时隐藏了保持打开的卡片或打开了保持关闭的卡片,或者调用者关闭卡片后焦点仍留在卡片内部,均视为失败。 audit:HoverCard/behavior
FR11 HoverCard.test.tsx 表面按下测试套件 位于可点击容器内和 <label> 内的卡片;卡片内的按钮 点击卡片内容时运行了容器的点击处理程序或激活了带标签的控件,或卡片按钮失效,均视为失败。 —
FR12 HoverCard.test.tsx 触控套件中的键入字段用例;interactionModality.test.ts 文本输入套件 点击、在字段中键入文本、然后按 Enter;再按 Escape 仅在点击之后进行文本输入便导致焦点返回时打开卡片,或按 Escape 后卡片保持关闭,均视为失败。 audit:HoverCard/behavior
Theming anatomy map scripts/check-knowledge.mjs 消费者解剖结构和当前目标 缺失、多余或过期的映射无法通过验证。 audit:HoverCard/theming

从源码读取,尚无专门测试:

  • FR3:卸载时恢复触发器自身的属性。
  • FR5:触控笔的按压计为一次点击。
  • FR5:点击触发器关闭由悬停或聚焦打开的卡片,或关闭自挂载起便一直打开的卡片;触控笔在悬停之后的点击也包括在内。
  • FR7:isOpen={true} 在焦点离开触发器时保持卡片打开。
  • FR8:hasHoverIndication={true}。

仅已在浏览器中检查,没有单元测试:

  • FR1:卡片的 padding。

决策日志

DEC-1 — touchTrigger 决定点击是否可能显示卡片

参考: component:HoverCard/DEC-1 决策者: cixzhang,2026-10-31;修订于 2026-11-01 和 2026-11-02

touchTrigger 决定消费一次点击来显示卡片是否安全,如 component:Tooltip 的 DEC-1 所述:auto(默认值)仅在触发器自身不执行任何操作时才在点击时显示卡片,从而一次点击只做一件事;tap 声明每次点击都可以显示卡片;none 声明任何点击都不可以。aria-disabled 控件或禁用控件的标签不算操作;仅通过无角色的 onClick 来执行操作的元素属于调用方需要修复的问题。HoverCard 没有公开的 toggle prop;toggle 式触发器遵循 component:Tooltip 的 DEC-1。

未决问题

无。

内容边界

本文件不会重复使用方 prop 表、示例或层系统规则。它链接到这些内容的所属方。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx