跳转至

Indicator 组件契约

契约一览

领域 契约
公共契约 无变更。@astryxdesign/core/Indicator 导出三个内置指示器(CheckboxIndicator、CheckIndicator、RadioIndicator)、共享的指示器 props 与类型、默认注册表以及按名称解析。
行为 宿主按名称(check、checkbox、radio)绘制装饰性控件视觉。主题中针对该名称的 indicators 条目会在每个按名称解析指示器的宿主中替换它;否则渲染内置指示器。每个指示器都对辅助技术隐藏。
最终用户影响 用户会在按名称解析指示器的组件中看到所选选项、复选框或单选按钮的一致标记,屏幕阅读器用户听到的是宿主控件的语义,而绝不会是重复内容。
构建者影响 无。
兼容性/就绪状态 记录已发布的行为;无 API、默认值或 DOM 变更。三个宿主直接渲染内置指示器,而非按名称解析;列于「当前状态影响」之下。
审查检查 拒绝向辅助技术暴露的指示器、被按名称解析的宿主忽略的主题覆盖、抑制内置标记的 falsy children,或指示器上的 role 或 Tab 停靠点。
治理规则 architecture:component-theming-surface;architecture:public-component-api INV5;architecture:theme-authoring-contract。

此表为审查参考;下文正文具有权威性。

意图

Indicator 是共享的、可替换的装饰性控件视觉集合:所选选项上的标记、复选框绘制的方框以及单选按钮绘制的圆圈。它拥有指示器名称、按名称的主题替换、共享的装饰性 prop 契约,以及 RadioIndicator。消费者用法位于 Indicator.doc.mjs 中。

兼容性与迁移

  • 已发布的默认行为保留:yes;在没有主题覆盖的情况下,check、checkbox 和 radio 解析为内置指示器
  • 兼容性类别:记录已发布的行为;无公共 prop、默认值、导出或 DOM 变更
  • 受控/非受控行为:不适用;宿主提供 state
  • 迁移决策:无

消费者迁移说明属于消费者文档和发布说明。

所有权边界

拥有

  • 核心指示器名称以及将它们映射到内置指示器的默认注册表。
  • 按名称的主题替换以及共享的指示器 prop 契约。
  • RadioIndicator,作为 Indicator.doc.mjs 的内联组件记录,具有 radio-indicator 和 radio-indicator-dot 目标。
  • 宿主放置在元素上的 indicatorScope 标记,该元素的悬停驱动指示器的悬停色调。

不拥有 / 非目标

  • CheckboxIndicator — 由 component:CheckboxIndicator 拥有。
  • CheckIndicator — 由 component:CheckIndicator 拥有。
  • 宿主控件的角色、名称、状态、焦点、键盘和激活 — 由每个宿主拥有(CheckboxInput、RadioList、Selector、菜单行)。
  • 作为 API 的 useIndicator 和 getIndicator — 没有自己模块记录的公共 hook 和函数;除 FR2 所描述的解析外,不受契约约束。

公共概念

概念 封闭值或状态 含义 按变体/方向/状态的可用性 默认值 拥有者 稳定性 无效值行为
指示器名称 check、checkbox、radio,以及增强名称 宿主绘制哪种视觉。 始终。 — component:Indicator 稳定 没有主题提供的增强名称解析为空。
状态 unchecked、checked 和 indeterminate(复选框) 宿主的选中状态。 按指示器系列。 必需 component:Indicator 稳定 TypeScript 拒绝该系列之外的值。
尺寸 sm、md 指示器框尺寸。 始终。 md component:Indicator 稳定 TypeScript 拒绝其他值。
替换内容 可渲染的 children 替代内置状态标记绘制的内容。 始终。 无 component:Indicator 稳定 Nullish、boolean 和空字符串 children 保留内置标记。

行为与布局契约

ID 不变量 依据
FR1 默认注册表精确地将 check 映射到 CheckIndicator,checkbox 映射到 CheckboxIndicator,radio 映射到 RadioIndicator。 当前测试
FR2 宿主按名称从最近的主题中解析指示器:该名称在主题的 indicators 条目中的值优先,否则使用内置指示器。一次覆盖会到达每个解析该名称的宿主。Tokenizer 底部弹层直接渲染 CheckboxIndicator 和 RadioIndicator,因此主题的 checkbox 或 radio 条目无法到达它。增强名称仅在主题提供时才解析。 architecture:theme-authoring-contract;当前测试
FR3 每个内置指示器的根元素在调用方的 props 之后设置 aria-hidden="true",因此调用方无法将其暴露;公共 props 类型拒绝 role 和 tabIndex。指示器接收 state、size、isDisabled 和 children,并且不接收任何会赋予它们语义的内容。 architecture:public-component-api INV5;当前测试
FR4 可渲染的 children 会替换指示器内部的内置状态标记;nullish、布尔值和空字符串 children 保留它,而 0 算作内容。 当前测试
FR5 RadioIndicator 渲染一个圆形的 span 元素(20 或 24 CSS 像素),其边框和填充随状态而变化:未选中时在表面(surface)上显示强调边框,选中时显示强调色填充,内部有一个 on-accent 圆点(8 或 10 CSS 像素)。禁用会将不透明度减半并弱化边框(以及未选中时的填充)。在支持悬停的指针下,悬停宿主的 indicatorScope 会使其着色。在强制颜色模式下,圆点保持可见。在减少动态效果(reduced motion)下,过渡是瞬时的。圆形和圆点以 50% 半径绘制,绝不用 --radius-full 胶囊(pill)token:圆形标记一个单选按钮,因此将胶囊做成方形的主题仍保留圆形的单选按钮,而想要方形单选按钮的主题则需要覆盖此组件。 当前源码和测试
FR6 RadioIndicator 的根元素带有 astryx-radio-indicator,并包含 data-size、data-checked 和 data-disabled;圆点带有 astryx-radio-indicator-dot,并包含 data-size。不会发出别名目标。调用方 props、ref、className、style 和 xstyle 都会到达根元素。 architecture:component-theming-surface;当前测试

允许的变化

  • AV1 — 替换。 主题可以将任何已命名的指示器替换为符合 FR3 的组件。
  • AV2 — 主题绘制。 主题可以在不替换内置指示器的情况下,通过其目标重新设置内置指示器的样式。

代表性状态

状态 必需不变量 允许的变化
无主题覆盖 内置指示器按名称渲染。 —
主题覆盖 每个解析该名称的宿主都会绘制覆盖组件。 覆盖设计。
单选已选中 强调色圆形容器带圆点;data-checked。 尺寸。
Falsy 子元素 内置标记仍会渲染。 —

转换与优先级顺序

  • ORD1 — 解析。 最近主题的 indicators[name],然后是内置指示器,对于未提供的增强名称则什么也不渲染。
  • ORD2 — 属性。 先是调用方 props,然后是指示器自身的 aria-hidden。

性能与资源

  • PR1 — 纯渲染。 指示器不拥有任何状态、副作用、监听器或观察器。

无障碍契约

  • AR1 — 装饰性。 指示器对辅助技术隐藏;宿主拥有全部语义(FR3)。
  • AR2 — 强制颜色。 在强制颜色模式下,单选圆点保持可见。

设计关系

结构或状态 设计需求 表示权威 层级角色 组件契约
单选圆形容器 未选中时强调边框;选中时强调色填充。 当前来源 支持性 FR5, FR6
单选圆点 选中时在强调色上显示圆点。 当前来源 支持性 FR5, FR6

没有任何设计记录约束 Indicator。复选框和勾选视觉由它们各自的记录所有。

族与系统关系

  • architecture:theme-authoring-contract 负责定义主题如何提供 indicators。
  • component:CheckboxIndicator 和 component:CheckIndicator 负责另外两个内置指示器。
  • CheckboxInput、RadioListItem、Selector 和菜单选择行承载指示器。

验证映射

契约 验证 代表性状态 突变或失败预期 审计章节
FR1、FR2 indicatorRegistry.test.tsx;Indicator.test.tsx useIndicator 测试套件 无主题;主题覆盖;增强名称 默认值错误、覆盖被忽略或解析出未提供的名称,均判定为失败。 audit:Indicator/behavior
FR3 Indicator.test.tsx decorative-contract 测试套件 每个内置组件处于选中状态;调用方设置 aria-hidden={false};role 和 tabIndex 作为字面量 prop 调用方可暴露的指示器、丢失的普通 prop,或接受的字面量 role 或 tabIndex,均判定为失败。证据缺口:没有测试检查未选中状态下的 aria-hidden。 audit:Indicator/accessibility
FR4 Indicator.test.tsx falsy-children 测试套件 null、false、''、0、真实子元素 抑制任何内置组件标记的假值子元素(false、null、undefined 或 '')判定为失败,且 CheckIndicator 将 0 视为空值也判定为失败。证据缺口:没有测试将 0 渲染为 CheckboxIndicator 或 RadioIndicator 的子元素。 audit:Indicator/behavior
FR5、FR6、AR2 Indicator.test.tsx radio-dot、disabled 和 target-name 用例;RadioIndicator.circle.source-build.test.mjs 选中和未选中;禁用;规范目标 未选中时出现圆点、选中时无圆点、缺少已选中的 data-checked 或已禁用的 data-disabled,或别名目标,均判定为失败。证据缺口:没有测试断言单选按钮的尺寸、状态颜色(强调边框、强调填充、强调色上的圆点)、减少动态效果下的即时过渡、禁用状态的透明度和边框、悬停色调、强制颜色模式下的圆点(RadioList 的强制颜色用例在任一匹配规则下均通过)、根元素和圆点上的 radio data-size、ref,或调用方在根元素上的 className、style 和 xstyle。 audit:Indicator/theming
ORD1、ORD2、PR1 由 FR2 和 FR3 行覆盖。证据缺口:没有测试断言不存在状态、效果或监听器。 — — audit:Indicator/behavior

当前状态影响

  • 直接指示器导入(FR2)。 Tokenizer 底部面板直接渲染 CheckboxIndicator 和 RadioIndicator,因此主题的 checkbox 或 radio 覆盖无法作用于它。

决策日志

无组件级决策。

开放问题

无。

内容边界

本文件不重复消费者 prop 表格/示例、当前审计结果、实现步骤或组件族/系统规则。它链接到这些内容的所属文档。

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