小程序框架骨架屏
基础库 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 个字段, |
button | object | {color:'#efefef'} | 否 | 该配置接收 1 个字段 |
backgroundColor | string | '#fff' | 否 | 骨架屏背景色 |
mode | 'fullscreen' | 'auto' | 'fullscreen' | 否 | 默认为使用绝对定位占满全屏。当对自定义组件使用,作为局部加载的样式时,可设置为 |
cssUnit | 'px' | 'rem' | 'vw' | 'vh' | 'vmin' | 'vmax' | 'vw' | 否 |
|
decimal | number | 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
文件。