跳转至

CheckIndicator 组件契约

契约一览

领域 契约
公共契约 CheckIndicator 从 @astryxdesign/core/Indicator 导出;state 为必填,size 默认为 md,isDisabled 默认为 false,且 children 可替换内置标记。
行为 该组件仅在选中状态下绘制装饰性的勾选图形。可浅层渲染的 children 在任一状态下都会替换该图形;未选中且无替换内容时不渲染任何元素。
最终用户影响 用户从所属控件获得一个选择提示,而不会出现重复的无障碍对象,也不会在未选中行旁边出现空占位符。
构建者影响 构建者可以替换名为 check 的指示器,或组合宿主拥有的类与样式,而无需接管所属控件的语义。
兼容性/就绪度 记录已发布行为;没有 API、默认值或 DOM 变更。选中状态的图形路径会丢弃声明的 ref;已列在“当前状态影响”下,修复仍未完成(OQ1)。
审查检查项 拒绝:丢失 aria-hidden;未选中默认状态中的标记;缺少选中标记;丢失受支持的 DOM/样式透传;更改替换优先级;新增组件拥有的主题目标;或在 OQ1 被决定后,选中路径仍丢弃 ref。
治理规则 architecture:public-component-api/INV1,INV5,INV6,INV8,INV9;architecture:component-theming-surface/INV3–INV6;architecture:component-test-sufficiency/INV1–INV7,INV10–INV11.

本表是审查投影;以下正文为权威依据。

意图

渲染由宿主使用的可替换、装饰性的勾选标记,用于表示某个选项已被选中,而不承担选择语义、交互或持久控件外观(chrome)的所有权。

兼容性与迁移

  • 已发布的默认值保留:是
  • 兼容性分类:记录已发布行为;没有公共 prop、默认值、导出或 DOM 变更
  • 受控/非受控行为:不适用;state 由所有者提供
  • 迁移决策:无;公共组件和 check 注册名称保持不变

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

所有权边界

拥有

  • 选中图形、未选中时的空缺、禁用颜色、尺寸映射、替换内容优先级和装饰性根节点。
  • 在每个渲染的根节点上支持中性的 DOM 和样式透传。替换内容的 span 接收声明的 ref;当前选中的 Icon 路径不会。

不拥有 / 非目标

  • 选择角色、无障碍名称、状态、焦点、键盘、激活或忙碌语义——由组合控件拥有。
  • 持久复选框或单选按钮外观(chrome)——由 component:CheckboxIndicator 或 component:Indicator 拥有。
  • 行放置和逻辑边缘布局——由宿主组件拥有。
  • 使用方提供的替换内容的行为或无障碍特性。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 所有者 稳定性 无效值行为
state unchecked, checked 选择内置勾选图形是不存在还是存在。 所有渲染路径。 必填 component:CheckIndicator 稳定 被公共类型拒绝
size sm, md 选择共享的指示器尺寸;当前两个值都使用 sm 的 Icon 图形。 选中状态和替换内容的根节点。 md component:CheckIndicator 稳定 被公共类型拒绝
禁用外观 启用、禁用 镜像所属控件的禁用颜色,而不产生语义。 选中状态和替换内容的根节点。 启用 component:CheckIndicator 稳定 仅接受布尔值
replacement content 浅层可渲染或为空 当 isRenderable(children) 返回 true 时,在任一状态下替换内置标记。React 元素和容器即使后代不渲染任何内容也会走此分支。 每个状态;替换内容会创建一个 span 根节点。 内置标记路径 component:CheckIndicator 稳定;空容器策略未决(OQ2) 不支持的值的处理遵循 React 渲染行为

行为与布局契约

ID 不变量 依据
FR1 当 state="checked" 且不存在替换内容时,组件 MUST 渲染一个装饰性对勾图形,并且 MUST 在调用方透传之后设置自身的 aria-hidden="true"。 随附源码;architecture:public-component-api/INV5
FR2 当 state="unchecked" 且不存在替换内容时,默认组件 MUST 不渲染任何元素。 随附源码、文档、测试和 stories
FR3 替换在两个状态下都采用浅层 isRenderable(children) 优先级:nullish 值、布尔值和空字符串保留内置状态行为;React 元素和容器即使后代不渲染任何内容,也会替换内置标记(OQ2)。 随附源码和回归测试
FR4 每个渲染出的根节点 MUST 保留受支持的 DOM props、className、style 和 xstyle,同时保持组件拥有的无障碍优先权;声明的 ref MUST 到达渲染后的根节点(architecture:public-component-api/INV8)。实现缺口:替换内容的 span 会接收 ref,但选中状态的 Icon 路径会丢弃它(OQ1)。 architecture:public-component-api/INV5,INV6,INV8;当前源码
FR5 内置的 checked 标记 MUST 保持为 Icon 拥有的绘制器,并与宿主提供的类位于同一元素上;未经批准的契约变更,CheckIndicator MUST NOT 添加包装器或不同的公共目标。 随附源码;architecture:component-theming-surface/INV3–INV5
FR6 禁用态颜色和替换内容颜色 MUST 继续使用语义化 token,而不是原始颜色值。 随附源码;当前 token 与主题架构

允许的变化

  • AV1 — 主题绘制。 Icon 目标和宿主拥有的类可以更改受支持的绘制,而不改变状态或语义所有权。
  • AV2 — 替换组件。 当替换组件保留此公共 prop 和装饰性所有权契约时,主题可以替换名为 check 的指示器。

代表性状态

状态 必需不变量 允许的变化
未选中 不渲染任何内置元素。 替换组件可以绘制。
选中 渲染一个装饰性对勾图形。 Icon 与宿主拥有的主题绘制。
禁用 选中或替换内容保持所请求的状态,并使用禁用态的语义化颜色。 主题拥有的非激活处理方式。
replacement content 浅层可渲染内容在居中的固定尺寸装饰性根节点中替换内置标记。 调用方拥有的装饰性内容。

转换与优先级顺序

  • ORD1 — 渲染优先级。 浅层替换内容判断 → 未选中的缺失或选中的 Icon → 调用方透传 → 组件自有的 aria-hidden → 合并后的主题/样式输入。

性能与资源

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

无障碍契约

  • AR1 — 装饰性归属。 每个渲染出的根节点保持 aria-hidden;组合控件拥有 role、名称、状态、焦点、键盘、激活和表单语义。
  • AR2 — 替换边界。 替换内容在隐藏根节点内是装饰性的,且 MUST NOT 是所属控件选中或忙碌状态的唯一语义表达。

设计关系

解剖结构或状态 设计要求 呈现权威 层级角色 组件契约
Chrome CheckIndicator 有意不拥有任何持久化 chrome。 已发布实现中观察到的呈现 不适用 FR2, FR5
状态标记 选中状态渲染共享的装饰性对勾 Icon。 Icon 所拥有的当前主题架构 辅助状态提示 FR1, FR5–FR6

共享的 Indicator.doc.mjs 将 CheckboxIndicator、CheckIndicator 和 RadioIndicator 的解剖结构与目标一同列出,因此本记录不包含 anatomy-theming 映射。CheckIndicator 不拥有任何持久化 chrome,并将其内建选中标记委托给 Icon。

家族与系统关系

  • architecture:component-theming-surface 负责目标放置与组合绘制器的归属。
  • architecture:public-component-api 负责导出、透传、样式组合、ref 和兼容性要求。
  • architecture:component-test-sufficiency 负责每个关键承诺和不同风险分区所需的证据。

验证映射

契约 验证 代表性状态 变更或失败预期 审计章节
FR1, FR2, FR3 Indicator.test.tsx 中 CheckIndicator 的状态与替换场景;falsy children 场景 选中、未选中、空标量、可见子元素、0 移除字形、添加未选中的 chrome,或选择错误的 children 分支均会失败。 audit:CheckIndicator/behavior
FR1, AR1 Indicator.test.tsx 中的装饰性契约场景 字形与替换根节点;调用方传入 aria-hidden={false} 调用方可暴露的根节点会导致失败。证据缺口:没有测试断言替换内容不是状态的唯一表达(AR2)。 audit:CheckIndicator/accessibility
FR4 Indicator.test.tsx“在两条渲染路径上转发调用方 props 和样式” 两条渲染路径 调用方 DOM prop 若停止到达任一根节点,或 className 若停止到达替换 span,则失败。证据缺口:没有测试断言选中字形路径上的 className、style 或 xstyle,替换 span 上的 style 或 xstyle,或任一路径上的 ref(选中路径的 ref 是 FR4 缺口)。 audit:CheckIndicator/api
FR5, FR6 themingTargets.test.ts 选中的字形 渲染出的 class 若未出现在文档记录的 targets 中,则失败。证据缺口:没有测试断言没有包装器将宿主 class 与 Icon 绘制器分隔开,或禁用色与替换色使用语义化 token。 audit:CheckIndicator/theming
ORD1, PR1 由 FR1–FR4 行覆盖。证据缺口:没有测试断言不存在状态、Effect 或监听器 — — audit:CheckIndicator/behavior

当前状态影响

  • Checked-path ref (FR4). 当 CheckIndicator 绘制其选中的字形(checked glyph)时,声明的 ref 为 null,这与 architecture:public-component-api INV8 相悖;修复方案为 OQ1。

决策日志

无组件级决策。

开放问题

  • OQ1 — CheckIndicator 是否应通过在选中路径中持有一个稳定的 span 根元素来保留其声明的 HTMLSpanElement ref,还是应更改公共 ref 合约以匹配 Icon 拥有的 painter? (human-api) 当前的选中路径返回 null;任一修正都会改变已发布的 DOM 或 ref 合约。
  • OQ2 — 空的 React 容器是否应继续抑制内置状态标记? (human-api) FR3 记录它们目前正是如此。

内容边界

本文件不重复消费者 prop 表/示例、当前审计结果、实现步骤或族/系统规则。它提供指向其归属方的链接。

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