开发
API

小程序框架骨架屏

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

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

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

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

使用方法

目录结构如下:

骨架屏编写

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

SK 文件

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

其中template标签中为标准的 HTML 子集,仅支持div标签和 idclassstyle三个属性;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>

自动生成

  1. 开发者可通过开发者工具为当前正在预览的页面生成骨架屏代码。生成按钮入口位于模拟器面板左下角选择列表。
  1. 点击“生成骨架屏”,将有弹窗提示选择骨架屏动效以及是否允许插入骨架屏代码。点击“保留”将创建新的 (n).sk 文件(n 表示递增),点击“覆盖”将覆盖上次创建的 *.sk 文件。
  1. 勾选“自动引入”,表示将在 app.json 中生成 skeleton 配置,不勾选则不作处理。生成配置如下: "skeleton": { "page": { "pages/index/index": "pages/index/index.sk" } }
  2. 确定后将在当前页面同级目录下生成 *.sk 文件( * 表示页面名称 ),文件内包括骨架屏的代码模板以及样式,开发者可以修改调整。

需要了解整个过程,可观看以下视频:

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

属性名

类型

默认值

必填

说明

loading

'spin' | 'chiaroscuro' | 'shine'

'spin'

骨架屏显示时的动画

image

object

{shape:'rect', color:'#efefef'}

该配置接受 2 个字段,colorshapecolorshape 用于确定骨架页面中图片块的颜色和形状,颜色值支持 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单位。元素绝对定位都使用 vwvh

decimal

number

4

生成骨架屏页面中 css 值保留的小数点位数,默认为 4

手动开发

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

CSS 变量

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

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

目前提供的 CSS 变量如下:

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

开发者可通过 valcalc 等 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 文件。
点击纠错
该文档是否对你的开发有所帮助?
有帮助
没帮助
该文档是否对你的开发有所帮助?
有帮助
没帮助