---
title: 骨架屏使用指南
summary: "介绍骨架屏的配置与使用方法，用于减少页面白屏时间并提升加载体验。"
tags: [骨架屏使用指南, 骨架屏配置, 白屏优化方案, 加载占位组件]
questions:
  - 骨架屏适用于哪些场景？
  - 使用骨架屏功能需要满足哪些环境要求？
  - 如何在 IDE 中生成骨架屏快照代码？
  - 骨架屏快照文件应该创建在哪个目录下？
  - 骨架屏的 data-remove-type 参数有哪些可选值，分别是什么含义？
  - 如何在手动模式下控制骨架屏的移除时机？
  - 骨架屏如何适配深色主题和自定义导航栏？
---

# 骨架屏使用指南

<Callout type="info" emoji="ℹ️">
  骨架屏可有效减少页面首次打开或页面切换时的白屏时间，提升视觉连续性与加载体验。
</Callout>

## 适用场景

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

## 环境要求

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

## 基本使用流程

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

1. 打开 IDE 骨架图预览工具。

<Image src="/images/skeleton/image1.png" />
2. 调整参数直至预览满意后点击“复制代码”。

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

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

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

目录示例：

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

<Image src="/images/skeleton/image2.png" width="260px" /> {/* 创建文件后目录截图 */}

### 步骤三：编译与验证

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

<Image src="/images/skeleton/image3.png" width="260px" /> {/* dist 目录内生成的文件截图 */}

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

## 骨架屏模板示例

```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>
```

### 深色主题适配示例

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

### 自定义导航栏偏移示例

```html
<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` 模式时，可在页面生命周期中手动移除：

```javascript
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` 导致父容器高度丢失；确保骨架工具选择范围正确 |
| 骨架与真实内容错位 | 自定义导航栏高度未偏移 | 添加导航偏移样式或确认导航配置 |