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-094FR5 所述。鼠标按压 保持 card 的桌面端按压样式。 - 兼容性类别:非破坏性行为变更;无公共 prop、默认值、DOM 或目标更改。
- 受控/非受控行为:不适用。
- 迁移决策:无。
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 嵌套控件上的两个焦点指示器(AR3)。 当任何后代获得键盘焦点时,card 会绘制其焦点轮廓,因此聚焦嵌套控件会同时显示 card 轮廓和控件自身的轮廓,而
architecture:interaction-modalityINV3 允许每次焦点移动只有一个指示器。 - 目标上未反映禁用状态(FR4)。
clickable-card目标反映variant,但不反映禁用状态,因此主题无法在那里为其设置样式,而architecture:component-theming-surfaceINV6 将状态保留在所属目标上。
所有权边界¶
拥有
- 承载 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