骨架屏使用指南

Info

骨架屏可有效减少页面首次打开或页面切换时的白屏时间，提升视觉连续性与加载体验。

适用场景

首屏数据较多、接口返回存在一定延迟的页面。
页面切换时存在明显空白或闪烁，希望过渡更自然。
需要与深色/浅色主题联动的占位展示。

环境要求

基础库版本需 >=2.27.2
@ray-js/cli 版本需 >=1.6.30
开发者工具版本需 >=0.9.0

基本使用流程

步骤一：在 IDE 中生成快照骨架代码

打开 IDE 骨架图预览工具。

调整参数直至预览满意后点击“复制代码”。

参数解释

选取元素范围：用于标识页面节点层级，控制生成区域。
忽略元素大小：过滤过小元素，避免无意义占位。
提取文本元素：开启后文字将转换为统一样式占位块，提高整体风格统一性。
忽略内联元素：排除宽高不确定的内联元素，避免错位。
快照背景色：配置在浅色/深色主题下的背景占位颜色。
自定义导航栏：若页面 navigationStyle = custom，需勾选以适配导航高度偏移。
保持原生样式：使用元素自身背景色作为占位色（关闭则统一骨架色）。
叠加透明度：调节色块层级叠加后的深浅效果。

步骤二：创建骨架屏快照文件

在对应页面目录下创建 页面名.snapshot.html 文件，并粘贴步骤一复制的代码。

目录示例：

└── home
    ├── index.config.ts
    ├── index.moudle.less
    ├── index.snapshot.html  # 骨架屏文件
    └── index.tsx

步骤三：编译与验证

执行正常构建流程。在构建输出目录 dist 中检查对应页面是否包含 *.snapshot.html：

打开小程序页面，观察：在业务逻辑与真实内容渲染前，应先显示骨架占位层，随后自然过渡到真实内容。

骨架屏模板示例

<style data-version="v2" data-remove-type="default">
  [is="snapshot-root"] {
    pointer-events: none;
    z-index: 100000;
    position: fixed;
    top: 0;
    left: 0;
    width: 100vw;
    height: 130vh;
    background-color: var(--skeleton-bg);
  }
  [is="snapshot-root"] div {
    position: absolute;
  }
  /* 自定义额外样式，可按需追加 */
</style>
<div style="top: 20px; width: 20vw; height: 20vh; background-color: #eee;">
  骨架图元素
</div>

深色主题适配示例

<style>
  [theme="dark"] [is="snapshot-root"] {
    background-color: #1c1c1e; /* 深色模式占位背景 */
  }
</style>

自定义导航栏偏移示例

<style>
  [is="snapshot-root"] div {
    transform: translateY(calc(var(--app-device-navbar-height, 44px) + var(--app-device-status-height, 20px)));
  }
</style>

参数说明

参数	可选值	说明	版本/依赖
`data-version`	`v2`	骨架样式版本标识（固定值）	-
`data-remove-type`	`default` / `manual`	移除模式：`default` 页面渲染完成后自动移除；`manual` 需手动调用 `removeSnapshot({ animation?: boolean })` 精确控制时机	`manual` 需基础库 >= 2.29.0

当使用 manual 模式时，可在页面生命周期中手动移除：

usePageEvent('onLoad', () => {
  const pages = getCurrentPages();
  const currentPage = pages[pages.length - 1];
  // 需保证基础库 >= 2.29.0 且骨架模板中设置 data-remove-type="manual"
  currentPage.removeSnapshot({ animation: false }); // animation: true 可开启过渡淡出
});

常见问题排查

现象	可能原因	处理方式
某元素未生成	元素本身无高度或被继承定位影响	检查是否使用 `position: fixed` 导致父容器高度丢失；确保骨架工具选择范围正确
骨架与真实内容错位	自定义导航栏高度未偏移	添加导航偏移样式或确认导航配置

#骨架屏使用指南

#适用场景

#环境要求

#基本使用流程

#步骤一：在 IDE 中生成快照骨架代码

#参数解释

#步骤二：创建骨架屏快照文件

#步骤三：编译与验证

#骨架屏模板示例

#深色主题适配示例

#自定义导航栏偏移示例

#参数说明

#常见问题排查