ProgressBar 组件契约¶
契约概览¶
| 区域 | 契约 |
|---|---|
| 公共契约 | label、value、max、isLabelHidden、hasValueLabel、formatValueLabel、variant、isIndeterminate、marks、isDisabled、根 BaseProps 和一个根 ref。 |
| 行为 | 一个带标签的 progressbar,其填充在弱化轨道上显示被钳制后的值,并在所有指针下按主题的时长和缓动移动;不确定态时滑动,在减弱动态下原地脉冲;可选提供数值文本和带标签的目标标记。 |
| 最终用户影响 | 人们可以看到操作进行到多远,辅助技术会读出名称和值;标记在悬停或聚焦时显示其标签。 |
| 构建方影响 | 构建方的 data-variant 目前会替换映射出的变体,因此针对进度条真实变体的主题规则不再匹配(FR8 缺口);除此之外无其他影响。 |
| 兼容性/就绪度 | 无 API 或默认值变更。实现缺口列于“当前状态影响”下。 |
| 评审检查 | 拒绝以下情况:正确性依赖附近文本的确定态进度条、超出 [0, max] 的值、泄漏的 NaN、不确定态下的数值语义,或目标脱离其所属部分。 |
| 治理规则 | component:ProgressBar/DEC-1、DEC-2;spec:AST-002;spec:AST-094 FR4、FR13;design:reduced-motion DR1;architecture:component-theming-surface;architecture:theme-tokens INV11;architecture:internationalization INV1a;architecture:public-component-api INV5–INV8。 |
此表为评审投影;以下方正文为准。
意图¶
ProgressBar 用于传达操作的进度。确定态进度条本身就是一个充分的独立视觉元素:人们无需依赖渲染在别处的可见文本,就能区分已完成与剩余进度。外部文本可以补充进度条,但不是进度条正确性的前提。
消费端语法和示例应放在 ProgressBar.doc.mjs 中。
兼容性与迁移¶
- 发布时的默认值保留:
yes— 确定态、value0、max100、accent、可见标签、无数值文本、无标记。 - 兼容性类别:记录已发布行为,以及两项不涉及 API、默认值或值变更的动画变化:减弱动态下的不确定填充(FR6),以及所有指针下按主题缓动时长移动的确定填充(FR4);四个规范的
progress-bar*目标是仅有的目标类。 - 受控/非受控行为:不适用;
value由调用方持有。 - 迁移决策:无
消费端迁移说明归属于消费端文档与发布说明。
当前状态影响¶
- 数值文本在目录之外拼装(FR3)。 默认数值文本和
aria-valuetext是在代码中构建的${percent}%,因此以不同方式书写百分比的区域设置会读到和看到英文形式;而architecture:internationalizationINV1a 要求 Astryx 自有文本来自单一目录消息。 - 调用方的
data-variant会替换映射出的变体(FR8)。 调用方 props 在根元素的主题属性之后展开,因此调用方的data-variant会替换映射值,真实变体的主题规则不再匹配;此处architecture:public-component-apiINV5 要求组件自有行为不被覆盖。 - 主题新增的变体没有基线填充(FR4)。 变体映射表已导出以供主题扩展,但新增变体不匹配任何内置填充或填充上的标记颜色,因此在主题为其设置样式之前,填充不会绘制任何内容;此处
architecture:component-theming-surfaceINV14 要求提供安全的基线。 - 触摸填充仍使用测得的时长(FR4)。 在粗粒度主指针下,值变化仍以
progress.fillTrackMs乘以轨道移动比例所得的时间线性移动填充;而spec:AST-094FR45 要求它在所有指针下按--duration-medium和主题缓动移动。 - 不确定态的滑动跟随任意从右到左的祖先(FR6)。 不确定态的滑动和标记居中会在任意从右到左的祖先下镜像,而不是依据进度条自身方向;因此在从右到左页面中的从左到右区域里,它们会与标签方向相逆;此处
architecture:internationalizationINV11 要求从渲染区域解析镜像。 - 浅色默认主题下警告和中性填充低于 3:1(FR6、OQ1)。 与轨道相比,即使完全不透明(在 body 和 surface 背景上),警告填充也只有 1.65–1.82:1,中性填充为 1.84–2.03:1;因此 FR6 的 3:1 变暗阶段下限在浅色模式下无法满足这两种色调;其余所有色调以及深色模式下的所有色调均满足该要求。
所有权边界¶
拥有
- 对于组件提供的每种确定态(determinate)呈现,在已完成进度与剩余进度之间提供充分的独立视觉区分。
- 容器、标签行、轨道(
progressbar元素)、填充和标记,以及它们的progress-bar、progress-bar-track、progress-bar-fill和progress-bar-mark目标。 - 值钳制、值文本、不确定态动画和标记放置。
不拥有 / 非目标
- 外部可见的标签、值或描述——由产品调用方拥有,是对进度条的补充。
- 内置标签或值文本的单独公共目标;不存在这样的目标。
- 确切的独立对比度处理——属于人工设计决策(OQ1)。
- 主题令牌定义——由
architecture:theme-tokens拥有。 - 标记工具提示的行为——由
component:Tooltip拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 进度模式 | determinate(确定态);indeterminate(不确定态) | 已完成进度是否已知。 | 所有变体 | determinate(确定态) | component:ProgressBar |
稳定 | — |
| 值与范围 | 0–max 范围内的有限 value |
已完成的数量。 | 确定态 | 0 of 100 | 调用方 | 稳定 | 钳制到 [0, max];非有限值或 max 视为 0。 |
| 标签 | 字符串,可见或视觉隐藏 | 进度条的可访问名称。 | 始终 | 可见 | 调用方 | 稳定 | — |
| 值文本 | 隐藏;显示;自定义格式化器 | 标签旁可选的可见值,同时也是 aria-valuetext。 |
确定态 | 隐藏;四舍五入的百分比 | component:ProgressBar |
稳定 | 不确定态时忽略。 |
| 变体 | accent、success、warning、error、neutral;通过导出的变体映射由主题添加的值 |
填充颜色。 | 始终 | accent |
component:ProgressBar |
稳定 | 新增的值在主题为其设置样式之前不会绘制填充(FR4 缺口)。 |
| 禁用 | true、false |
弱化的填充、标签和标记。 | 始终 | false |
component:ProgressBar |
稳定 | — |
| 标记 | {value, label} 列表 |
轨道上带标签的刻度。 | 确定态 | 无 | 调用方 | 稳定 | 非有限值会被丢弃;其余值钳制到轨道上。 |
| 视觉处理 | 一种充分的独立处理;确切形式待定 | 图形如何区分已完成与剩余进度。 | 确定态 | — | component:ProgressBar |
由 DEC-1 决定;形式待定(OQ1) | 没有不完整的公共模式。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
| ID | 不变量 | 依据 |
| FR1 | ProgressBar 提供的每个确定态呈现都是一种充分的独立可视化形式,足以区分已完成进度与剩余进度;外部可见文本可以对其补充,但绝非必需,且补充文本或图形永远不会替代这一区分。ProgressBar 不会使视觉正确性依赖于调用方声明的、其无法验证或关联的外部内容。 | component:ProgressBar/DEC-1; spec:AST-002 |
| FR2 | 只有在该组件已具备正确的基础行为,并且由调用方持有的稳定视觉区分仍然存在之后,才会考虑新增用于调整视觉区分的新公开 API。 | component:ProgressBar/DEC-1; spec:AST-002 |
| FR3 | 根元素包含一个标签行和一条轨道。标签通过 aria-labelledby 为轨道(role="progressbar")命名;isLabelHidden 仅将其在视觉上隐藏。当组件处于确定状态时,轨道暴露 aria-valuenow(钳制后的值)、aria-valuemin 0、aria-valuemax(max)以及来自 formatValueLabel 的 aria-valuetext,后者默认为四舍五入后的百分比;hasValueLabel 会在标签旁边显示相同文本。max 为零或非有限值时,进度为 0%,且绝不渲染 NaN。Astryx 所有的值文本来自一条目录消息(architecture:internationalization INV1a)。实现差距:默认文本是在代码中拼装的(当前状态影响)。 | 当前源码与测试 |
| FR4 | 轨道高 8px,完全圆角,使用 --color-background-muted,并裁剪填充。确定状态的填充条横跨轨道并沿其滑动,使其前缘位于钳制后的百分比处,并随条自身的书写方向镜像,当值变化时,在每种指针(包括手指)下,以主题缓动从绘制位置开始移动,持续 --duration-medium(spec:AST-094 FR45)。在粗粒度主指针(spec:AST-094 FR13)下,大于零时至少绘制 16px 长,该长度覆盖的标记算作在填充条上(FR7),为零时不绘制任何内容。progress.fillTrackMs(1000ms,UIKit 的进度视图用于整条轨道变化)及其线性曲线 progress.curves.fill 保留在生成的动效角色表中,作为 UIKit 的实测参考,且不会有动效播放它们(spec:AST-094 FR4, DEC-5)。实现差距:在粗粒度主指针下,填充条仍以 progress.fillTrackMs 乘以值移动的轨道占比的时间线性移动。在减少动效下,新值会立即到位,适用于每种指针(design:reduced-motion DR1)。填充条绘制为 --color-accent、--color-success、--color-warning、--color-error,对于 neutral 和禁用条则为 --color-text-disabled;主题新增的变体具有安全的、与主题无关的填充(architecture:component-theming-surface INV14)。实现差距:主题新增的变体在主题为其设置样式前,不绘制填充条,也不绘制填充条上的标记颜色(当前状态影响)。在强制颜色模式下,填充条按值调整大小而非滑动,并保留 1px 的 CanvasText 轮廓,以便其形状保持可见(architecture:theme-tokens INV11)。 | 当前源代码与测试;UIKit 测量(iOS 26.2 模拟器);component:ProgressBar/DEC-2 |
| FR5 | isDisabled 会使填充、标签、值文本和标记弱化,且不添加任何 ARIA 状态。 | 当前源代码与测试 |
| FR6 | isIndeterminate 会移除所有 value 属性和值文本。在无减少动态(reduced motion)的情况下,每次指针操作时,一个 40% 的填充条会在被裁剪的轨道上滑动,带缓动,单次通过耗时 1.5s,并跟随条自身的渲染方向镜像(architecture:internationalization INV11)。在减少动态的情况下,每次指针操作时,填充条会作为一整条实心条横跨整个轨道,没有分段也没有移动,仅其不透明度脉冲变化:从 1 降到 0.84 再返回,每个方向都采用 progress.reducedMotionPulseMs 角色(2000ms),并使用 timing.curves.move 曲线;轨道保持不变。该脉冲是一个忙循环,因此速率不会缩放它(spec:AST-094 FR4、spec:AST-108 FR4)。它应用了 design:reduced-motion DR1 的不移动规则,用不透明度变化替代移动,应用于一条记录留给其组件的循环。在 0.84 下限处,填充条相对于轨道在两种主题下,对所有在完全不透明度下能达到 3:1 的色调,至少保持 3:1 的对比度(AR4)。实现差距:滑动和标记的居中会在任何从右到左(RTL)祖先元素下镜像,而不是条自身的渲染方向;因此在从右到左页面的从左到右区域中,它们会与标签方向相逆地运行(当前状态影响)。 | 当前源代码和测试;component:ProgressBar/DEC-2 |
| FR7 | 每个有限标记会在 progressbar 元素外部渲染,以便其标签保持可见;在标记被钳制的位置上渲染一个刻度线,其工具提示在悬停和聚焦时显示标签;填充部分内的标记采用填充条的对比色,并且在 indeterminate 状态下不渲染标记。可聚焦的标记将其标签暴露为可访问名称(WCAG 2.2 SC 4.1.2)。每个标记都是一幅以其标签命名的图像。 | 当前源代码和测试 |
| FR8 | 根元素携带 progress-bar 以反映 variant,轨道为 progress-bar-track,填充为 progress-bar-fill 以反映解析后的填充 variant,每个标记为 progress-bar-mark 以反映解析后的填充 variant 和放置位置;标签和值文本不携带目标。反射状态保持为组件自有(architecture:public-component-api INV5)。实现差距:调用方的 data-variant 会替换根元素的反射 variant(当前状态影响)。 | 当前源代码与测试 |
| FR9 | ref 和 data-testid 到达根元素;受支持的 DOM、data、ARIA 和事件属性到达根元素,而反射的主题属性保持组件自有(FR8);xstyle、className 和 style 在组件样式之后组合。 | 当前源代码与测试;architecture:public-component-api INV5–INV8 |
允许的变体¶
- AV1 — 精确的视觉处理。 形状、设计令牌选择以及其他渲染细节可以有所不同,只要每个结果呈现均满足 FR1。
- AV2 — 主题。 主题可以通过目标表达其视觉语言,同时保持独立的区分。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 确定,部分 | 完成和剩余进度可仅凭图形区分;存在 value 属性。 | 变体。 |
| 带数值文本 | 图形仍满足 FR1;文本对其进行补充。 | 格式化器。 |
| 标签隐藏 | 条形保留其可访问名称。 | — |
| 确定,触摸 | 在粗粒度主指针下,填充按主题的时长和缓动从其绘制位置移动;至少高于零 16px;零处无内容。 | 变体。 |
| 不确定 | 无 value 属性;滑动填充;在减少动态效果下,全宽填充在原地脉动其不透明度,无移动。 | 变体。 |
| 带刻度 | 刻度位于 progressbar 外部,每个刻度是一个以其标签命名的图像;其工具提示显示该标签。 |
刻度标签。 |
转换与优先级顺序¶
- ORD1 — 值。 非有限 → 0;钳制到
[0, max];非正max得出 0%。 - ORD2 — 呈现。 先解析确定或不确定状态;外部内容绝不削弱确定状态的视觉要求。
性能与资源¶
- PR1 — 不检查外部内容。 ProgressBar 不添加 DOM 观察、测量或关系发现,以判断附近文本是否使较弱的条形可接受。刻度工具提示延迟加载。
无障碍契约¶
- AR1 — 独立的非文本区分。 确定状态的条形满足适用的非文本对比度要求,而不依赖外部可见文本。
- AR2 — 编程式语义。 轨道是一个命名为
progressbar的对象,在确定状态下具有值语义,在不确定状态下没有值语义,且与可见处理方式无关。 - AR3 — 不推断补充文本。 ProgressBar 不声称外部文本存在、可见、等价或相关联。
- AR4 — 减少动态效果下的脉动使条形保持可见。 不确定状态的脉动绝不会把填充绘制到低于 0.84 不透明度;这是每个在完全不透明度下对轨道达到 3:1 的色调,在浅色和深色默认主题中仍能达到的最低不透明度(最低:深色中的成功色,在表面背景上为 3.01:1)。浅色中的警告色和中性色即使在完全不透明度下也达不到(当前状态影响;OQ1)。
设计关系¶
| 解剖结构或状态 | 设计需求 | 表征权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 进度条 | 安排标签行和轨道。 | 当前源代码与文档 | 支持 | FR3, FR8 |
| 标签与数值文本 | 为操作命名,并可选地补充其数值。 | 当前源代码与文档 | 支持 | FR3 |
| 填充与剩余轨道 | 提供足够的独立区分度。 | DEC-1;处理方式待定(OQ1) | 突出 | FR1, FR4 |
| 标记 | 轨道上可选带标签的目标点。 | 当前源代码与文档 | 支持 | FR7 |
主题化解剖¶
{
"Progress bar": {"target": "progress-bar"},
"Label": {
"none": {
"reason": "unsettled: No current public ProgressBar target reaches this part; future target ownership is undecided."
}
},
"Value text": {
"none": {
"reason": "unsettled: No current public ProgressBar target reaches this part; future target ownership is undecided."
}
},
"Track": {"target": "progress-bar-track"},
"Fill": {"target": "progress-bar-fill"},
"Mark": {"target": "progress-bar-mark"}
}
Label 和 Value text 的处置是当前事实,并非决定这些部分保持无目标状态。
家族与系统关系¶
architecture:public-component-api与spec:AST-002/DEC-1规定调用方所有的区分度是否足以支撑公共 prop;FR2 应用它们。architecture:component-theming-surface与architecture:theme-authoring-contract规定目标与主题覆盖。architecture:theme-tokens规定 token 词汇表与 forced-colors 边界;FR4 应用 INV11。architecture:internationalization管理 Astryx 拥有的文本;FR3 记录了 value-text 缺口。component:Tooltip拥有标记的 tooltip。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, AR1, AR3 | 稳定的视觉基线 core-progressbar--default(中性)与 core-progressbar--with-target-mark(探针) |
默认;带标记的探针主题 | 填充或轨道若有变更,会以变更后的状态返回供审查。缺口:尚未在已发布主题与颜色模式之间进行真实浏览器对比检查以证明独立区分度(OQ1 保留该处理方式)。 | audit:ProgressBar/visual |
| FR2 | 公共类型与消费者文档审查 | 当前 props | 缺口:没有自动化检查;新的视觉区分 prop 会被视为审查发现。 | audit:ProgressBar/api |
| FR3, ORD1, AR2 | ProgressBar.test.tsx 的标签、数值文本、格式化器、钳制、零与 NaN 测试;ProgressBar.a11y.test.tsx 与 ProgressBar.a11y.chromium.spec.ts 状态 |
确定态;已格式化;已完成;标签隐藏 | 缺少名称、数值超出 [0, max]、泄漏 NaN 或错误的 aria-valuetext 都会导致失败,包括在无障碍树中。缺口:没有测试检查非英语区域设置下的默认文本。 |
audit:ProgressBar/a11y |
| FR4 | ProgressBar.test.tsx 轨道裁剪、transform、变体和 forced-colors 测试;ProgressBarMotion.a11y.chromium.spec.ts |
每种变体;值变化;RTL 区域;减少动态效果;forced-colors 模式 | 轨道未裁剪、在 forced-colors 模式之外按宽度调整填充大小、丢失 forced-colors 轮廓、在 RTL 区域中前缘偏离值或未镜像、减少动态效果下值变更未立即到位,或移动时逐帧触发布局,均视为失败。缺口:变体颜色没有直接检查。缺口:“固定 8px 轨道高度”测试仅检查条形能够渲染,因此轨道高度没有检查;没有测试覆盖主题新增的变体。 | audit:ProgressBar/visual |
| FR5 | ProgressBar.test.tsx 禁用和禁用标记测试 |
禁用 | 缺少标签或未变暗的标记均失败。缺口:变暗的填充和标签颜色没有直接检查。 | audit:ProgressBar/visual |
| FR6 | ProgressBar.test.tsx 不确定状态套件 |
每种变体;RTL | 不确定状态下出现值属性或值文本、丢失标签、轨道未裁剪、或滑动未镜像,均失败。没有测试覆盖右到左页面内左到右区域中的滑动。缺口:RTL 测试断言了右到左祖先选择器,因此它固化了 FR6 缺口。 | audit:ProgressBar/behavior |
| FR4 触摸时序 | ProgressBarTouch.a11y.chromium.spec.ts;ProgressBar.test.tsx 触摸套件 |
粗指针与细指针;10% 到 90%;移动中途的新值;窄轨道上的 1%;零;减少动态效果 | 任何指针下移动超出主题的缓动时长、或从旧值而不是已绘制位置开始;粗指针下非零填充短于 16px;或零值时绘制了填充,均失败。 | audit:ProgressBar/behavior |
| FR6 减少动态效果 | ProgressBarMotion.a11y.chromium.spec.ts 的减少动态效果脉冲用例;ProgressBar.test.tsx 脉冲套件 |
每种变体;粗指针和细指针 | 存在分段、任何 transform 或位移、填充比轨道窄、动画属性不是填充的不透明度、不透明度低于 0.84、每个方向的周期不是 progress.reducedMotionPulseMs、或轨道发生变化,均失败。 |
audit:ProgressBar/behavior |
| AR4 | ProgressBarMotion.a11y.chromium.spec.ts 的脉冲下限对比度用例 |
每种变体;浅色和深色默认主题;body 和 surface 背景 | 在完全不透明度下达到 3:1、但在下限处低于 3:1 的色调将失败。缺口:浅色模式下的 warning 和 neutral 在完全不透明度下低于 3:1(OQ1)。 | audit:ProgressBar/a11y |
| FR7 | ProgressBar.test.tsx 目标标记测试套件;ProgressBar.a11y.chromium.spec.ts 标记名称测试 |
无;单个;多个;钳制;非有限;填充时;不确定;禁用;工具提示 | 缺失、错位或被裁剪的标记,位于 progressbar 内部的标记,不是由其标签命名的图像的标记,丢失的工具提示,或错误的填充时颜色,均会导致失败。 |
audit:ProgressBar/a11y |
| FR8 | ProgressBar.test.tsx 目标名称与标记目标测试;themingTargets.test.ts |
四个标准目标 | 缺失或重命名的目标会导致失败。差距:没有测试覆盖调用方的 data-variant。themingTargets.test.ts 只能捕获重命名或未记录的目标;如果某个部件不再携带其目标,则没有任何检查会失败。 |
audit:ProgressBar/theming |
| FR9 | ProgressBar.test.tsx ref 与 data-testid 测试 |
ref;测试 ID | 不是 div 的 ref 或丢失的测试 ID 会导致失败。差距:ref 测试只检查 ref 是 div,而不检查它是否为根节点,并且没有测试覆盖 DOM 属性、className、style 或 xstyle 合并顺序。 |
audit:ProgressBar/api |
| PR1 | 源码审查 | 所有状态 | 差距:如果 ProgressBar 开始检查附近内容,没有任何自动化检查会失败。 | audit:ProgressBar/behavior |
| 主题结构映射 | scripts/check-knowledge.mjs |
标准结构与四个目标 | 缺失、多余或过时的映射会导致仓库验证失败。 | audit:ProgressBar/theming |
决策日志¶
DEC-1 — ProgressBar 拥有足够的独立视觉表现¶
参考: component:ProgressBar/DEC-1
决策者: cixzhang,2026-08-30
ProgressBar 必须提供足够的独立视觉表现。组件内部或外部的可见文本可能有助于理解,但即使没有这些文本,进度条本身仍须负责传达已完成与剩余进度的对比。
公共 API 不得让这种正确性依赖于组件无法承载、关联或验证的外部内容。先解决组件自身的行为问题。只有在基础行为已正确之后,仍存在一个稳定的、由调用方所有的区分时,才考虑新增 API。
已拒绝:根据调用者对附近内容的声明来降低标准。那会将组件正确性变成一个组件无法验证的外部条件。
DEC-2 — 触摸填充时序与减弱动效脉冲¶
参考: component:ProgressBar/DEC-2
决策者: cixzhang,2026-11-01
在手指下,确定性填充的移动方式与 UIKit 的进度视图相同,因为触摸展示默认为实测的原生时序(spec:AST-094 DEC-1);鼠标则保留主题的动效。spec:AST-094 DEC-26 取代了这一触摸填充时序:值变化不是手势,因此填充在所有指针下都按主题的时长和缓动函数移动。不确定进度条在所有指针下保持其 40% 缓动滑动。在减弱动效下,移动的段仍然会移动,因此进度条停止移动,并在所有指针下于原地缓慢脉冲,其下限保持可见;缓慢的 2000ms 脉冲是一个所有者值,不同于 iOS Safari 在 0.30 至 0.60 不透明度之间实测的 1s 脉冲。
已拒绝:手指下不确定进度条的 iOS Safari 四分之一轨道扫动。
未决问题¶
- OQ1 — 在所有受支持的变体、主题和颜色模式下,哪种精确的视觉处理能让每个确定性表现都具有足够的独立已完成与剩余之间的区分度?(
human-design)
内容边界¶
本文件不重复消费者属性表或示例、当前审计结果、实施步骤、精确视觉值或系统主题规则。它会链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx