骨架屏 -凯发app官方网站

更新时间：2025-09-26 18:07:30

订阅更新

我的文档

设置

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

使用限制

●

从

基础库

2.9.99 或更高版本、

客户端

10.5.26 或更高版本开始支持；若版本较低，骨架屏将不生效。

开启骨架屏

在 app.json 中配置如下基础内容：

{

"loadingpages": {

"ignorepages": [

"pages/foo/foo"

"externalpages": [

"plugin-private://2333/pages/foo/foo"

]

}

ignorepages

当 app.json 同目录下存在 app.loading.axml 和 app.loading.acss（可选）文件时，所有页面都会加载该骨架屏。通过

ignorepages

可控制哪些页面不应渲染骨架屏，支持如下值：

类型	示例	说明
string[]	["pages/index/index"]	不在此列表中的宿主小程序页面将使用 app.loading.axml 或者自身的 .loading.axml 渲染骨架屏。
字符串defaults	defaults	宿主小程序页面中仅有同名 .loading.axml 文件的可渲染骨架屏。
字符串all	all	所有宿主小程序页面不渲染骨架屏。

以如下项目结构为例：

不同的

ignorepages

配置会渲染骨架屏的页面是：

ignorepages 取值	渲染骨架屏的页面
["pages/ignore/ignore"]	●pages/default/default 使用 app.loading.axml ●pages/home/home 使用 home.loading.axml
defaults	●pages/home/home 使用 home.loading.axml
all	●无，所有页面均不渲染骨架屏。

externalpages

指定使用 app.loading.axml 作为骨架屏的非宿主小程序页面。例如，可将插件页面添加到此数组中。

内置变量

根据变量的来源与优先级，axml 中可以使用的变量包括：

变量名（优先级从低到高）	类型	说明
$app	object	应用信息
$app.query	object	全局参数
$page	object	页面信息
$page.route	string	页面路径
$page.query	object	页面参数
应用参数（不推荐）	any	全局参数，对早期骨架屏版本的兼容。不再推荐
页面参数（不推荐）	any	页面参数，对早期骨架屏版本的兼容。不再推荐
$systeminfo	object	getsysteminfo 异步对象
$storage	object	getstorage 异步对象
$menubuttonboundingclientrect	object	getmenubuttonboundingclient 异步对象
$backgroundfetchdata	object	getbackgroundfetchdata 异步对象（仅支持真机）

异步对象

骨架屏中提供的异步对象可以用于异步获取数据并刷新骨架屏。例如下段插值表达式将触发 jsapi 查询，并在查询结果返回后再次刷新骨架屏。

acss 变量（已废弃）

早期的骨架屏版本支持了众多 acss 变量，但查询系统信息并生成变量会造成明显的性能问题，使得骨架屏无法及时上屏，故此功能已被废止。请使用异步对象来做样式处理，例如：

延迟下屏

默认地，当页面真实数据可进行首次渲染时，骨架屏就会被真实数据对应的视图替换。当需要等待页面的关键异步数据接口返回后再替换骨架屏时，可以延迟骨架屏下屏并替换到真实数据渲染。

配置方式如下：