Skeleton 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在内容加载时展示占位轮廓，帮助用户预先理解页面结构，并保持加载过程中的布局连续。

使用选择

用于内容加载占位。已有组件支持 loading / skeleton 时先声明状态，让组件提供正确形状，不在页面重画它的骨架。

• loading=false 渲染真实 children；加载时按 variant / width / height 或 renderHints 显示占位。

• 优先让已有组件通过 loading 提供形状；独立骨架的尺寸和圆角仍使用设计系统 Token。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Skeleton, Frame } from '@snowui-design-system/components';</script> <Frame row enableAutoLayout={false} style="width: min(100%, 20rem); display: flex; align-items: center; gap: var(--gap-3);">	<Skeleton variant="circle" width={48} height={48} />	<Frame column enableAutoLayout={false} style="flex: 1; min-width: 0; gap: var(--gap-2);"><Skeleton variant="line" width="42%" height={14} /><Skeleton variant="line" width="92%" height={12} /><Skeleton variant="line" width="68%" height={12} /></Frame>	<Skeleton variant="rect" width={72} height={32} /></Frame>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

布局模型

主布局模型：内禀原子布局。

• Skeleton 作为占位原语时，尺寸优先由组件自注册的 renderHints 决定；显式 variant / width / height 可覆盖 hints，旧 componentClass 映射只作兼容。作为外部布局子项时表现为 Hug 或按调用方传入的固定尺寸渲染。

• 多条 text skeleton、avatar-group skeleton overlap 等只是 Skeleton 私有渲染布局，用于模拟目标组件占位，不向外提供通用区域协议。

• Skeleton 不输出 data-auto-layout；Frame 的 loading 协议负责决定是否渲染 Skeleton，Skeleton 本身不接管宿主布局。

适用范围

• 直接在 test / demo 中显式渲染骨架，用于观察默认样式。

• 被 Frame 在 loading + skeleton 协议中内部调用，作为默认占位渲染器。

• 配合组件侧的 renderHints 接收最终的骨架尺寸与行数提示。

2.2 renderHints 规则

未传 radius 时，非圆形 Skeleton 使用 var(--radius-3, 0.75rem)；circle 始终使用 50%。旧 Icon class 映射仍保留 rect + 50% 的兼容外观。

解析顺序

Skeleton 的布局解析顺序固定如下：

1. 存在 renderHints 时视为组件已自注册，直接以 hints 创建布局；显式 variant / width / height 逐字段优先。

2. 没有 hints 但传了显式 variant / width / height 时，按显式单项骨架渲染。

3. 仅旧调用方没有 hints / 显式几何时，才根据 componentClass 读取历史默认布局。

4. 完全未命中时回退为通用 rect 骨架。

4.1 通用样式

4.2 布局容器样式

补充规则：

• .snowui-skeleton-layout-single 会切回 display: block。

• .snowui-skeleton-layout-text 会改为纵向布局：width: 100%; flex-direction: column; align-items: stretch;

• .snowui-skeleton-layout-avatar-group 保持 gap: 0。

4.3 形状默认值

补充规则：

• line 和 rect 默认圆角统一为 12px。

• circle 永远保持 border-radius: 50%。

• line / circle / rect 都有 max-width: 100%; max-height: 100%; 兜底。

文本骨架规则

任何已注册组件都可以用 renderHints.rows 展开成多条文字骨架；Text 会根据内容自动计算行数。

6.1 行数来源

• Text 自身在骨架态下会统计第一层块级文本段落节点数量。

• 当前统计的标签集合是：

  • div

  • p

  • li

  • blockquote

  • h1-h6

• 第一层存在纯文本内容时，会额外记作 1 条。

• 最终最少渲染 1 条。

6.2 多条文字骨架布局

第一层渲染规则

Skeleton 本身不负责递归拆解整棵组件树，当前规则固定为“只看第一层”。

• 当组件自身进入 loading + skeleton 时，优先渲染当前组件自己的 Skeleton。

• 不继续展开组件内部的 Icon / Text / Avatar 等子组件。

• 当 Frame 进入 loading + skeleton 时：

  • 若第一层存在已自注册的直接子组件，则只渲染这些第一层组件对应的 Skeleton。

  • 若第一层不存在组件，则 Frame 自身回退为文字形态 Skeleton。

尺寸规则

• 数字型 width / height 会统一转成 rem。

• Skeleton 优先使用组件通过 renderHints.width / height / radius / rows 提供的最终几何。

• 这意味着圆角矩形 Skeleton 在组件已经提供尺寸提示时，会跟随组件的最终宽高，而不是回退成通用短宽。

• 当前没有启用“读取真实 DOM 实测尺寸”的通用机制。

使用示例

 <div class="flex flex-col gap-8">    <Skeleton variant="text" width="12rem" />    <Skeleton variant="circular" width={40} height={40} />    <Skeleton variant="rectangular" width="16rem" height="6rem" /></div>  <Frame loading={pageLoading}>    <Button>提交</Button>    <Text>加载中的文本</Text></Frame>  <Frame loading skeleton>    <Button variant="filled">        <Icon />        <Text>Search</Text>    </Button></Frame>  <Text loading skeleton class="w-full">    <div>段落一</div>    <div>段落二</div>    <div>段落三</div></Text>  <Frame    loading={pageLoading}    skeleton={false}    whileLoad={{ opacity: 0.6, scale: 0.98 }}>    <Button>提交</Button></Frame>