跳转至

CheckboxIndicator 组件契约

契约概览

领域 契约
公共契约 CheckboxIndicator 从 @astryxdesign/core/Indicator 导出;state 为必需项,size 默认为 md,isDisabled 默认为 false,children 可替换内置标记。
行为 始终渲染装饰性复选框外观。除非浅层 isRenderable() 谓词将 children 视为替换内容,否则选中和不确定状态会绘制对应的标记。
终端用户影响 用户会收到一个可见的复选框状态提示,而所属控件保留所有语义、焦点、键盘和激活行为。
构建者影响 构建者可重新设置标准目标的样式或替换指定的指示器,而无需接管所属控件的语义。
兼容性/就绪状态 记录已发布行为;无 API、默认值或 DOM 变更。仅输出标准的 checkbox-indicator 目标。
审查检查 拒绝丢失 aria-hidden、缺失状态标记、丢弃透传/ref/样式、更改替换优先级,或在根上出现第二个目标别名。
治理规则 architecture:public-component-api/INV1,INV5,INV6,INV8,INV9;architecture:component-theming-surface/INV3–INV8,INV12;architecture:component-test-sufficiency/INV1–INV7,INV10–INV11。

此表是审查投影;下文正文具有权威性。

意图

渲染可替换的装饰性视觉元素,用于传达复选框所有者的未选中、选中或不确定状态,而不接管复选框的语义或交互。

兼容性与迁移

  • 已发布默认值保留:是
  • 兼容性类别:记录已发布行为;无公共 prop、默认值、导出或 DOM 变更
  • 受控/非受控行为:不适用;state 由所有者提供
  • 迁移决策:无

使用者的迁移说明应放在使用者文档和发布说明中。

所有权边界

拥有

  • 装饰性复选框外观、状态标记、禁用外观、尺寸、替换内容优先级以及组件主题化目标。
  • 根 DOM ref 以及受支持的中性 DOM 和样式透传。

不拥有 / 非目标

  • 复选框角色、无障碍名称、焦点、键盘、激活、表单参与或忙碌语义——由组合控件拥有。
  • 行放置和逻辑边缘布局——由宿主组件拥有。
  • 使用者提供的替换内容的行为或可访问性。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
state unchecked、checked、indeterminate 选择内置的视觉状态。 所有渲染路径。 必需 component:CheckboxIndicator 稳定 由公共类型拒绝
size sm、md 选择 20px 或 24px 的视觉框及匹配的标记几何。 所有状态。 md component:CheckboxIndicator 稳定 由公共类型拒绝
禁用外观 启用、禁用 镜像所属控件的禁用表现,而不产生语义。 所有状态。 启用 component:CheckboxIndicator 稳定 仅接受布尔值
替换内容 浅层可渲染或为空 当 isRenderable(children) 返回 true 时,替换两个内置标记。即使后代未渲染任何内容,React 元素和容器也会走此分支。 所有状态。 内置标记路径 component:CheckboxIndicator 稳定;空容器策略开放(OQ1) 不支持的取值遵循 React 渲染行为

行为与布局契约

| ID | 不变式 | 依据 | | FR1 | 组件 MUST 在每种状态下渲染一个装饰性的 span 外壳,并且在调用方透传之后设置自身的 aria-hidden="true"。 | 已发布的源码;architecture:public-component-api/INV5 | | FR2 | unchecked MUST 不显示任何内置标记,checked MUST 显示对勾,indeterminate MUST 显示短横线。 | 已发布的源码、文档、测试和 stories | | FR3 | 替换使用浅层 isRenderable(children) 优先级:nullish 值、布尔值和空字符串保留状态标记;React 元素和容器会替换它,即使其后代不渲染任何内容(OQ1)。 | 已发布的源码和回归测试 | | FR4 | 根元素 MUST 保留受支持的 DOM props、ref、className、style 和 xstyle,同时保持组件自有的可访问性优先级。 | architecture:public-component-api/INV5,INV6,INV8 | | FR5 | 根目标 MUST 是 checkbox-indicator,即该元素上唯一的目标;不得发出别名目标。 | architecture:component-theming-surface/INV4,INV6;当前测试 | | FR6 | 尺寸、选中或不确定(data-checked)以及禁用状态 MUST 反映在根目标上;对勾和短横线 MUST 保留其专用的 checkbox-indicator-check 和 checkbox-indicator-dash 绘制目标。 | 已发布的源码;architecture:component-theming-surface/INV4,INV6 | | FR7 | 状态转换 MUST 遵循减少动态效果(reduced motion)设置,并且选中/不确定标记在强制颜色(forced-colors)模式下 MUST 保持可感知。 | 已发布的源码和 WCAG 2.2 1.4.11 |

允许的变化

  • AV1 — 主题绘制。 令牌和规范组件目标可以更改颜色、边框、圆角、不透明度及其他允许的视觉属性,而无需改变状态或语义所有权。
  • AV2 — 替换组件。 当替换组件保留此公开 prop 和装饰性所有权契约时,主题可以替换指定的复选框指示器。

代表性状态

状态 必需不变量 允许的变化
unchecked 外壳保持可见,且不显示任何内置标记。 主题拥有的绘制与形状。
checked 外壳和对勾保持可见。 主题拥有的绘制与形状。
indeterminate 外壳和短横线保持可见。 主题拥有的绘制与形状。
disabled 所请求的状态在弱化处理下保持清晰可读,且没有宿主驱动的悬停响应。 主题拥有的非活动处理方式。
replacement content 可浅层渲染的内容会替换同一外壳内的两个内置标记。 调用方拥有的装饰性内容。

转换与优先级顺序

  • ORD1 — 渲染优先级。 调用方透传 → 组件自有的 aria-hidden → 合并的主题/样式输入 → 浅层替换内容决策 → 内置状态标记。

性能与资源

  • PR1 — 纯渲染。 组件不拥有任何状态、Effect、监听器、观察器、计时器或外部资源。

可访问性契约

  • AR1 — 装饰性所有权。 根元素保持 aria-hidden;组合而成的控件拥有角色、名称、状态、焦点、键盘、激活和表单语义。
  • AR2 — 强制颜色。 当作者颜色被强制覆盖时,选中和不确定标记仍可区分。
  • AR3 — 替换边界。 替换内容在隐藏的根元素内是装饰性的,并且 MUST NOT 成为所属控件状态的唯一语义表达。

设计关系

结构或状态 设计需求 呈现权威 层级角色 组件契约
Chrome 语义主题令牌和规范绘制目标 由当前主题架构规定 辅助控件视觉 FR1, FR5–FR7
Checkmark 可见的选中状态标记 已发布实现中的观察结果 辅助状态提示 FR2, FR6–FR7
不确定标记 可见的部分状态标记 从已发布实现中观察到的表现 辅助性状态提示 FR2、FR6–FR7

共享的 Indicator.doc.mjs 将 CheckboxIndicator、CheckIndicator 和 RadioIndicator 的解剖结构与目标合并列出,因此本条记录不包含解剖结构-主题映射。

组件族与系统关系

  • architecture:component-theming-surface 负责目标放置与状态反映。
  • component:Indicator 负责注册表名称 checkbox 与主题替换。
  • architecture:public-component-api 负责导出、透传、样式组合、ref 和兼容性要求。
  • architecture:component-test-sufficiency 负责每条关键承诺及不同风险分区所需证据。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1、AR1 Indicator.test.tsx 装饰性契约用例 选中状态;调用方 aria-hidden={false} 可被调用方暴露的已选中指示器将导致失败。证据缺口:没有测试检查未选中或不确定状态下的 aria-hidden,也没有测试验证替换内容并非唯一的状态表达方式(AR3)。 audit:CheckboxIndicator/accessibility
FR2、FR3 Indicator.test.tsx 默认指示器、替换和假值子元素用例 选中状态且带假值与真实子元素;选中状态且带替换子元素 被移除的勾选标记元素、抑制它的假值子元素、或不替换它的真实子元素,都会导致失败。证据缺口:没有测试检查短横线元素;而且由于两个标记在每个状态下都会渲染,并通过 display 切换显隐,没有测试断言每个状态下可见的是哪个标记。 audit:CheckboxIndicator/behavior
FR4 Indicator.test.tsx 装饰性契约「仍然转发普通属性」用例 普通 DOM 属性 丢失 data-testid、id 或 dir 将导致失败。证据缺口:没有测试断言根元素上的 ref、className、style 或 xstyle。 audit:CheckboxIndicator/api
FR5、FR6 Indicator.test.tsx 复选框目标与规范目标用例;themingTargets.test.ts sm 下的不确定状态;规范目标 缺失或被别名化的 checkbox-indicator 目标,或缺失 data-checked="indeterminate" 或 data-size,将导致失败。证据缺口:没有测试断言选中状态下的 data-checked、复选框的 data-disabled(禁用状态用例渲染的是 RadioIndicator)、或 checkbox-indicator-check 与 checkbox-indicator-dash 目标。 audit:CheckboxIndicator/theming
FR7、AR2 CheckboxInput.test.tsx 强制颜色用例(「编译强制颜色填充,使不确定标记在 Windows 高对比度下依然可见」、「编译强制颜色,使勾选标记在 Windows 高对比度下依然可见」) 强制颜色下的选中与不确定状态 证据缺口:强制颜色用例只要匹配任意注入的规则即可通过,因此移除勾选标记和短横线元素的 CanvasText 规则后测试仍然通过;没有测试断言减少动效(reduced-motion)过渡。 audit:CheckboxIndicator/visual
ORD1、PR1 由 FR1–FR4 行覆盖。证据缺口:没有测试断言不存在状态、副作用或监听器。 — — audit:CheckboxIndicator/behavior

决策日志

无组件本地决策。

开放问题

  • OQ1 — 空的 React 容器在 children 中是否应继续抑制内置状态标记? (human-api) FR3 记录表明当前确实如此。

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