跳转至

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:CheckboxListItem ORD1)。
  • ORD2 — 切换。 选项项的提议下一数组(component:CheckboxListItem ORD2)→ 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:RadioList FR6)。

决策日志

没有组件局部决策。CheckboxList 应用 spec:AST-021、 spec:AST-085 和 family:input-fields 的 FR10。

开放问题

  • OQ3 —— 没有消息的状态应渲染什么? (human-api) 每个选项的相关问题位于 component:CheckboxListItem。

内容边界

本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤、每选项契约或共享组件契约;它链接到这些内容的拥有者。

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