CheckboxList 组件合约¶
合约概览¶
| 领域 | 合约 |
|---|---|
| 公开合约 | CheckboxList 是一个带标签的 role="group",由 CheckboxListItem 行组成。value 数组选择受控集合模式(onChange、changeAction);没有它时,其条目为独立条目。该组拥有命名、描述、禁用、禁用原因、只读、待处理值和状态。每个选项的行为为 component:CheckboxListItem。 |
| 行为 | 该组为其选项提供命名和描述,跟踪每个 changeAction 处于待处理状态的值,以便每个正在保存的选项保持忙碌,而其他选项保持可交互,并将禁用、只读和状态应用于每个选项。 |
| 最终用户影响 | 用户可以识别该组,通过指针、触摸和键盘操作每个选项,了解某个组不可用的原因,并查看哪些选项仍在保存。 |
| 构建者影响 | 构建者通过传递 value 来选择集合模式,然后提供稳定的条目 value。没有消息的状态的渲染方式在此处仍是开放问题(OQ3);每个选项的开放问题见 component:CheckboxListItem。 |
| 兼容性/就绪性 | 新增 isOptional(FR16)和 isRequired(FR17),两者默认均为 false。每个复选框在错误状态下获得 aria-invalid;没有其他 API、默认值或 DOM 变更。 |
| 审查检查 | 拒绝以下情况:某个待处理值在另一个选项被切换时失去忙碌状态或重新切换守卫;组命名或描述 id 被丢弃;在组被禁用或只读时进行切换;未经所有者决策而引入新的目标或状态 API。每个选项的检查见 component:CheckboxListItem。 |
| 约束规则 | architecture:public-component-api/INV1–INV9;architecture:component-theming-surface/INV3–INV6;architecture:interaction-modality/INV1–INV5;architecture:component-test-sufficiency/INV1–INV7;architecture:knowledge-contracts/INV2;spec:AST-021/FR8–FR10;spec:AST-038/FR7;spec:AST-085/FR1, FR7;family:input-fields/FR10;WCAG 2.2 1.3.1, 2.1.1, 4.1.2。 |
此表是评审投影;以下正文为权威依据。
意图¶
呈现一小组带标签的独立复选框选项,其选中、可用、只读、忙碌和状态在指针、触摸、键盘和辅助技术中保持一致。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性类别:新增
isOptional(FR16)和isRequired(FR17),两者默认均为false;没有其他公开属性、默认值或导出变更;每个复选框在错误状态下获得aria-invalid - 受控/非受控行为:集合模式由
value控制;独立条目遵循component:CheckboxListItem;不存在非受控模式 - 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
所有权边界¶
拥有
- 带标签的复选框组、其
checkbox-list目标、组的描述、状态和禁用原因关系,以及其base、container*和control*属性所在的位置。 - 与 CheckboxListItem 共享的集合状态:选中成员关系、变更排序、乐观待处理值和组级可用性。
- 组合的选项结构及其目标布局(见下方的主题结构)。
不拥有 / 非目标
- 每个选项的行为——复选框、命名和描述、独立模式、行表面委托和
onClick路由、条目禁用和加载状态、密度尺寸以及选中行填充——由component:CheckboxListItem拥有。 - 列表和选项行呈现——由
component:List拥有;其list-item目标仅到达行的根元素。 - 复选框控件、其指示器、焦点环和按下覆盖层——由
component:CheckboxInput和 CheckboxIndicator 拥有。 - 组标签和验证消息呈现——由
family:input-fields下的 Field(共享所有者部分)和component:FieldStatus拥有。 - 加载指示器呈现——由
component:Spinner拥有;工具提示行为——由useTooltip拥有。 - 针对行、描述或调用方内容的新目标或反映状态。
公开概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
| 组命名 | label、isLabelHidden、description | 命名并描述 role="group";隐藏的 label 仍会对其进行命名。 | 所有状态。 | label 必填;可见 | 调用方和 Field | 稳定 | 被公共类型拒绝 |
| 可选性 | isOptional、isRequired | 在组标签后显示 Field 的可选或必填指示;isRequired 还需要至少一个已勾选的复选框(FR17)。 | 所有状态。 | false | 调用方和 Field | 稳定 | 仅限布尔值 |
| 集合值 | value 数组存在或不存在 | 存在:该组拥有其项目的选中成员资格和变更处理。不存在:其项目是独立的。 | 所有状态。 | 不存在 | 调用方和组件 | 稳定 | 在集合模式下,没有 value 的项目会抛出异常(item FR4) |
| 变更路径 | onChange、changeAction、两者都有、两者都没有 | 报告下一个值数组;changeAction 在带有乐观值的过渡中于 onChange 之后运行。 | 集合模式。 | 两者都没有 | 调用方和组件 | 已发布;无处理程序的含义尚未确定 | 没有处理程序意味着组件不拥有变更 |
| 可用性 | 启用、isDisabled、带 disabledMessage 的 isDisabled | 阻止每个项目切换,项目通过 aria-disabled 保持可聚焦;原因会添加一个组工具提示。 | 原因仅在 isDisabled 下适用。 | 启用 | 组件 | 稳定 | 没有 isDisabled 的原因不会渲染任何内容 |
| 只读 | isReadOnly | 使每个项目变为只读。 | 组范围内。 | false | 组件 | 稳定 | 仅限布尔值 |
| 待处理值 | changeAction 处于待处理状态的值 | 每个待处理值的项目渲染为忙碌状态;切换另一个项目不会清除它;并发值会一起稳定。 | 带有 changeAction 的集合模式。 | 无 | 组件 | 稳定 | 仅限过渡状态 |
| 状态 | warning、error、success、可选消息 | 消息会在列表后渲染一个独立的 FieldStatus 并描述该组;错误会使每个复选框变为 aria-invalid。 | 所有状态。 | 无 | 调用方和 FieldStatus | 已发布 | 没有消息的状态不会渲染任何内容 |
| 行布局 | density 紧凑/均衡/宽松;hasDividers;width | Density 作用于 List 及其行;分隔线分隔行;宽度会同时调整标签、列表和状态的大小。 | 所有状态。 | 均衡;无;固有 | 组件和 List | 稳定 | 被公共类型拒绝 |
| 透传 | CheckboxList 其余属性、ref、container*、control* | 基础属性和 ref 到达 role="group";container* 到达 Field 框;control* 到达组元素。 | 所有状态。 | 无 | 组件 | 稳定 | 根元素不接受 xstyle、className、style |
项目属性(label、aria-label、description、endContent、isChecked、
onCheck、项目的 isDisabled、isLoading 以及项目透传)属于
component:CheckboxListItem 的概念。
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 渲染 MUST 将 CheckboxListItem 子元素放置在 role="group" 内的 List 中,该 group 通过 aria-labelledby 由组标签命名;其 aria-describedby MUST 按此顺序列出任何存在的调用方描述,然后是描述、状态消息和禁用原因工具提示。 |
已发布的源代码;聚焦测试;WCAG 1.3.1 和 4.1.2 |
| FR2 | CheckboxList 根元素 MUST 承载当前的 checkbox-list 目标。 |
已发布的源代码和公开文档 |
| FR4 | 状态消息 MUST 通过列表后的独立 FieldStatus 渲染。 | 已发布的源代码、聚焦测试和 Chromium 无障碍测试套件 |
| FR6 | 使用 value 数组时,组 MUST 向其项目提供成员资格,使用项目提议的下一个数组调用 onChange(component:CheckboxListItem FR4),然后在带有乐观值的过渡中,使用同一数组运行 changeAction。 |
已发布的源代码和聚焦测试 |
| FR7 | 组 MUST 跟踪每个 changeAction 处于待处理状态的值,并将其暴露给其项目,每个项目都会渲染为忙碌状态(component:CheckboxListItem FR7);切换另一个项目 MUST NOT 清除较早的待处理值。并发待处理的值会一同落定,之后所有忙碌状态都会清除。 |
已发布的公开 changeAction promise;聚焦回归测试;Chromium 无障碍测试套件 |
| FR9 | 组 isDisabled MUST 使每个复选框通过 aria-disabled 成为可聚焦禁用(component:CheckboxInput FR4)并拒绝切换,且 MUST 在 role="group" 元素上设置 aria-disabled="true",如同 component:ButtonGroup FR1 所做。当提供 disabledMessage 时,原因提示会在组悬停和键盘聚焦时打开,且该原因 MUST 描述每个可聚焦复选框(spec:AST-085 FR5、FR7)。实现差距:原因仅描述 role="group",因此聚焦的复选框未被其描述。 |
spec:AST-085 FR1, FR7;已发布的源代码、聚焦测试和共享复选框绑定 |
| FR10 | 组 isReadOnly MUST 使组中的每个项只读(component:CheckboxListItem FR8 和 FR10)。 |
已发布的源代码;共享复选框绑定;spec:AST-011 只读词汇 |
| FR13 | density MUST 到达 List 及其行(复选框大小遵循 component:CheckboxListItem FR11);hasDividers MUST 分隔各行,且最后一行之后无分隔线;width MUST 同时调整标签、列表和状态的大小。 |
已发布的源代码、文档和 Chromium 无障碍套件 |
| FR14 | 带消息的错误 status 会渲染该消息(FR4),且错误 status 使每个复选框 aria-invalid="true",因此当每个复选框获得焦点时,屏幕阅读器会播报无效状态。实现差距:无消息的 status 不渲染任何内容;其含义为 OQ3。 |
已发布的源代码;spec:AST-002/FR15 |
| FR15 | 基础 props(包括 ARIA 和 ref)MUST 到达 role="group";调用方的 aria-labelledby 与组标签合并,调用方的 aria-describedby 排在前面。在渲染 Field 框的情况下,container* MUST 到达该 Field 框(在 horizontal-labels FormLayout 中无渲染,container* 无效并发出警告),control* MUST 到达组元素;根级 xstyle、className 和 style 不被接受。 |
family:input-fields FR10;CheckboxList.fr10.test.tsx |
| FR16 | isOptional MUST 以 isOptional 的形式到达组的 Field,因此组标签会显示可选指示符,除非最近的 FormLayout 默认将字段设为可选(component:FormLayout FR5)。空选择是一种答案,因此复选框组不会从表单默认值获取必填状态(component:FormLayout FR5 的例外):无论是否提供 isOptional,其复选框都不会因此携带 aria-required,且表单默认值不会在它们上设置原生 required。 |
CheckboxInput 与 RadioList 的一致性;WAI-ARIA 1.2 group 没有 aria-required,且在每个复选框上设置 aria-required 会要求每个选项 |
| FR17 | isRequired 将组标记为必填。其名称按照与每个输入字段相同的规则(family:input-fields)显示输入字段的必填标记;因此,如果表单默认已将字段标记为必填,则不显示标记,这与任何字段一致。当没有复选框被选中时,第一个既未禁用也未只读的复选框会携带原生 required,因此浏览器会阻止提交并将其聚焦,同时显示自己的消息;一旦有任何复选框被选中,则没有复选框携带 required。空组被视为缺失;应用的 status 保持为可见错误文本,Astryx 不添加自己的消息。 |
所有者决策;family:input-fields;HTML 约束验证 |
每个选项的需求由 component:CheckboxListItem 负责(architecture:knowledge-contracts/INV2)。
Allowed variation¶
- AV1 — 组内容。 标签、描述、状态消息和宽度可在其公共类型范围内变化。
- AV2 — 主题绘制。
checkbox-list目标以及组合组目标可以更改允许的视觉属性,而不改变语义或状态优先级。
选项变体由 component:CheckboxListItem AV1–AV3 负责。
Representative states¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 默认集合 | 命名的组、选项列表和行均渲染;成员关系传递到每个选项项 | 选项内容和已选值 |
| 待处理值 | 每个待处理值都使其选项项保持忙碌,直到所有待处理值确定 | 哪些选项处于待处理状态 |
| 带原因的组禁用 | 复选框保持可聚焦但不可操作;原因可通过悬停、焦点和 AT 访问 | 原因文本 |
| 组只读 | 每个选项项均为只读 | 哪些值被选中 |
| 带消息的组状态 | 分离的 FieldStatus 跟随该组并对其进行描述 | 错误、警告或成功状态 |
Transformation and precedence order¶
- ORD1 — 选中状态。 集合
value→ 乐观待处理值 → 每个选项项读取的成员关系(component:CheckboxListItemORD1)。 - ORD2 — 切换。 选项项的提议下一数组(
component:CheckboxListItemORD2)→onChange→changeAction(在一个将切换值添加到待处理集合的过渡中)。 - ORD3 — 可用性。 组禁用优先,并保持每个复选框可聚焦;组原因添加的是工具提示,而非可操作性;组只读仅适用于变更操作。
Performance and resources¶
- PR1 — 资源有界。 组件自身不拥有任何 observer 或全局监听器。工具提示监听器的作用域限定为组元素及其生命周期。一个必选组(FR17)在其生命周期内将其选项注册到 Core 的共享 mutation observer,因此重新排序会更新哪个复选框携带
required。
当前测量结果应归入审计记录;本小节仅负责持久约束及其验证目标。
Accessibility contract¶
- AR1 — 组标识。 组名称及其描述、状态和禁用原因关系 MUST 保持可通过编程确定。
- AR2、AR3、AR5 — 选项语义、键盘一致性和忙碌感知由
component:CheckboxListItem的 AR1、AR2 和 AR4 负责。 - AR4 — 禁用原因。 在切换仍被阻止的情况下,组原因 MUST 保持可通过键盘焦点和辅助技术发现。
Design relationships¶
| 结构或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 组 | 包含当前复选框组的组成。 | 当前源代码和公开文档 | 支撑 | FR1, FR2 |
| 选项列表 | 呈现由 List 拥有的列表和行根。 | 当前源代码 | 支撑 | FR1, FR13 |
| 选项行 | 呈现每个选项的复选框、内容、忙碌指示器和选中行填充。 | component:CheckboxListItem |
突出 | component:CheckboxListItem FR1–FR13 |
| 状态消息 | 呈现该组当前的状态。 | 当前共享组件来源 | 辅助 | FR4 |
主题化解剖结构¶
{
"Group": {"target": "checkbox-list"},
"Group label": {
"delegatesTo": {"owner": "component:Field", "target": "field-label"}
},
"Description": {
"none": {
"reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
}
},
"Options list": {
"delegatesTo": {"owner": "component:List", "target": "list"}
},
"Option row": {
"delegatesTo": {"owner": "component:List", "target": "list-item"}
},
"Checkbox": {
"delegatesTo": {
"owner": "component:CheckboxInput",
"target": "checkbox-indicator"
}
},
"Option label": {
"none": {
"reason": "unsettled: Item rather than Text renders the stable Option label in a separate untargeted span; future exposure still needs an owner decision"
}
},
"Option description": {
"none": {
"reason": "unsettled: Item rather than Text renders the stable Option description in a separate untargeted span; future exposure still needs an owner decision"
}
},
"End content": {
"none": {
"reason": "intentional: End content is caller-provided content outside CheckboxList's public theming ownership"
}
},
"Spinner": {
"delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
},
"Status message": {
"delegatesTo": {
"owner": "component:FieldStatus",
"target": "field-status"
}
}
}
Description 仍是一种稳定的消费方解剖结构,但当前没有公共目标可以到达它。呈现选项标签和描述的是 Item 而不是 Text,且位于独立的未设目标的 span 中;因此二者既不委托给 Text,也不继承行根 list-item 目标;未来的暴露仍未确定。富标签内容和尾部内容由调用方提供,而尾部内容有意留在 CheckboxList 的公共主题化所有权之外。Option row 委托会作用到行表面;在选中、启用且可编辑的行上,还会反映其 selected 状态(component:CheckboxListItem FR15)。
族系与系统关系¶
architecture:public-component-api负责导出可达性、透传保留、样式组合、refs 和已发布变更规则。architecture:component-theming-surface负责解剖结构资格认定、事实性的none处置、保留组合的目标所有权以及状态反映。architecture:interaction-modality负责焦点可见性,以及聚焦复选框与绘制其环的元素之间的边界。architecture:knowledge-contracts/INV2将每个逐选项事实保留在component:CheckboxListItem中,而不是复制到这里。spec:AST-021负责 CheckboxListItem 的可复用复选框无障碍绑定及其确切已知失败生命周期。spec:AST-011将isReadOnly记录为可见、可聚焦、不可编辑值的名称。spec:AST-038/FR7在层边界处停止 CheckboxList 上下文;层内的项目需要自己的 provider。component:CheckboxListItem拥有此组所组合的逐选项契约。- List、CheckboxInput、Field、FieldStatus、Spinner 和 Tooltip 在被 CheckboxList 组合时保留其现有的公共目标与行为契约。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, AR1 | CheckboxList.test.tsx 的 group-role、group-description 和 disabledMessage 用例 |
具名分组;描述加状态;禁用原因 | 缺少组名,或描述与状态顺序错误,则失败。证据缺口:没有测试断言调用方描述在前,或禁用原因在后。 | audit:CheckboxList/accessibility |
| FR2, FR15 | CheckboxList.test.tsx 的 ref 和 container 用例;CheckboxList.fr10.test.tsx |
独立使用;horizontal-labels FormLayout |
不挂在 group 上的 ref、不在 Field 盒子上的 container*、或不挂在 group 上的 base prop 都会失败。 |
audit:CheckboxList/api |
| FR4、FR14 | CheckboxList.test.tsx 的错误状态用例,包括每个复选框的 aria-invalid;CheckboxListErrorStatus.a11y.chromium.spec.ts |
带消息的错误 | 缺少状态消息则失败。证据缺口:没有测试断言无消息时的空渲染。 | audit:CheckboxList/accessibility |
| FR6、FR7 | CheckboxList.test.tsx 的添加、移除和挂起用例;CheckboxList.a11y.chromium.spec.ts 的 pending-single、pending-concurrent 和 pending-settled 用例 |
添加;移除;一个和两个挂起的值;已稳定 | 错误的数组、提前清除的挂起值,或持续到稳定之后的忙碌状态,均会导致失败。 | audit:CheckboxList/behavior |
| FR9、FR10、AR4 | CheckboxList.test.tsx 的组禁用(包括组的 aria-disabled)、disabledMessage 和只读用例;ListGroupDisabled.a11y.chromium.spec.ts;共享复选框绑定 |
组禁用;带原因;只读项 | 失去 Tab 焦点、在禁用状态下切换,或只读切换,均会导致失败。证据缺口:没有测试断言聚焦的复选框不会被该原因描述。 | audit:CheckboxList/accessibility |
| FR13 | CheckboxList.test.tsx 的密度用例;CheckboxList.a11y.chromium.spec.ts 的密度、分隔线、320 像素和 RTL 用例 |
紧凑、均衡、宽敞;分隔线;窄屏;RTL | 密度、分隔线、溢出或方向传感器失败。证据缺口:没有测试断言 width 同时调整标签、列表和状态的尺寸。 |
audit:CheckboxList/layout |
| FR16 | CheckboxList.test.tsx 的可选指示符和 FormLayout 默认用例 |
isOptional;必填默认下的未标记和可选组;可选默认;聚焦时切换 |
从 Field 中移除 isOptional、在可选默认下显示它、必填默认下带 aria-required 的组复选框,或在 isOptional 变化时重新挂载行,均会导致失败。 |
audit:CheckboxList/accessibility |
| FR17 | CheckboxList.required.test.tsx |
标记;必填默认表单;未选中任何框;选中一个;最后一个框未选中;第一个框禁用;组禁用;只读组;独立项;带 key 的重排;移除项 | 缺少标记、必填默认下出现标记、未选中任何框时提交、选中一个时阻止提交,或超过一个框带有 required,均会导致失败。 |
audit:CheckboxList/accessibility |
| ORD1–ORD3、PR1 | ORD1 和 ORD2 由 FR6 和 FR7 行覆盖,ORD3 由 FR9 和 FR10 行覆盖。证据缺口:没有测试断言不存在观察者或全局监听器。 | — | — | audit:CheckboxList/behavior |
| 本地目标源 | themingTargets.test.ts;CheckboxList.test.tsx 的 ref 和容器用例 |
checkbox-list |
渲染的类不在文档化目标中,或 Field 根节点上缺少 astryx-checkbox-list,则失败。 |
audit:CheckboxList/theming |
| 主题化结构映射 | scripts/check-knowledge.mjs |
规范结构与当前局部目标 | 规范键漂移、无效处置或目标拼写,或存在未认领的当前局部目标,均会导致验证失败。 | audit:CheckboxList/theming |
每个选项的验证由 component:CheckboxListItem 的验证映射负责。当前仓库检查不解析 delegatesTo 的拥有者与目标配对;上述配对与当前的 Field、List、CheckboxInput、Spinner 和 FieldStatus 目标相匹配。
当前状态影响¶
- 组原因(FR9)。 组的
disabledMessage仅描述role="group",因此聚焦的禁用复选框不会由其描述, 这违反spec:AST-085的 FR5 和 FR7。 - 没有消息的状态(FR14)。 没有消息的状态不会渲染 任何内容;其含义见 OQ3。
- 必填宣告(FR17)。
role="group"无法携带aria-required,且浏览器会将未勾选的required复选框暴露为无效 而非必填,因此当组为空时,只有其第一个复选框报告该状态; 必填的RadioList则会改为在每个单选按钮的状态上保留其无效状态 (component:RadioListFR6)。
决策日志¶
没有组件局部决策。CheckboxList 应用 spec:AST-021、
spec:AST-085 和 family:input-fields 的 FR10。
开放问题¶
- OQ3 —— 没有消息的状态应渲染什么? (
human-api) 每个选项的相关问题位于component:CheckboxListItem。
内容边界¶
本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤、每选项契约或共享组件契约;它链接到这些内容的拥有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx