跳转至

ClickableCard 组件契约

契约一览

领域 契约
公共契约 一个 Card,带有必需的 label,以及 onClick(动作)或 href(导航)二者之一,另有 isDisabled 以及 Card 的 padding、variant、elevation 和 size 输入。该 card 基于 useClickableContainer 构建,它返回 onPointerDown,容器会展开它,从而从嵌套交互元素上开始的触摸按压不会显示按下状态(FR5)。
行为 一个视觉上隐藏的原生 button 或 link 拥有该 card 的动作;整个 card 表面都能激活它,而嵌套控件和选中的文本保持各自的结果。
终端用户影响 用户可以从 card 上的任意位置(通过指针或键盘)激活它,而禁用的 card 保持可到达且会被宣告,同时不执行任何操作。
构建者影响 主题的 exit duration 和 easing 设置触摸按压释放(FR5);无 API 更改。
兼容性/就绪状态 无 API 更改;触摸按压释放变更(FR5、spec:AST-094 FR5)。两个实现缺口列在“当前状态影响”下。
审查检查 拒绝禁用的实时目标、重复激活、来自嵌套控件或选中文本的激活、跳过共享决策的目标,或丢失的焦点绘制。
治理规则 family:navigation-destinations/FR1,FR3–FR5;architecture:interaction-modality/INV2–INV5;architecture:public-component-api/INV5–INV8;spec:AST-085 FR1, FR2, FR5, FR6;component:ClickableCard/FR5(触摸按压释放);spec:AST-094/FR5(按压释放的 exit tokens)。

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

意图

ClickableCard 将 Card 表面转变为单个动作或导航目标, 同时不剥夺其内部交互内容的激活能力。

兼容性与迁移

  • 已发布的默认值保持不变:触摸按压释放为 no:它按 主题的 exit duration 和 easing 淡出,如 FR5 和 spec:AST-094 FR5 所述。鼠标按压 保持 card 的桌面端按压样式。
  • 兼容性类别:非破坏性行为变更;无公共 prop、默认值、DOM 或目标更改。
  • 受控/非受控行为:不适用。
  • 迁移决策:无。

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

当前状态影响

  • 嵌套控件上的两个焦点指示器(AR3)。 当任何后代获得键盘焦点时,card 会绘制其焦点轮廓,因此聚焦嵌套控件会同时显示 card 轮廓和控件自身的轮廓,而 architecture:interaction-modality INV3 允许每次焦点移动只有一个指示器。
  • 目标上未反映禁用状态(FR4)。 clickable-card 目标反映 variant,但不反映禁用状态,因此主题无法在那里为其设置样式,而 architecture:component-theming-surface INV6 将状态保留在所属目标上。

所有权边界

拥有

  • 承载 card 动作的隐藏原生 button 或 link,及其名称。
  • Card 表面激活,以及针对嵌套交互后代和选中文本的激活抑制。
  • card 上的启用、禁用、悬停、按压和委托焦点绘制。
  • 绘制根上的 clickable-card 目标。

不拥有 / 非目标

  • 选择或切换——由 component:SelectableCard 拥有。
  • 调用方内容的语义、绘制或激活。
  • 目标接受——由 family:navigation-destinations 拥有。
  • Card padding、variant 绘制、圆角、elevation 和尺寸——由 component:Card 拥有。

公共概念

概念 封闭值或状态 含义 按 variant/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
激活模式 动作(onClick);导航(href);两者皆非(OQ1) 哪个隐藏的原生控件负责卡片的动作。 每个变体 两者皆非 component:ClickableCard 稳定 当同时给出时,href 优先。
禁用 启用;禁用 禁用的卡片保持可聚焦并会被宣告,但不执行任何操作。 两种模式 启用 component:ClickableCard 稳定 —
嵌套归属 卡片表面;嵌套可交互后代;选择 只有表面按下才会激活卡片。 启用的卡片 表面 component:ClickableCard 稳定 —
目的地 接受;阻止 每个导航接收端都使用共享的目的地判定。 导航模式 无 family:navigation-destinations 稳定 被阻止的目的地不会导航。

行为与布局契约

ID 不变量 依据
FR1 根元素是 Card 的 div。当存在 href 时,一个视觉上隐藏的原生链接持有目的地和 target;否则一个视觉上隐藏的 button type="button" 调用 onClick。label 为该控件命名,且该隐藏控件是卡片的 Tab 停靠点。 当前源码与测试
FR2 在卡片表面上按主按钮会以卡片作为 currentTarget 调用一次 onClick,随后执行一次被接受的导航,除非回调取消该导航。在带有 href 的卡片表面上按中键会在新标签页中打开被接受的目的地,且不调用 onClick。在嵌套的可交互后代内部、在打开的 Tooltip 或 HoverCard 表面(component:Tooltip FR11)内的按压,或结束文本选择的按压,都不会激活卡片。激活动作卡片的隐藏按钮会调用一次 onClick;激活隐藏链接会导航而不调用 onClick。 当前源码与测试;architecture:public-component-api INV7
FR3 普通、新标签页、修饰键、中键以及表面委托的导航均使用共享的目的地判定;被阻止的目的地不会导航。 family:navigation-destinations FR1, FR3–FR5
FR4 isDisabled 使隐藏控件保持可聚焦,并带有 aria-disabled="true";Enter、Space 以及点击它都不会产生任何效果。禁用的链接保留其链接角色和名称,但没有 href 或 target。该控件仍可聚焦并会被宣告(spec:AST-085 FR1、FR2、FR5);卡片自身的 click 和 mouseup 处理以及调用方的 onMouseUp 会被移除,调用方的其他事件属性仍会到达根元素,且表面不显示悬停或按下的绘制效果(spec:AST-085 FR6),并以半透明度渲染。禁用状态会反映在所属目标上(architecture:component-theming-surface INV6)。实现差距:clickable-card 目标未反映禁用状态(当前状态影响)。 当前源码与测试
FR5 启用时,根元素在可悬停指针下绘制共享悬停覆盖层,并为会激活卡片的鼠标和触摸按压绘制按下覆盖层;起始于嵌套交互元素上的触摸按压不显示按下绘制,因为它不会激活卡片(与 FR2 的激活规则相对应),而鼠标在该处的按压保留 :active 绘制,且带边框卡片的边框会对悬停作出响应。触摸按压会立即显示。在触摸呈现下,其释放时按主题的退出运动令牌(--duration-exit、--ease-exit)淡出,依照 spec:AST-094 的 FR5;鼠标按压则保留卡片的桌面端按下样式。当键盘焦点位于隐藏控件上时,根元素上会显示共享焦点轮廓。 当前源代码、stories 和 architecture:interaction-modality
FR6 除 Card 的目标之外,根元素还携带反映 variant 的 clickable-card 目标。ref 指向根元素;受支持的 DOM、ARIA、数据和事件属性均能到达根元素;调用方的 onMouseUp 在卡片自身的之后运行;xstyle、className 和 style 在组件样式之后合成。 当前源代码和测试;architecture:public-component-api 的 INV5–INV8

允许的变化

  • AV1 — 调用方内容。 调用方内容在卡片内保留其自身的语义、主题和交互。
  • AV2 — 路由集成。 已接受的跳转目标可以使用原生链接或活动链接提供者。
  • AV3 — 卡片外观。 卡片变体、内边距、高度和尺寸可以变化,而不会改变激活归属权。

代表性状态

状态 必需的不变量 允许的变化
启用操作 隐藏按钮可通过键盘和表面操作;onClick 只运行一次。 内容与外观。
启用导航 隐藏链接保留其跳转目标;表面按压使用共享决策。 原生路由或 Provider 路由。
禁用操作 隐藏按钮可聚焦并带有 aria-disabled;不运行任何操作。 —
禁用导航 保留链接角色和名称;无 href 或 target;可聚焦;不发生任何导航。 —
嵌套控件 后代元素处理其自身事件;卡片不会被激活。 任意可交互子元素。

转换与优先级顺序

  • ORD1 — 事件归属。 禁用状态移除卡片自身的 click 和 mouseup 处理;随后文本选择和嵌套交互元素的归属权会抑制卡片激活;否则,对于主键按压,onClick 在任何已接受的跳转目标之前运行,并可能取消该目标;中键按压会打开已接受的 href,但不会调用 onClick。
  • ORD2 — 导航。 在选择原生、路由、同标签页、新标签页、修饰键点击、中键点击或委托激活之前,先确定跳转目标。

性能与资源

  • PR1 — 仅共享资源。 ClickableCard 在挂载时安装共享按压控制器,并仅在启用期间将根元素标记为按压表面;它自身不添加任何计时器、观察器、请求、portal 或布局测量。

无障碍契约

  • AR1 — 原生语义拥有者。 隐藏的按钮或链接暴露其原生角色和 label;可见的根元素不添加自身角色。
  • AR2 — 禁用状态保持可感知。 禁用卡片的控件保持在 Tab 顺序中,播报 aria-disabled,并且是惰性的(FR4)。
  • AR3 — 每次焦点移动一个焦点指示器。 隐藏控件获得焦点时,在卡片根元素上显示一次(architecture:interaction-modality 的 INV3)。实现差距:当嵌套控件获得焦点时,根元素也会绘制轮廓,因此该控件会显示两个指示器(当前状态影响)。
  • AR4 — 模态对等性。 键盘、指针和触摸用户各自都拥有可操作的路径;悬停永远不会是唯一的路径。

设计关系

解剖结构或状态 设计要求 呈现权属 层级角色 组件契约
容器 Card 表面,具有启用的交互绘制与委托焦点。 当前源码与文档 上下文相关的操作表面 FR4–FR6, AR3, AR4
内容 调用方的层级与交互,保持不变。 调用方自有内容 上下文相关 FR2, AV1

主题化解剖结构

{
  "Container": {"target": "clickable-card"},
  "Content": {
    "none": {
      "reason": "intentional: Caller-supplied content retains its own theming ownership; ClickableCard applies no content target."
    }
  }
}

家族与系统关系

  • family:navigation-destinations 拥有跨导航汇的目的地接受与对等性规则;FR3 应用该规则。
  • architecture:interaction-modality 拥有交互模态与焦点指示器规则;FR5 和 AR3 应用这些规则,AR3 记录差距。
  • architecture:component-theming-surface 设定了 clickable-card 目标所遵循的规则;FR4 记录禁用状态差距。
  • architecture:public-component-api 拥有 ref、透传、取消和样式输入规则;FR2 和 FR6 应用这些规则。
  • spec:AST-085 拥有禁用控件行为;FR4 和 AR2 应用它。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, AR1 ClickableCard.test.tsx 隐藏控件、标签与目标测试;Button.a11y.test.tsx 与 Button.a11y.chromium.spec.ts 中的 ClickableCard 状态 操作与导航;clickable-card 和 clickable-card-as-link 缺少隐藏按钮或链接、丢失 aria-label 或 target、按钮角色或名称未在无障碍树中暴露,或链接卡片丢失其计算出的 link 角色,均判定失败。差距:链接卡片在无障碍树中的名称,以及根元素不添加任何角色,这两点均无检查。 audit:ClickableCard/accessibility
FR2, ORD1 ClickableCard.test.tsx 表面、隐藏控件、键盘、嵌套控件与选择测试 表面;隐藏控件;Enter;嵌套按钮与输入;选择 缺少或重复的 onClick、错误的 currentTarget,或来自嵌套控件或选择的激活,均判定失败。差距:没有测试取消来自 onClick 的导航;没有测试覆盖在同时给定 href 和 onClick 时激活卡片的隐藏链接;也没有 ClickableCard 测试覆盖在给定 href 的卡片上进行中键按压。 audit:ClickableCard/behavior
FR3, ORD2 useClickableContainer.test.tsx;ClickableCard.test.tsx 链接测试 普通、修饰、中键、目标、已接受、已阻止 被阻止的目的地仍然到达导航汇,或激活方法丢失,在共享钩子测试中判定失败。 audit:ClickableCard/navigation
FR4, AR2 ClickableCard.test.tsx 禁用与触摸按压测试;Button.a11y.chromium.spec.ts 中的 clickable-card-disabled 状态 禁用的操作与导航 禁用控件脱离 Tab 顺序、href 或 target 仍然有效、回调仍然执行、禁用状态下出现触摸按压标记,或禁用操作卡片的不可用状态或惰性(点击、Enter、空格)在无障碍树中失败,均判定失败。差距:禁用链接卡片没有无障碍树检查(spec:AST-085 FR5),且禁用悬停与鼠标按压绘制(spec:AST-085 FR6)以及半透明度均无检查。 audit:ClickableCard/accessibility
FR5, AR3, AR4 ClickableCard.test.tsx 触摸按压测试;CardPress.a11y.chromium.spec.ts 在 core-clickablecard--with-on-click 上;稳定视觉基线 core-clickablecard--navigation 静态;桌面悬停与鼠标按压;触摸按压 悬停未覆盖静态样式、鼠标按压未覆盖悬停样式、触摸按压与桌面按压或淡出效果不匹配,或静态外观发生变化,则测试失败或出现回归。缺口:边框悬停与焦点轮廓没有自动化检查。 audit:ClickableCard/design
FR6 ClickableCard.test.tsx 高度测试;themingTargets.test.ts 高度;目标清单 丢失高度类或目标则测试失败。缺口:没有测试覆盖 ref、DOM 透传、onMouseUp 顺序或样式输入合并。 audit:ClickableCard/api
PR1 源码审查 启用与禁用 缺口:如果 ClickableCard 添加自己的定时器、观察器或测量,没有自动化检查会失败。 audit:ClickableCard/behavior
主题结构映射 scripts/check-knowledge.mjs 消费方结构与当前目标 缺失、多余或过时的映射会导致仓库验证失败。 audit:ClickableCard/theming

决策日志

无记录。

未决问题

  • OQ1 — 渲染不带 href 或 onClick 的 ClickableCard 是否应继续作为受支持的可聚焦空操作,还是公开契约应拒绝或禁用该组合?(human-api)当前发布的类型与渲染允许这种用法。

内容边界

本文件不重复消费者属性表/示例、当前审计结果、实施步骤、共享目标规则或 Card 样式。它链接到这些内容的所属文档。

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