跳转至

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-modality INV3 相悖。

决策日志

没有组件级决策。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