Skeleton

Skeleton 用于在数据加载、图片加载或异步内容渲染前提供视觉占位。Skeleton 适合手动拼出固定形状，SkeletonContainer 可以保留子节点结构并自动把文本、媒体和交互元素转换成骨架块。

import { Skeleton, SkeletonContainer } from '@skyroc/web-ui';

何时使用

• 内容正在异步加载，但页面布局已经确定。
• 需要减少空白状态和加载闪烁，让用户感知到内容结构。
• 需要为卡片、列表、头像、图片或详情页展示占位块。
• 只有短暂等待且不需要表现内容结构时，可以使用 Spinner 或 Progress。

基础用法

使用 className 控制 Skeleton 的宽高、圆角和布局位置。

<Skeleton className="size-12 rounded-full" />
<Skeleton className="h-4 w-[250px]" />
<Skeleton className="h-[125px] w-[250px] rounded-xl" />

自动骨架化

SkeletonContainer 在 loading 为 true 时会递归处理子节点：文本会变成文本占位，媒体和无内容布局块会变成媒体占位，Button 等交互组件会变成交互占位。

<SkeletonContainer loading>
  <article>
    <h2>Article Title</h2>
    <p>Article preview content</p>
  </article>
</SkeletonContainer>

动画

通过 animation 控制自动生成骨架块的动效。pulse 是默认脉冲动画，wave 使用横向渐变扫光，none 展示静态占位。

控制范围和样式

通过 depth 限制递归深度，通过 skeletonColor 和 skeletonRadius 控制生成骨架块的颜色和圆角。

<SkeletonContainer
  depth={1}
  loading
/>

<SkeletonContainer
  animation="wave"
  loading
  skeletonColor="hsl(var(--primary) / 0.18)"
  skeletonRadius="999px"
/>

排除元素

通过 excludeKeys 保留指定 key 的元素。被排除的元素会带上 data-skeleton-exclude，不会被容器的 loading 样式隐藏。

<SkeletonContainer
  excludeKeys={['action-btn']}
  loading
>
  <button key="action-btn">Take Action</button>
</SkeletonContainer>

API

Skeleton

基础占位块。通常通过 className 设置具体形状，组件本身渲染为 div。

SkeletonContainer

自动骨架化容器。loading=false 时直接返回 children；loading=true 时渲染包装容器并把 children 转换成骨架结构。

类型