跳转至

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

主题化解剖

{
  "Placeholder": {"target": "skeleton"}
}

家族与系统关系

  • 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