CheckboxListItem 组件契约¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公开契约 | 一个选项行:由 label 或 aria-label 命名的原生复选框,由 description 描述,可选 endContent 和 align,通过 ListItem 渲染。在带有 value 数组的 CheckboxList 内(集合模式),选中状态来自成员关系且 value 为必填。在 List 内,或在没有 value 的 CheckboxList 内(独立模式),该项读取 isChecked 并调用 onCheck。 |
| 行为 | 复选框是该选项唯一的 Tab 停靠点。当项目可编辑且位于 CheckboxList 中或具有 onCheck,或者具有 onClick 时,行表面点击会委托给它;项目的 onClick 在每次直接点击、键盘点击或行表面点击时只触发一次。禁用、只读和忙碌状态拒绝切换。 |
| 终端用户影响 | 用户可以通过指针、触摸和键盘操作每个选项,听到其名称、描述以及选中、混合、禁用、只读或忙碌状态,并在保存时看到加载指示器(spinner)。 |
| 构建者影响 | 项目所在位置及其父列表是否具有 value,共同决定模式;value 仅在集合模式下为必填。无处理程序(handlerless)的含义、选中行的指针反馈、消费者 DOM-prop 目标、只读点击传播和焦点环归属仍是未决问题(OQ1、OQ3–OQ6)。 |
| 兼容性/就绪度 | 一个已选中、启用、可编辑的行反映 selected(FR15);无 API 或默认值变更。无处理程序项目和双重焦点指示器列在“当前状态影响”下。 |
| 评审检查 | 拒绝出现第二个 Tab 停靠点、在禁用、只读或忙碌时进行切换、isChecked 覆盖父级 value 数组、每次点击触发多次的 onClick、丢失的描述关系,或未经所有者决策引入的新目标、状态或事件路由 API。 |
| 治理规则 | architecture:public-component-api/INV5–INV9;architecture:component-theming-surface/INV3–INV6;architecture:interaction-modality/INV1–INV5;architecture:component-test-sufficiency/INV1–INV7;spec:AST-021/FR8–FR10;spec:AST-085/FR1, FR7;spec:AST-011;spec:AST-038/FR7;WCAG 2.2 1.3.1、2.1.1、4.1.2。 |
该表格是评审视图;以下正文为权威依据。
意图¶
在 CheckboxList 或普通 List 中,将一项独立选择呈现为全宽行,其复选框、标签、描述和结尾内容与其选中、可用、只读和忙碌状态保持对齐。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公开 prop、默认值、导出或 DOM 变更
- 受控/非受控行为:仅受控——在集合模式下由父列表的
value控制,在独立模式下由isChecked控制 - 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
所有权边界¶
拥有
- 一个选项行:其 CheckboxInput、命名(字符串标签、通过
aria-labelledby的富标签、aria-label覆盖)、描述关系、结尾内容插槽,以及随列表密度变化的复选框尺寸。 - 模式解析:集合成员关系与独立
isChecked和onCheck的取舍、集合模式下缺少value的错误,以及该行提议的下一个值。 - 行表面点击委托、单 Tab 停靠点规则以及项目
onClick路由。 - 项目的禁用和加载状态、待处理集合项目的忙碌渲染、只读渲染以及选中行填充。
不拥有 / 非目标
- 组、其标签、描述、状态、禁用原因、只读和禁用输入、待处理值集合以及集合变更排序——由
component:CheckboxList拥有。 - 行呈现、密度、分隔线、悬停和按压叠加层、focus-within 环、
list-item目标以及标签和描述截断——由component:List和 Item 拥有。 - 复选框控件、其指示器、焦点环、按压叠加层以及忙碌、禁用和只读语义——由
component:CheckboxInput和 CheckboxIndicator 拥有。 - 加载指示器呈现——由
component:Spinner拥有;委托机制——由共享的 clickable-container hook 拥有。 - 新目标、反射状态或事件路由 API。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 命名 | 字符串 label;节点 label;aria-label |
为复选框命名;节点 label 根据其可见文本为其命名;aria-label 替换复选框上派生的名称,而不是行的名称。 |
所有状态。 | label 必填 | 调用方与组件 | 稳定 | 被公共类型拒绝 |
| 模式 | 集合(父级有 value);CheckboxList 中无 value 的独立模式;List 中的独立模式 |
集合模式读取成员资格并通过父级报告;独立模式读取 isChecked 并调用 onCheck。 |
由放置位置决定;isChecked 和 onCheck 在集合模式下被忽略。 |
独立 | 组件 | 稳定 | 没有 value 的集合项会抛出异常 |
| 选中状态 | 未选中、选中、混合(仅独立模式) | 原生复选框状态;混合态使用原生 indeterminate 属性并提议 true。 |
所有模式。 | 未选中 | 调用方 | 稳定 | 被公共类型拒绝 |
| 变更路径 | 父级 onChange/changeAction(集合);onCheck(独立);无 |
提议下一个值数组或布尔值。 | 已启用、可编辑、非忙碌的项。 | 无 | 调用方与组件 | 已发布;无处理程序时的含义尚未确定 | 没有处理程序意味着组件不拥有变更 |
| 可用性 | 已启用;项 isDisabled;组禁用;带原因的组禁用 |
阻止切换和选中行的填充;复选框通过 aria-disabled 保持可聚焦。 |
项和组。 | 已启用 | 组件 | 稳定 | 仅布尔值 |
| 只读 | 来自组的 isReadOnly |
保持值可见、可聚焦且完全不透明,同时拒绝切换。 | 仅在 CheckboxList 内部。 | false | 组件 | 稳定 | 仅布尔值 |
| 忙碌 | isLoading;针对该项 value 的父级 changeAction 待处理 |
复选框内显示加载指示器,行和复选框处于忙碌状态,拒绝切换。 | 按项。 | 空闲 | 组件 | 稳定 | 仅布尔/过渡状态 |
| 内容 | description、endContent |
描述用于说明复选框;末尾内容仍归调用方所有,且不在名称范围内。 | 所有状态。 | 无 | 调用方 | 稳定 | 仅限类型化值 |
onClick |
在直接、键盘和行表面点击时于复选框上触发 | 每次点击触发一次,包括只读项;公共类型指定行元素。 | 所有状态。 | 无 | 调用方与组件 | 已发布;目标尚未确定 | — |
| 透传 | ref、className、style、xstyle、data、除 aria-label 外的 ARIA、其他事件 |
到达行 <li>;调用方的 xstyle 在选中行的填充之后进行组合。 |
所有状态。 | 无 | 组件 | 已发布;ARIA 目标尚未确定 | 组件拥有的属性优先 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| ---- | --- | --- |
| FR1 | 该行 MUST 渲染一个原生的 CheckboxInput 作为 ListItem 的起始内容;该复选框必须是该选项唯一可聚焦的控件,并且该行本身 MUST NOT 可聚焦。 | 已交付的源代码;专项测试;WCAG 2.1.1 和 4.1.2 |
| FR2 | 字符串 label MUST 为复选框命名;节点 label MUST 通过 aria-labelledby 从可见的 label 元素为其命名;aria-label MUST 替换复选框上推导出的名称,且永远不会作用到该行。 |
已交付的源代码和专项测试 |
| FR3 | 可渲染的 description MUST 通过 aria-describedby 描述复选框;缺失或为空的描述 MUST 不添加任何内容。 |
已交付的源代码和专项测试;WCAG 1.3.1 |
| FR4 | 在带有 value 数组的 CheckboxList 内部,该条目 MUST 从成员关系中读取选中状态,在没有 value 时抛出错误,并通过父级的变更路径提议一个添加或移除了其 value 的新数组;isChecked 和 onCheck MUST 被忽略。 |
已交付的源代码和专项测试 |
| FR5 | 在 List 内部,或者在没有 value 的 CheckboxList 内部,该条目 MUST 读取 isChecked 并以下一个布尔值调用 onCheck;混合状态条目 MUST 提议 true,且 value MAY 被省略。当保留混合值时,component:CheckboxInput FR1 记录的混合状态缺口适用。 |
已交付的源代码和专项测试 |
| FR6 | 条目 isDisabled 或一个被禁用的组 MUST 通过 aria-disabled 使复选框成为可聚焦但禁用(focusable-disabled)状态,拒绝切换,并省略选中行填充;组禁用原因会添加组提示(component:CheckboxList FR9)。 |
已交付的源代码、专项测试以及共享复选框绑定 |
| FR7 | 条目 isLoading,或父级针对该条目 value 的待处理 changeAction,MUST 在复选框内渲染 Spinner,将该行和复选框标记为忙碌,并拒绝切换。 |
已交付的源代码、专项测试以及 Chromium 无障碍套件 |
| FR8 | 只读组 MUST 使复选框为只读、可聚焦且完全不透明,拒绝任何切换,并省略选中行填充;该行仅在条目具有 onClick 时才委托点击。 |
已交付的源代码、专项测试以及共享复选框绑定;spec:AST-011 |
| FR9 | 对于 CheckboxList 内或带有 onCheck 的已启用、可编辑条目,在交互式后代元素之外的行表面点击 MUST 被委托给复选框;label、description 或末尾内容中的链接和按钮 MUST 保持其自身行为。 |
已交付的源代码和专项测试 |
| FR10 | 条目的 onClick MUST 对每次直接、键盘或行表面点击触发一次,包括在只读条目上。 |
已交付的源代码和专项测试;architecture:public-component-api/INV5 |
| FR11 | compact 密度 MUST 渲染 sm 复选框;其他密度 MUST 渲染 md。 |
已发布源码和定向测试 |
| FR12 | 启用、可编辑、选中的行 MUST 绘制 --color-accent-muted 填充,且使用方的 xstyle MUST 在其后合成。 |
已发布源码和 Chromium 无障碍测试套件 |
| FR13 | ref、className、style、xstyle、align、数据属性、除 aria-label 之外的 ARIA,以及除 onClick 之外的事件 MUST 到达行的 <li>。 |
已发布源码和定向测试 |
| FR14 | 带 isChecked 且无 onCheck 的独立条目在激活时不改变任何内容。实现差距:它未声明只读状态,因此复选框被暴露为可编辑(WCAG 2.2 4.1.2);在没有 value 的 CheckboxList 内部,其行也会委托点击并显示指针反馈。其含义为 OQ1。 |
精确的已知失败:spec:AST-021 list-item-handlerless-read-only;WCAG 4.1.2 |
| FR15 | 选中、启用、可编辑的行绘制选中行填充,并在行的 item 和 list-item 目标上反映 selected 状态,从而使主题可以重新样式化选中行及该填充上的文本(architecture:component-theming-surface INV6)。只读或禁用的行不绘制填充,也不反映任何状态;其目标与未选中行匹配。 |
architecture:component-theming-surface/INV6 |
| FR16 | 随版本发布的行为,在其开放问题被裁定之前不构成需求:使用方的 DOM 输入被拆分到两个元素上:数据属性和 ARIA 到达行,而 onClick 在复选框上运行,其类型却针对行,因此 event.currentTarget 是复选框,不携带行的数据属性(OQ3)。 |
architecture:public-component-api/INV5;任何重定类型或移动均须参照 INV9 |
| FR17 | 随版本发布的行为,在其开放问题被裁定之前不构成需求:在带 onClick 的只读条目上,该条目会停止点击的传播,因此 React 祖先永远不会收到这些点击,而对于启用的条目它们会收到(OQ4)。条目自身的 onClick 仍会在每次点击时触发一次(FR10)。 |
当前源码;共享的 clickable-container hook 行为 |
| FR18 | 随版本发布的行为,在其开放问题被裁定之前不构成需求:在启用、可编辑、选中的行上,选中行填充取代了行的悬停和按下覆盖层,因此指针悬停和按住不会给出行反馈(OQ5)。 | Chromium 无障碍测试套件;design:user-states 将悬停和选择处理排除在其当前声明之外 |
| FR19 | 一次键盘焦点移动绘制两个指示器:Item 的行 focus-within 轮廓和 CheckboxInput 的指示器环(OQ6)。一次焦点移动 MUST 有一个所属指示器(architecture:interaction-modality INV3)。实现差距:两个指示器都会绘制。 |
Chromium 无障碍测试套件;architecture:interaction-modality/INV3 |
允许的变化¶
- AV1 — 内容。 标签、描述和结尾内容可以在其公共类型范围内变化,而不会成为新的目标。
- AV2 — 组合呈现。 密度、分隔线、行覆盖层、焦点环和复选框指示器仍是其所属组件的能力。
- AV3 — 主题绘制。 语义令牌和组合目标可以更改允许的视觉属性,而不改变语义、Tab 键顺序或状态优先级。
代表性状态¶
| 状态 | 必需的不变量 | 允许的变化 |
|---|---|---|
| 集合选项 | 由成员关系确定选中;一个 Tab 停靠点;通过父级切换 | 标签、描述、末端内容 |
| 独立选项(列表或组) | 读取 isChecked,调用 onCheck;混合状态提议 true |
放置位置 |
| 忙碌选项 | Spinner、忙碌行和复选框,拒绝切换 | 加载来源(prop 或待保存) |
| 只读选项 | 可见、可聚焦、全不透明度、不可变;onClick 每次点击触发一次 |
该项是否具有 onClick |
| 禁用选项 | 不可操作;无选中行填充 | 项或组来源;组原因 |
| 无处理器的独立选项 | 惰性;声明无只读状态(FR14、OQ1) | — |
转换与优先级顺序¶
- ORD1 — 选中状态。 父级
value数组(集合)→ 乐观的待处理值 → 成员关系;否则使用isChecked;否则为未选中。 - ORD2 — 切换。 disabled、只读或忙碌守卫 → 模式 → 父级
onChange(集合)或onCheck(独立)。 - ORD3 — 点击路由。 交互式后代保留其点击 → 当项可编辑且位于 CheckboxList 中,或具有
onCheck,或具有onClick时,其他行表面点击委托给复选框 → 复选框的点击运行onClick一次。 - ORD4 — 属性。 使用者的剩余 props → 行
<li>;aria-label和onClick→ 复选框;组件自有的名称、描述、状态和忙碌属性优先。
性能与资源¶
- PR1 — 有界资源。 该项不拥有观察器、计时器或全局监听器;委托监听器属于行及其生命周期。
当前测量归入审计记录;本小节仅拥有持久约束及其验证目标。
无障碍契约¶
- AR1 — 选项语义。 每个选项 MUST 保持为原生复选框,其名称、描述、选中或混合状态,以及禁用、只读和忙碌状态均可通过编程方式确定。
- AR2 — 键盘对等性。 Tab MUST 恰好一次到达复选框,Space MUST 遵循与指针激活相同的可用性和变更规则。
- AR3 — 扩大的目标。 行表面 MUST 充当复选框的指针和触摸目标,而不会成为第二个控件。 按住点击委托行的框上的指针(手指、鼠标或笔)会按下并绘制整行,就像按在行上一样(触摸:所有者通过,2026-11-04;鼠标和笔:所有者决定,2026-11-10)。
- AR4 — 忙碌感知。 忙碌选项 MUST 在无障碍树中并通过 Spinner 可见地暴露忙碌状态。
- AR5 — 焦点可见性。 复选框上的键盘焦点 MUST 保持可见;目前有两个指示器绘制(FR19、OQ6)。
设计关系¶
| 解剖结构或状态 | 设计需求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 选项行 | 全宽行,包含起始位置的复选框、标签和描述,以及末端内容。 | List 和 Item | 支撑 | FR1、FR9、FR13 |
| 复选框 | 呈现选项的选择指示器。 | CheckboxInput 所有者及其按下的 design:user-states |
突出 | FR1、FR6–FR8、FR11 |
| 标签、描述 | 命名并描述复选框。 | Item | 主要内容 | FR2、FR3 |
| 选中行填充 | 在启用、可编辑的选中行上补充复选框状态。 | 行 selected 状态(FR15);FR18 开放 |
支撑 | FR12 |
| Spinner | 在选项忙碌时替换标记。 | Spinner | 支撑 | FR7 |
此记录不携带解剖结构主题映射。组合选项的解剖结构及其目标布置记录在 component:CheckboxList 的主题解剖结构中,CheckboxListItem 自身不拥有任何目标。
家族与系统关系¶
component:CheckboxList组合此契约:它提供集合值、可用性、只读和待处理值,选项通过上下文读取这些值,并拥有其周围的组。architecture:public-component-api拥有透传保留、事件组合、refs 和发布变更规则。architecture:component-theming-surface拥有目标布置和状态反射。architecture:interaction-modality拥有焦点可见性和单指示器规则。spec:AST-021拥有 CheckboxListItem 的可复用复选框无障碍绑定及其确切的已知失败生命周期。spec:AST-011将isReadOnly记录为可见、可聚焦、不可编辑值的名称。spec:AST-038/FR7在层边界处停止 CheckboxList 上下文;层内的项需要自己的 provider。- List、Item、CheckboxInput、CheckboxIndicator 和 Spinner 在此组合时保留其现有的目标和行为契约。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
| FR1, FR9, AR2, AR3 | CheckboxList.test.tsx 单一 Tab 停靠点、行点击、标签内链接和交互式尾部内容用例 | 集合选项;行表面点击;富标签中的链接;交互式尾部内容 | 出现第二次 Tab 停靠、丢失事件委托,或来自交互后代元素的切换,则失败。 | audit:CheckboxListItem/interaction |
| AR3(所有指针) | CheckboxList.test.tsx 按压表面用例;CheckboxListPress.a11y.chromium.spec.ts | 粗指针和细指针;标签、描述和框体;嵌套复选框 | 若按压框体却仅绘制框体,或嵌套复选框按压到行,则失败。 | audit:CheckboxListItem/interaction |
| FR2, FR3, AR1 | CheckboxList.test.tsx 可访问名称和描述用例;共享复选框绑定 | 字符串和富标签;aria-label;字符串和节点描述;无描述 | 名称或描述错误,或行上设置了 aria-label,则失败。 | audit:CheckboxListItem/accessibility |
| FR4, FR5 | CheckboxList.test.tsx 集合、独立和全选用例 | 添加、移除、缺少 value、混合、全选、isChecked 与父级数组 | 数组或布尔值错误、缺少错误,或 isChecked 覆盖成员关系,则失败。 | audit:CheckboxListItem/behavior |
| FR6–FR8, AR4 | CheckboxList.test.tsx 禁用、加载中、待定和只读用例;CheckboxList.a11y.chromium.spec.ts 的 disabled-*、loading-item、pending-* 和 read-only 用例 | 单项和整组禁用;原因;加载中;待定;只读 | 在禁用、只读或忙碌状态下切换,或丢失忙碌状态,则失败。 | audit:CheckboxListItem/accessibility |
| FR10, FR17 | CheckboxList.test.tsx 条目 onClick 和只读点击用例 | 启用和只读;直接、键盘和行表面点击 | 每次点击触发零次或多次的 onClick 则失败。证据缺口:没有测试断言只读条目上的事件传播被阻止(FR17)。 | audit:CheckboxListItem/behavior |
| FR11 | CheckboxList.test.tsx 密度用例 | 紧凑和均衡 | 复选框尺寸错误则失败。 | audit:CheckboxListItem/layout |
| FR12, FR18 | CheckboxList.a11y.chromium.spec.ts 的 checked、hover-* 和 pressed-* 用例 | 浅色和深色;未选中和选中 | 填充缺失或位置错误会导致行绘制检查失败。证据缺口:没有断言 xstyle 在填充之后进行合成。 | audit:CheckboxListItem/visual |
| FR13, FR16 | CheckboxList.test.tsx ref 与样式、data-testid 和 ARIA 用例 | 行 ref、class、style、data、ARIA | 输入被丢弃或路由错误则失败。证据缺口:没有测试断言 onClick 的 event.currentTarget(FR16)。 | audit:CheckboxListItem/api |
| FR14 | Checkbox.a11y.test.tsx 已知失败 list-item-handlerless-read-only;CheckboxList.a11y.chromium.spec.ts 的 handlerless 用例 | 独立使用 isChecked 且没有 onCheck | 当此缺口关闭时,已记录的已知失败将不再匹配。 | audit:CheckboxListItem/accessibility |
| FR15 | CheckboxList.test.tsx 选中行状态用例 | 已选中、未选中、只读和禁用行 | 一个已选中、可用、可编辑的行,如果其行目标上没有 selected,则失败;只读或禁用行带有 selected 也失败 | 当前源码 |
| FR19, AR5 | CheckboxList.a11y.chromium.spec.ts 的 focus-visible 和 forced-colors-focus 用例 | 键盘焦点;强制颜色 | 失去焦点指示器即失败。证据缺口:没有测试统计焦点指示器(FR19)。 | audit:CheckboxListItem/visual |
| 方向 | RTL 审计目标 core-checkboxlist--rich-descriptions(apps/storybook/rtl-audit/targets.json);CheckboxList.a11y.chromium.spec.ts 的 rtl 用例 | LTR 与 RTL | 复选框和末端内容无法交换行内顺序。 | audit:CheckboxListItem/layout |
| ORD1–ORD4, PR1 | 由 FR4–FR10 和 FR13 行覆盖。证据缺口:没有测试断言不存在观察器、计时器或全局监听器 | — | — | audit:CheckboxListItem/behavior |
当前状态影响¶
- 无处理器的项(FR14)。 一个带有
isChecked且没有onCheck的独立项被呈现为可编辑复选框,但激活不会改变任何内容(WCAG 2.2 4.1.2)。共享复选框套件将其记录为已知失败;其含义为 OQ1。 - 激活后的混合状态(FR5)。 一个独立混合项在激活后若其值仍保持混合,则会失去原生混合状态,正如
component:CheckboxInput所记录。 - 两个焦点指示器(FR19)。 键盘焦点同时绘制行轮廓和复选框环,与
architecture:interaction-modalityINV3 相悖。
决策日志¶
没有组件级决策。CheckboxListItem 应用 spec:AST-021 和 spec:AST-085。
未决问题¶
- OQ1 — 一个带有
isChecked且没有onCheck的独立项意味着什么?(human-api)选择只读、不可用或无效用法,与匹配的 CheckboxInput 问题保持一致。 - OQ3 — 哪个元素拥有消费者 DOM 输入?(
human-api)数据和 ARIA 到达行,而onClick在行类型处理器的上下文中运行于复选框上。 - OQ4 — 只读项的点击是否应该传播?(
human-api)当前没有权威方拥有祖先传播。该停止行为的存在,是因为共享的 clickable-container 钩子否则会把来自其aria-readonly委托目标的点击重新委托回它。 - OQ5 — 选中行应显示什么样的悬停和按下反馈?(
human-design)选中行的填充目前会替换两个覆盖层。 - OQ6 — 哪个元素绘制选项的焦点环?(
human-design)architecture:interaction-modality/INV3要求一个指示器;RadioList 组合了同样的两个绘制者。
内容边界¶
本文件不重复消费者 prop 表和示例、当前审计结果、实现步骤或组契约。它提供指向其所有者的链接。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx