Skeleton 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个占位块,具有 width、height、radius 以及一个交错 index。 |
| 行为 | 该块对辅助技术隐藏,等待一秒,然后分十步使其不透明度脉冲变化;减少动态效果时保持静态。 |
| 对最终用户的影响 | 视力正常的用户看到正在加载的内容轮廓;屏幕阅读器用户不会获得空占位符;高对比度用户仍能看到该块。 |
| 对构建者的影响 | 无;该记录描述的是已发布的行为。 |
| 兼容性/就绪状态 | 已发布行为记录为当前状态;无 API、默认值或输出变更。未记录实现差距。 |
| 审查检查 | 拒绝默认暴露的占位符、steps() 时序函数、减少动态效果下的脉冲,或在强制颜色模式下消失的块。 |
| 治理规则 | architecture:component-theming-surface/INV2,INV6;architecture:public-component-api/INV5,INV6,INV8。 |
本表格是审查投影;下方正文具有权威性。
意图¶
Skeleton 在内容加载时充当占位,使页面保持布局并显示内容将出现的位置。它负责占位符的形状、绘制、脉冲,以及将其从无障碍树中排除。
兼容性与迁移¶
- 已发布默认值保持不变:
yes - 兼容性类别:记录已发布的行为;无公共 prop、默认值、DOM、样式或目标输出变更
- 受控/非受控行为:不适用;Skeleton 不持有状态
- 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
所有权边界¶
拥有
- 占位块及其
skeleton主题目标、尺寸和圆角。 - 其在正常、提高对比度和强制颜色模式下的绘制。
- 延迟的、交错的不透明度脉冲及其在减少动态效果下的抑制。
- 其默认从无障碍树中排除。
不拥有 / 非目标
- 周边区域的加载状态、忙碌语义、布局以及真实内容何时替换占位符——由产品调用点(callsite)拥有。
- 没有已知形状的不确定进度——由
component:Spinner拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 尺寸(Size) | width 和 height:像素数值或 CSS 值 |
块的尺寸。 | 始终 | 100% |
component:Skeleton |
稳定 | 字符串按 CSS 原样传递。 |
| 圆角(Radius) | none、0、1、2、3、4、rounded |
来自圆角刻度的转角半径。 | 始终 | 3 |
component:Skeleton |
稳定 | TypeScript 拒绝其他值。 |
| 交错(Stagger) | 非负整数 index |
延迟脉冲,使顺序占位符产生涟漪效果。 | 始终 | 0 |
component:Skeleton |
稳定 | 任何数字都会应用于延迟公式。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | Skeleton 渲染一个无子元素的 div,携带 skeleton 目标,按 width 和 height 设置大小(数字以像素计,字符串作为 CSS 值),默认均为 100%。 |
当前源代码和测试 |
| FR2 | radius 将 none 映射为无圆角,0 映射为 --radius-none,1 映射为 --radius-inner,2 映射为 --radius-element,3 和 4 映射为 --radius-container,rounded 映射为 --radius-full;默认值为 3。radius 是调用点几何属性(AV2),与 width 和 height 一样,不通过 themeProps 反映(architecture:component-theming-surface INV6)。 |
当前源代码 |
| FR3 | 该块以 0.25 的不透明度绘制 --color-skeleton。在 prefers-contrast: more 下,它将该颜色向正文文本方向混合 30% 后绘制。在 forced-colors: active 下,它绘制 GrayText,该规则优先于对比度规则;无脉冲运行时为完全不透明度;当允许动态效果时,FR4 的脉冲仍会改变其不透明度。 |
当前源代码和测试 |
| FR4 | 该块将其不透明度从 0.25 到 0.925 以十个相等的保持步长进行脉冲并返回,无限交替,每次上升和每次下降都使用主题在 tempo 缩放之前设置的 --duration-medium-max(spec:AST-108 FR4),采用线性时序函数且不使用 steps()。脉冲在 1000 毫秒加上 100 毫秒乘以 index 后开始。在 prefers-reduced-motion: reduce 下没有脉冲。 |
当前源代码和测试 |
| FR5 | ref 到达该块。受支持的 DOM、ARIA、data 和事件属性(包括 data-testid)在默认 aria-hidden 之后到达该块;xstyle、className 和 style 按该顺序在组件样式之后合并。 |
当前源代码和测试 |
允许的变化¶
- AV1 — 主题绘制。 主题可以通过
skeleton更改该块的视觉属性,而不改变其解剖结构或无障碍排除。 - AV2 — 形状。 宽度、高度和半径因调用点而异,以匹配它们所代表的内容。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 默认 | aria-hidden 块,不透明度为 0.25,在一秒后开始脉冲。 |
尺寸和半径。 |
| 错开 | 每个块的脉冲在前一个索引之后 100 毫秒开始。 | 块的数量。 |
| 减少动态 | 静态块,不透明度为 0.25。 | — |
| 强制颜色 | GrayText 块在无脉冲运行时保持完全不透明;允许动态时,FR4 脉冲会改变其不透明度(AR2)。 |
— |
| 由调用方暴露 | aria-hidden={false} 到达该块。 |
— |
转换与优先级顺序¶
- ORD1 — 绘制。 默认骨架颜色 → 增强对比度混合 → 强制颜色
GrayText。 - ORD2 — 属性。
aria-hidden="true"和data-testid→ 组件类 → 组件样式 →xstyle→className→style→ 调用方属性。
性能与资源¶
- PR1 — 非主线程脉冲。 脉冲仅改变不透明度,且不使用步进时序函数,因此受支持的引擎无需主线程重绘即可运行它。Skeleton 不添加任何监听器、观察器或计时器。
无障碍契约¶
- AR1 — 默认隐藏。 该块为
aria-hidden="true",因此辅助技术不会播报空的占位符;调用方可传入aria-hidden={false}。周围区域传达忙碌状态。 - AR2 — 强制颜色和增强对比度绘制。 该占位符是装饰性的。在强制颜色模式下,它绘制为
GrayText,以便在浏览器会移除其填充的情况下保持可见,在无脉冲运行时保持完全不透明;允许动态时,FR4 脉冲仍会将其不透明度从 0.25 变化到 0.925。在增强对比度下,其颜色向主文本颜色方向移动 30%。 - AR3 — 减少动态。 当用户要求减少动态时,移除脉冲。
设计关系¶
| 解剖结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 占位符 | 以柔和脉冲预览加载内容的形状。 | 当前源代码和公开文档 | 支持 | FR1–FR4, AR1–AR3 |
主题化解剖¶
家族与系统关系¶
architecture:component-theming-surface拥有skeleton目标的目标限定。architecture:public-component-api拥有 ref、透传和样式输入规则;FR5 将它们应用于该块。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1、FR5、AR1 | Skeleton.test.tsx 渲染和无障碍测试 |
默认;调用方传入 aria-hidden={false} |
移除该块、默认 aria-hidden 或调用方覆盖会导致失败。缺口:没有测试覆盖 ref、默认 100% 尺寸或样式输入顺序。 |
audit:Skeleton/a11y |
| FR4、PR1、AR3 | Skeleton.test.tsx 脉冲(pulse)测试套件 |
编译后的关键帧和时序 | steps() 时序函数或更改后的不透明度步骤会导致失败。缺口:持续时间、仅含不透明度的关键帧、起始延迟、逐索引交错以及减弱动效移除均无自动化检查。 |
audit:Skeleton/motion |
| FR3、AR2 | Skeleton.test.tsx 强制颜色测试套件 |
强制颜色 | 从编译后的 CSS 中移除 GrayText 或全不透明度覆盖会导致失败。缺口:增强对比度混合、以及两种媒体特性同时生效时哪条规则胜出,均无自动化检查;强制颜色渲染(包括其中的脉冲)未在浏览器中验证。 |
audit:Skeleton/a11y |
| FR1–FR3 | 在浏览器中查看 Skeleton.stories.tsx 的 Shapes 和 StaggeredList 夹具(fixtures) |
圆角 rounded、3、2、none;交错列表 |
缺口:没有单元测试断言尺寸、圆角或增强对比度绘制效果,也没有固定的 story 渲染圆角 0、1 或 4 或增强对比度模式;其他值仅体现在渲染的夹具中。 |
audit:Skeleton/layout |
| 主题解剖映射(Theming anatomy map) | scripts/check-knowledge.mjs |
规范解剖结构和当前目标 | 缺失、多余、带前缀或过期的映射会导致仓库验证失败。 | audit:Skeleton/theming |
| AR1 | 无障碍树证据(spec:AST-009 FR3) |
默认和公开的占位符 | 缺口:没有无障碍树检查证明占位符不在树中;单元测试仅断言了该属性。 | audit:Skeleton/a11y |
决策日志¶
无记录。该记录描述的是已发布的行为。
待解决的问题¶
无。
内容边界¶
本文件不重复消费者属性表/示例、当前审计结果、实现步骤或家族/系统规则。它通过链接指向这些内容的负责人。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx