Spinner 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个带有 size(sm–xl)、shade、可选可见 label,以及五个用于几何与颜色的公共主题变量的动画环。 |
| 行为 | 该环位于一个具名指示器内;可见标签渲染在其下方,非空字符串标签通过 aria-labelledby 为指示器命名,而不是重复该标签。独立 Spinner 通过共享通道(AR1)进行播报。 |
| 最终用户影响 | 有视力的用户看到正在进行的工作;屏幕阅读器用户会找到一个具名指示器,默认使用翻译后的“加载中”;减少动态效果的用户会看到变慢的环,而不是静止的环。 |
| 构建者影响 | 每个 Spinner 的指示器从 status 变为 progressbar,包括组合组件内部的隐藏环,因此按角色查询指示器的消费方测试会发生变化;没有 prop、默认值或样式变化。 |
| 兼容性/就绪状态 | 一个可访问性修复:角色变为 progressbar,独立 Spinner 通过通道播报;没有公共 prop 或默认值变化,应用代码无需更改(spec:AST-017 FR53):调用方传入非 progressbar 的 role 会让 Spinner 保持静默,与发布时行为一致。其余差距列在“当前状态影响”下。 |
| 评审检查 | 拒绝:没有可访问名称的指示器、重复的字符串标签名称、挂载时已包含自身文本的活动角色、可被 flex 宿主压缩的框、覆盖框尺寸的调用方 style,或在减少动态效果下停止的环。 |
| 约束规则 | spec:AST-086/FR2,FR8,FR11;spec:AST-020/FR15;spec:AST-017/FR53;architecture:component-theming-surface/INV6;architecture:internationalization/INV1a;architecture:public-component-api/INV5,INV6,INV8。 |
此表是评审投影;下文正文具有权威性。
意图¶
Spinner 表示持续时间未知的工作正在进行中。它拥有环的几何形状、运动、色调、其下方的可选可见标签,以及指示器的可访问名称。
兼容性与迁移¶
- 已发布默认值保留:每个 prop 均为
yes;指示器的角色和播报作为可访问性修复(AR1)发生变化 - 兼容性类别:可访问性修复,无公共 prop、默认值或样式输出变化;应用代码无需更改(
spec:AST-017FR53) - FR53 下的已发布兼容性:调用方传入非
progressbar的role会让 Spinner 保持静默,与发布时行为一致,因此以这种方式静默组合环的应用代码将继续工作。这不是推荐模式;新代码应使用aria-hidden隐藏组合 Spinner - 受控/非受控行为:不适用;Spinner 不持有状态
- 迁移决策:无
消费方迁移说明属于消费方文档和发布说明。
当前状态影响¶
- 空名称或丢失名称(AR1)。
aria-label=""被用作名称,label=""会渲染一个空的可见文本并据此为指示器命名;这两种情况都会让指示器具有空的可访问名称(WCAG 2.2 4.1.2)。当存在label时,调用方的aria-labelledby会指向无角色的包装器,而不是指示器。
所有权边界¶
拥有
- 指示器、其内部绘制的环,以及其下方的可选标签。
- 按
size决定的环几何形状、按shade决定的环与轨道颜色、弧的转动,以及减少动态效果时的速率。 - 五个公共主题变量及其声明位置。
- 指示器的可访问名称,包括翻译后的默认名称。
不拥有 / 非目标
- 组合组件的忙碌指示器是否静默 —— 由该组件在
spec:AST-086FR8 下拥有。核心组合器和应用代码使用aria-hidden隐藏它;Typeahead、BaseTypeahead 和 Tokenizer 会保持其搜索指示器具名,并通过内部、非导出的路径使其静默。 - 内容形态的加载占位 —— 由
component:Skeleton拥有。 - 确定性进度 —— 由
component:ProgressBar拥有。 - 当
label为节点时的富标签内容 —— 由调用方拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 拥有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| --------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------ | ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| 尺寸 | sm, md, lg, xl |
环形直径为 10、14、18 或 28px,描边宽度为 2、3、3 或 4px。 | 所有 Spinner | md |
component:Spinner |
稳定 | TypeScript 会拒绝其他值。 |
| 色调 | default, subtle, onMedia, inherit |
适用于浅色、行内、深色媒体或继承上下文的弧线与轨道颜色。 | 所有 Spinner | default |
component:Spinner |
稳定 | TypeScript 会拒绝其他值。 |
| 标签 | 无;字符串;富节点 | 显示在圆环下方的可见内容。 | 所有 Spinner | 无 | component:Spinner |
稳定 | null 和 undefined 表示无。 |
| 主题变量 | --spinner-diameter, --spinner-stroke-width, --spinner-arc-fraction, --spinner-color, --spinner-track-color |
主题按 size、按 shade 或在基础目标上设置的公共几何与颜色扩展点。 |
声明在带有 spinner 目标的任意元素上。 |
按尺寸和色调 | component:Spinner |
稳定 | 当主题化的描边宽度为 0 时不绘制描边;弧线比例仅在样式表加载后生效。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | 没有标签时,Spinner 渲染一个 inline-grid span 指示器,它带有 spinner 目标、ref、data-testid 和透传 props。有标签时,一个带 --spacing-2 间距的纵向 div 包装器承载目标、ref、data-testid、透传 props 和样式输入;指示器 span 和标签依次渲染在其中。 |
当前源码和测试 |
| FR2 | 指示器的盒子大小为圆环直径加上每侧一个描边宽度,在调用方的 style 之后以内联样式设置;因此调用方的 width 或 height 永远不会调整其大小,而调用方的其他样式仍然生效。该盒子在 flex 宿主中不会收缩。在没有样式表时,盒子和圆环按该尺寸的默认几何绘制。 |
当前源码和测试 |
| FR3 | 圆环由一个 aria-hidden 轨道圆和一个 aria-hidden 弧线组成,弧线覆盖圆周的 --spinner-arc-fraction(默认 0.375),从十二点方向开始,带有圆头线帽。弧线以每周期 --duration-slow-min 的速度围绕静止轨道旋转;该值由主题在 tempo 缩放之前设置(spec:AST-108 FR4),线性且无限循环;在 prefers-reduced-motion: reduce 下,周期减慢至 3 秒且不会停止。 |
当前源码和测试 |
| FR4 | 所有已挂载的圆环都在同一相位中旋转,无论各自何时挂载。当浏览器无法报告正在运行的动画时,Spinner 不执行任何相位同步工作。 | 当前源码和测试 |
| FR5 | default 在 --color-track 上绘制 --color-accent;subtle 在 --color-track 上绘制 --color-text-secondary;onMedia 在自身上以轨道不透明度 77/255 绘制 --color-on-dark;inherit 在自身上以轨道不透明度 0.3 绘制 currentColor。 |
当前源代码和测试 |
| FR6 | 这五个公共变量仅声明在承载 spinner 目标的元素上,按 size 和 shade 区分,因此对该目标及其 size: 或 shade: 变体的主题规则会覆盖它们;当标签将目标移到包装器上时,内部指示器会继承它们。 |
当前源代码和测试 |
| FR7 | 字符串标签渲染为粗体正文 Text;富节点标签按提供的内容渲染。 | 当前源代码和测试 |
| FR8 | xstyle 和 className 作用于承载目标的元素,并在组件样式之后合并;style 在它们之后合并,但指示器盒子的 width 和 height 除外(FR2)。 |
当前源代码和测试 |
允许的变体¶
- AV1 — 主题几何与颜色。 主题可以按尺寸、按色调或全局地更改这五个公共变量;盒子会跟随主题化的直径和描边。
- AV2 — 标签内容。 标签文本和富内容可以变化。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 无标签 | Progressbar span 承载目标并带有翻译后的“Loading”名称。 |
尺寸、色调。 |
| 字符串标签 | 包装器承载目标;指示器通过 aria-labelledby 引用可见 Text 来命名。 |
标签文本。 |
| 富标签 | 指示器通过 aria-label 命名(调用者的,否则为“Loading”);节点按提供的内容渲染。 |
节点内容。 |
显式 aria-label |
指示器由该值命名,无论有无标签。 | — |
| 减少动态效果 | 弧线以 3 秒周期持续运动。 | — |
| 窄 flex 容器 | 指示器盒子保持完整尺寸并溢出,而不是压缩。 | — |
转换与优先级顺序¶
- ORD1 — 无障碍名称。 在没有
label的情况下,调用者的aria-labelledby会到达指示器并从被引用的元素为其命名。然后:非空的调用者aria-label→ 非空字符串label(当未设置aria-label时,通过aria-labelledby)→ 翻译后的@astryx.spinner.loading(“Loading”)。空的aria-label或label,以及label旁边的调用者aria-labelledby,均属于 AR1 缺口。 - ORD2 — 变量值。 针对
size:或shade:变体的主题规则 → 基于基础目标的主题规则 → 组件按尺寸和按色调的默认值。 - ORD3 — 盒子尺寸。 由解析后的直径和描边组合成的盒子尺寸 → 当没有样式表声明时,使用该尺寸的默认框架;两者都不会让位于调用者的
style。
性能与资源¶
- PR1 — 挂载成本。 挂载 Spinner 不会引起全文档样式重算,重复的模块求值不会失败,服务器渲染不会执行仅浏览器端的工作。
- PR2 — 有界的阶段工作。 多个环一起挂载时只消耗一轮阶段工作,未挂载的环永远不会被触碰。
无障碍契约¶
-
AR1 — 可播报、已命名的指示器。 页面加载后出现的独立 Spinner 会通过共享通道进行播报,其元素不携带 live role 或
aria-live(spec:AST-086FR2、FR11);处于忙碌属主内部的 Spinner 保持静默(spec:AST-086FR8)。指示器按 ORD1 拥有可访问名称,可见的字符串标签绝不会重复作为aria-label。该指示器是一个不确定进度指示器:role="progressbar"且没有aria-valuenow,并按照 ORD1 的顺序命名(可见字符串标签通过aria-labelledby,绝不重复作为aria-label)(spec:AST-020FR15;OQ1,已决定)。组合式 Spinner 通过aria-hidden隐藏来静默,正如 CheckboxInput、Switch、Button 以及大多数 Core 组合器和应用代码所做的那样;Typeahead、BaseTypeahead 和 Tokenizer 会保持其搜索指示器具有名称,并通过一条内部、非导出的路径使其静默。调用者传入除progressbar以外的role也会使其保持静默,这是spec:AST-017FR53 下随附的兼容性行为(请参阅“兼容性与迁移”)。没有任何公共 prop 会使其静默。实现缺口:aria-label=""或label=""会使其带有空名称;并且在有label的情况下,调用者的aria-labelledby会落在无 role 的包装器上,从而不命名任何内容。 -
AR2 — 装饰环。 该环为
aria-hidden。 - AR3 — 翻译默认。 默认名称来自翻译目录并遵循当前活动区域设置。
- AR4 — 减少动态。 在
prefers-reduced-motion: reduce下,动画会减慢并保持移动,因此该环仍显示为工作状态。
设计关系¶
| 解剖或状态 | 设计需求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 环 | 轨道上的移动弧线表示不确定的工作。 | 当前来源 | 突出 | FR2–FR6, AR2, AR4 |
| 标签 | 可选的粗体文本或调用方内容,用于描述工作。 | 当前来源和文档 | 辅助 | FR1, FR7, AR1 |
主题:承载 spinner 目标的元素反映 size 和 shade,并声明五个公共变量;环圈读取这些变量。使用方的解剖结构未命名任何部件,因此不会声明解剖主题块。
家族与系统关系¶
spec:AST-086负责状态公告的交付;AR1 记录 Spinner 如何满足 FR2 和 FR11,并且组合中的忙碌拥有者在 FR8 下保持静默。architecture:component-theming-surface负责目标和变量限定;FR6 记录 Spinner 在何处声明其变量。architecture:internationalization负责默认名称使用的目录。architecture:public-component-api负责 ref、透传和样式输入规则;FR2 和 FR8 记录对style优先级的盒尺寸例外。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, FR7, FR8 | Spinner.test.tsx 渲染、标签和 data-testid 测试 |
无标签、字符串标签、富标签 | 丢失标签或测试 id 会失败。差距:在两种形式中,都没有测试断言哪个元素承载 ref、xstyle 和 className,或者带标签形式下目标落于何处。 |
audit:Spinner/behavior |
| FR2 | Spinner.test.tsx 盒模型大小套件;Spinner.stories.tsx NarrowFlexHost |
每种尺寸;调用方 style 宽度;窄 flex 宿主 |
调用方宽度占据上风,或后备框架丢失,均告失败。差距:如果盒在 flex 宿主中缩小,没有自动化检查会失败;这在 story 中可见。 | audit:Spinner/layout |
| FR3, FR4, PR2 | Spinner.test.tsx 环套件,包括 135 度扫掠测试;SpinnerMotion.a11y.chromium.spec.ts |
轨道和转子结构、默认短划线和弧分数、帧调度;一个 700 毫秒的主线程阻塞、一个周期、多个环 | 丢失圆、更改的默认短划线和弧分数、额外帧或未批处理的固定均会失败;同样,脚本运行时停止、逐帧绘制、以其他速率或方向旋转或相位漂移的环也会失败。差距:起始角度测试仅检查没有 SVG transform 属性,因此移除 CSS 起始旋转仍会通过;主题化的弧分数以及从未决相位工作中丢弃未挂载的环没有自动化检查。 |
audit:Spinner/motion |
| FR5, FR6 | Spinner.test.tsx 主题变量套件 |
尺寸、色调和基础范围的覆盖 | 主题变量在错误的选择器上发出则会失败。差距:如果组件在带标签的 Spinner 的内部 span 上声明其默认值,没有测试会失败;并且色调测试仅断言存在性和反映,因此默认颜色和轨道不透明度没有自动化检查。 | audit:Spinner/theming |
| PR1 | Spinner.test.tsx 注册测试套件 |
导入、重复求值 | 在挂载时执行工作或在第二次求值时抛出异常,则失败。差距:该套件仅在 DOM 环境下运行,因此服务端安全性没有自动化检查。 | audit:Spinner/behavior |
| AR1, AR3 | Spinner.test.tsx 命名与本地化测试 |
默认标签、显式标签、字符串标签和富文本标签 | 缺少名称、字符串标签被重复用作 aria-label,或默认标签未翻译,都会导致失败。播报测试套件覆盖每次出现时的单次投递、页面加载时静默、Core 所有者内部静默以及调用方通过 aria-labelledby 提供的名称。差距:没有测试覆盖空的 aria-label 或 label。 |
audit:Spinner/a11y |
| AR4 | SpinnerMotion.a11y.chromium.spec.ts 减少动态效果测试 |
减少动态效果 | 如果圆环停止转动,或旋转速度不是每圈 3 秒,则失败。 | audit:Spinner/motion |
| AR2 | 源码审查 | 每个状态 | 差距:如果轨道或转子失去 aria-hidden,没有任何自动化检查会失败。 |
audit:Spinner/a11y |
| AR1, AR2 | StatusMessage.a11y.chromium.spec.ts Spinner 状态 |
默认标签和可见字符串标签(已挂载) | 角色或名称发生变化会使可访问性树断言失败。差距:富文本标签、空名称和隐藏圆环没有可访问性树检查;通道投递由 Spinner.test.tsx 的播报测试套件检查。 |
audit:Spinner/a11y |
决策日志¶
- OQ1 —— 独立 Spinner 在没有 live 区域角色时的角色与名称。
由
spec:AST-020FR15 决定:一个不确定进度指示器,使用role="progressbar"且不设置aria-valuenow,并按 ORD1 的规定命名。当它被组合进其他组件时,指示器保持静默(spec:AST-086FR8):大多数 Core 组合组件和应用代码通过aria-hidden将其隐藏;三个搜索组合组件通过内部路径使其静默;调用方role不是progressbar时,为保持发布版本的兼容性而保持静默(spec:AST-017FR53);Spinner 不接受任何播报 prop。
未决问题¶
无未决问题。OQ1 已决定(见决策日志)。
内容边界¶
本文件不重复使用方 prop 表格/示例、当前审计结果、实施步骤或家族/系统规则。它会链接到这些内容的所有者文档。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx