抖音开放平台Logo
开发者文档
小程序
控制台
  • 开发教程与代码示例
  • 入门
  • 小程序框架
  • 小程序运行时
  • 自定义组件
  • 基础教程
  • 能力教程
  • 性能优化
  • 概述
  • 性能优化辅助平台/工具
  • 性能优化方法
  • 数据预取
  • TTWebAssembly
  • 框架骨架屏
  • 数据预取配置方案示例
  • 数据预取js方案
  • 数据预取js方案接入示例
  • 让 image 图片体积减小 7 成
  • 启动性能
  • 运行时性能
  • 小程序白屏&渲染异常问题优化
  • 安全
    • 基础库 2.78.0，IDE 3.2.6 开始支持本能力。支持宿主：抖音、抖音极速版。
    骨架屏是页面的一个空白版本，通常会在页面完全渲染之前，通过一些灰色的区块大致勾勒出轮廓，待数据加载完成后，再替换成真实的内容。
    通过小程序框架提供骨架屏机制，能比业务中创建的骨架屏加载时机更靠前，使用这一机制，可以减少用户的白屏等待时长，给用户带来更好的体验。
    以懂车帝小程序为例，使用框架骨架屏后与自研骨架屏对比 LCP 到达率显著提升，Android 提升率达 6.79%，尤其对于页面加载复杂，LCP 到达率较低的页面，效果显著。
    为了开发的便利，开发者工具将提供自动生成骨架屏代码的能力，支持根据开发者的配置生成骨架屏。

    使用方法

    骨架屏编写

    骨架屏的编写有自动生成和手动开发两种方式。自动生成简单高效，手动开发更加灵活，自动生成后亦可手动修改，开发者可根据自身需要灵活选择。骨架屏编写依赖模板文件，下面将详细介绍下骨架屏模板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>
    自动生成
      1.开发者可通过开发者工具为当前正在预览的页面生成骨架屏代码。生成按钮入口位于模拟器面板左下角选择列表。
      2.点击「生成骨架屏」，将有弹窗提示选择骨架屏动效以及是否允许插入骨架屏代码。点击「保留」将创建新的 (n).sk 文件（n 表示递增），点击「覆盖」将覆盖上次创建的 *.sk 文件。
      3.勾选「自动引入」，表示将在 app.json 中生成 skeleton 配置，不勾选则不作处理。生成配置如下：
      4.确定后将在当前页面同级目录下生成 *.sk 文件（ * 表示页面名称 ），文件内包括骨架屏的代码模板以及样式，开发者可以修改调整。
        需要了解整个过程，可观看以下视频：
    开发者可在 app.json 和 page.json 的["skeleton"]["config"]中进行骨架屏相关配置，page.json 的配置优先级高于 app.json。具体配置如下：
    属性名
    类型
    默认值
    必填
    说明
    loading
    string
    spin
    否
    骨架屏显示时的动画。支持枚举值： spin, chiaroscuro, shine
    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
    string
    fullscreen
    否
    默认为使用绝对定位占满全屏。当对自定义组件使用，作为局部加载的样式时，可设置为 auto，高度随内容高度撑开。支持枚举值：fullscreen , auto
    cssUnit
    string
    vw
    否
    CSS单位。元素绝对定位都使用 vw 与 vh。支持枚举值：px , rem , vw, vh, vmin, vmax
    decimal
    number
    4
    否
    生成骨架屏页面中 css 值保留的小数点位数，默认为 4。
    手动开发
    开发者可在小程序项目任意位置新建和编写*.sk文件。
    CSS 变量
    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 文件。
    ​