Skeleton 骨架屏
内容尚未到达时，按最终版面占位。
用法
按真实卡片的封面与文字节奏占位
组件结构
加粗的是必需部件。
data-scope="skeleton"：root · item
示例
形状
容器的 shape 是该组的默认形状，单根骨架条自带 shape 时按自己的形状
加载结束
loading 期间容器报告 aria-busy，切换为 false 后整块收起，位置让给真实内容
动效
在微光、呼吸和静止三档之间选择
设计指引
何时使用
- 首屏或整块区域的加载，且版面结构可预测。
- 加载时间通常在几百毫秒到几秒之间。
何时不用
- 加载极快时，骨架闪烁比直接出现更差。
- 版面完全不可预测时，使用加载指示器。
- 一次动作的等待（提交中）使用按钮的载入态。
特性
loading为假时替换为真实内容。shape决定骨块的形状（文本行、圆形、矩形）。animation在微光、呼吸和静止三档之间切换。
组合
最佳实践
- 骨架的形状与真实内容对应：行数、宽度、圆角都要接近，否则内容到达时整块跳动。
- 不做得比真实内容更复杂。
反模式
- 用一块巨大的灰色矩形代替所有内容。
- 加载失败后骨架持续闪烁。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-skeleton> |
| Vue 组件 | XhSkeletonItem XhSkeletonRoot |
| 状态机 | 无，connect 直接由 props 算属性 |
| 皮肤 | @xihan-ui/styles/skeleton.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
animation | SkeletonAnimation | 动效档，默认 'shimmer'；默认档不输出 data-animation。 | |
loading | boolean | 是否还在加载，默认 true。 | |
shape | SkeletonShape | 容器内骨架条的默认形状，默认 'text'。 |
React 适配器 props
只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。
| React 组件 | 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
XhSkeletonItem | shape | SkeletonShape | 该根的形状，覆盖容器提供的默认值。 |
状态
公开状态写入 data-state。
| 部件 | 取值 |
|---|---|
root | 'loading' | 'loaded' |
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
loading | boolean | 当前是否处于加载态。 |
getRootProps | () => T['element'] | |
getItemProps | (item?: SkeletonItemProps) => T['element'] |
无障碍
键盘
规格出处：W3C APG
无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。
ARIA
以下属性由 connect 生成。
| 部件 | 属性 | 值 |
|---|---|---|
root | aria-busy | 'true' | undefined |
item | aria-hidden | 'true' | undefined |
样式参考
皮肤
@xihan-ui/styles/skeleton.css 使用 [data-scope="skeleton"][data-part="root"] 部件选择器，位于 xihan.components 与 xihan.motion 层。覆盖样式使用 xihan.overrides。
forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-animation | props.animation |
root | data-state | 'loading' | 'loaded' |
item | data-shape | item.shape |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-skeleton-bg | item | background-color | default | --xh-bg-subtle | skeleton 的 item 部件 background-color 覆盖槽。 |
--xh-skeleton-circle-radius | item | border-radius | shape=circle | --xh-shape-circle | skeleton 的 item 部件 border-radius 覆盖槽。 |
--xh-skeleton-circle-size | item | inline-size | shape=circle | --xh-control-h-lg | skeleton 的 item 部件 inline-size 覆盖槽。 |
--xh-skeleton-duration | item | animation | default | --xh-motion-loop-shimmer | skeleton 的 item 部件 animation 覆盖槽。 |
--xh-skeleton-gap | root | gap | default | --xh-space-3 | skeleton 的 root 部件 gap 覆盖槽。 |
--xh-skeleton-pulse-duration | itemroot | animation | animation=pulse | --xh-motion-loop-shimmer | skeleton 的 item、root 部件 animation 覆盖槽。 |
--xh-skeleton-radius | item | border-radius | default | --xh-shape-control | skeleton 的 item 部件 border-radius 覆盖槽。 |
--xh-skeleton-rect-block-size | item | min-block-size | shape=rect | --xh-control-h-lg | skeleton 的 item 部件 min-block-size 覆盖槽。 |
--xh-skeleton-rect-radius | item | border-radius | shape=rect | --xh-shape-surface | skeleton 的 item 部件 border-radius 覆盖槽。 |
--xh-skeleton-sheen | item | background-image | default | --xh-bg-surface-raised | skeleton 的 item 部件 background-image 覆盖槽。 |
--xh-skeleton-text-block-size | item | block-size | shape=text | --xh-text-caption-size | skeleton 的 item 部件 block-size 覆盖槽。 |
--xh-skeleton-text-radius | item | border-radius | shape=text | --xh-shape-pill | skeleton 的 item 部件 border-radius 覆盖槽。 |
动效
动效角色：循环（见动效规范）。
可覆盖的动效槽：--xh-skeleton-duration · --xh-skeleton-pulse-duration。
关键帧 xh-skeleton-pulse · xh-skeleton-shimmer 随皮肤自带，不引用别处文件里的名字。时长与缓动读动效令牌，改令牌即改全局节奏。
prefers-reduced-motion: reduce 下本组件另有降级规则。