小程序框架骨架屏

基础库 2.47.0，IDE 3.2.6 开始支持本能力，目前仅对白名单小程序开放。

骨架屏是页面的一个空白版本，通常会在页面完全渲染之前，通过一些灰色的区块大致勾勒出轮廓，待数据加载完成后，再替换成真实的内容。

通过小程序框架提供骨架屏机制，能比业务中创建的骨架屏加载时机更靠前，使用这一机制，可以减少用户的白屏等待时长，给用户带来更好的体验。

为了开发的便利，开发者工具将提供自动生成骨架屏代码的能力，支持根据开发者的配置生成骨架屏。

使用方法

目录结构如下：

骨架屏编写

骨架屏的编写有自动生成和手动开发两种方式。自动生成简单高效，手动开发更加灵活，自动生成后亦可手动修改，开发者可根据自身需要灵活选择。骨架屏编写依赖模板文件，下面将详细介绍下骨架屏模板SK文件。

SK 文件

SK 文件是框架骨架屏的模板文件，文件命名为*.sk，由template和style两部分组成。

其中template标签中为标准的 HTML 子集，仅支持div标签和 id、class、style三个属性；style为标准的 CSS。示例代码如下：

<template>
  <!--  骨架屏HTML代码，标准的HTML子集；仅支持`div`标签和 `id`、`class`、`style`三个属性 -->
  <div id="sk-main">
    <div class="sk-title" style="background-color: red"></div>
  </div>
</template>
<style>
  /* 骨架屏样式代码，标准的CSS */
  .sk-title {
    color: red;
  }
</style>

自动生成

开发者可通过开发者工具为当前正在预览的页面生成骨架屏代码。生成按钮入口位于模拟器面板左下角选择列表。

点击“生成骨架屏”，将有弹窗提示选择骨架屏动效以及是否允许插入骨架屏代码。点击“保留”将创建新的 (n).sk 文件（n 表示递增），点击“覆盖”将覆盖上次创建的 *.sk 文件。

勾选“自动引入”，表示将在 app.json 中生成 skeleton 配置，不勾选则不作处理。生成配置如下： "skeleton": { "page": { "pages/index/index": "pages/index/index.sk" } }
确定后将在当前页面同级目录下生成 *.sk 文件（ * 表示页面名称），文件内包括骨架屏的代码模板以及样式，开发者可以修改调整。

需要了解整个过程，可观看以下视频：

开发者可在 app.json 和 page.json 的["skeleton"]["config"]中进行骨架屏相关配置，page.json 的配置优先级高于 app.json。具体配置如下：

属性名	类型	默认值	必填	说明
loading	'spin' \| 'chiaroscuro' \| 'shine'	'spin'	否	骨架屏显示时的动画
image	object	{shape:'rect', color:'#efefef'}	否	该配置接受 2 个字段，`color`、`shape`。`color` 和 `shape` 用于确定骨架页面中图片块的颜色和形状，颜色值支持 16 进制，形状支持两个枚举值，`circle` （圆形）和 `rect`（矩形）
button	object	{color:'#efefef'}	否	该配置接收 1 个字段`color` 。`color` 用来确定骨架页面中被视为按钮块的颜色
backgroundColor	string	'#fff'	否	骨架屏背景色
mode	'fullscreen' \| 'auto'	'fullscreen'	否	默认为使用绝对定位占满全屏。当对自定义组件使用，作为局部加载的样式时，可设置为 `auto`，高度随内容高度撑开
cssUnit	'px' \| 'rem' \| 'vw' \| 'vh' \| 'vmin' \| 'vmax'	'vw'	否	`CSS`单位。元素绝对定位都使用 `vw` 与 `vh`
decimal	number	4	否	生成骨架屏页面中 `css` 值保留的小数点位数，默认为 4

手动开发

开发者可在小程序项目任意位置新建和编写*.sk文件。

CSS 变量

基础库 2.51.0，IDE 3.2.8 开始支持本能力。

在页面配置了自定义导航栏，开发者期望实现和页面真实布局相似的骨架屏时，可使用 CSS 变量来完成。

目前提供的 CSS 变量如下：

变量名	单位	说明	最低支持版本
--pixel-ratio	number	设备像素比	2.51.0
--status-bar-height	px	状态栏的高度	2.51.0
--menu-button-top	px	胶囊按钮到页面顶部距离	2.51.0
--menu-button-height	px	胶囊按钮高度	2.51.0

开发者可通过 val 和 calc 等 CSS 函数来使用这些变量，示例如下：

.sk-logo {
  background: url("pages/index/logo.png");
  margin: var(--menu-button-top) auto 0;
  /* 可设置默认值兼容无 css 变量的版本 */
  height: var(--menu-button-height, 30px);
  width: 119px;
}

.sk-text {
  /* 计算胶囊按钮到状态栏的距离 */
  margin-top: calc(var(--menu-button-top) - var(--status-bar-height));
  background: red;
  height: 30px;
  width: 100%;
}

显示控制

骨架屏的显示，需要在app.json的["skeleton"]["page"]中进行配置，示例同上文自动生成配置示例。

skeleton 配置详情说明见 app.json 文档。

移除控制

骨架屏的移除，有超时隐藏和主动隐藏两种方式。超时隐藏通过配置控制，使用简单；主动隐藏通过调用API控制，能更准确的控制隐藏时机，同时支持局部隐藏来达到渐进式加载的效果。

超时隐藏

在未进行任何配置的情况下，框架骨架屏将在加载后2000ms自动隐藏。

开发者可在app.json的["skeleton"]["config"]["timeout"]中配置全局超时时间，单位为ms。当timeout值为0时，表示关闭全局超时隐藏配置。["skeleton"]["config"]详情说明见 app.json 文档。

另外，开发者可在page.json的["skeleton"]["config"]["timeout"]中配置局部超时时间，配置方式同全局配置，优先级高于全局配置。

主动隐藏

开发者将timeout值为0关闭骨架屏超时隐藏配置后，可使用 this.removeSkeleton() API 主动隐藏骨架屏。示例代码如下：

Page({
  onReady() {
    this.removeSkeleton && this.removeSkeleton();
  },
});

局部隐藏

开发者可使用 this.removeSkeleton({id: ''}) API 局部隐藏指定ID的骨架屏节点。示例代码如下：

Page({
  onReady() {
    this.removeSkeleton && this.removeSkeleton({ id: "node-id" });
  },
});

代码示例

开发者工具中预览

Bug & Tip

Tip：id 不能当做 CSS 选择器使用；
Tip：使用 this.removeSkeleton 时需要做兼容处理，this.removeSkeleton && this.removeSkeleton()；
Tip：需要等当前页面全部加载完成才可点击生成骨架屏；
Tip：如果使用了自定义导航栏，目前骨架屏方案无法和真正布局完全对应，会有一些误差；
Tip：骨架屏仅包括页面首屏中的可见区域，对于横向滚动的 swiper 等容器组件，超出屏幕的子元素将被忽略；
Tip：当效果不理想时，建议调整相关配置重新自动生成，或者修改自动生成的骨架屏代码（每个元素都使用了绝对定位，开发者可以修改元素而不影响其他元素固定位置和大小）；
Tip：骨架屏通常用于商品列表、新闻列表等页面，对于动画/原生/复杂组件较多的页面展示效果不佳；
Tip：生成的骨架屏代码中会包含预览时的页面数据（比如文字等），将被用来填充页面；
Tip：对于存在背景色（backgroundColor）的元素处理方式为直接删除该属性，生成的骨架屏可能并不符合预期，开发者可根据自身需求来改变骨架屏模块背景色；
Tip：骨架屏配置并不支持 remove 等配置来单独处理操作选择的 DOM 元素。如需删除或者隐藏某些元素，可以更改 *.sk 文件。

点击纠错

该文档是否对你的开发有所帮助？

有帮助

没帮助

该文档是否对你的开发有所帮助？

有帮助

没帮助

小程序框架骨架屏
使用方法
代码示例
Bug & Tip