# 骨架屏

骨架屏是頁面的一個空白版本，通常會在頁面完全渲染之前，通過一些灰色的區(qū)塊大致勾勒出輪廓，待數據加載完成后，再替換成真實的內容。通常在小程序中，我們需要手工維護骨架屏的代碼，當業(yè)務變更時，同樣需要對骨架屏代碼進行調整。為了開發(fā)的便利，開發(fā)者工具提供了自動生成骨架屏代碼的能力。

# 運行環(huán)境

下載并安裝 1.03.2006032 或 1.04.2006032 以上版本的開發(fā)者工具

# 使用方法

工具可以為當前正在預覽的頁面生成骨架屏代碼。工具入口位于模擬器面板右下角三點處。

骨架屏入口

點擊生成骨架屏，將有彈窗提示是否允許插入骨架屏代碼。確定后將在當前頁面同級目錄下生成 page.skeleton.wxml 和 page.skeleton.wxss 兩個文件，分別為骨架屏代碼的模板和樣式。

骨架屏代碼通過小程序模板（template）的方式引入以 pages/index/index 頁面為例，引入方式如下。

<!-- pages/index/index.wxml 引入模板 -->
<import src="index.skeleton.wxml"/>
<template is="skeleton" wx:if="{{loading}}" data="{{}}"/>

/* pages/index/index.wxss 中引入樣式 */
@import "index.skeleton.wxss";

示例代碼：https://developers.weixin.qq.com/s/3AQoEBmh7XhF

# 顯示與隱藏

與普通的模板相同，通過 wx:if 控制顯示隱藏。

# 生成配置

可在 project.config.json 增加字段 skeletonConfig 進行骨架屏相關配置，頁面配置會覆蓋掉全局配置。

// project.config.json
{
  "skeletonConfig": {
    "global": {
      // 默認的全局配置
      "loading": "",
      "outline": {
        "remain": false,
        "replace": "none"
      },
      "text": {
        "color": "#EEEEEE"
      },
      "image": {
        "shape": "",
        "color": "#EFEFEF",
        "shapeOpposite": []
      },
      "button": {
        "color": "#EFEFEF",
        "excludes": []
      },
      "pseudo": {
        "color": "#EFEFEF",
        "shape": "circle",
        "shapeOpposite": []
      },
      "excludes": [],
      "remove": [],
      "empty": [],
      "hide": [],
      "grayBlock": [],
      "showNative": false,
      "backgroundColor": "transparent",
      "mode": "fullscreen",
      "templateName": "skeleton",
      "cssUnit": "rpx",
      "decimal": 4,
    },
    "pages": {
      "pages/index/index": {
        // 頁面配置，key 為頁頁面路徑
      }
    }
  }

具體配置如下。開發(fā)者可根據需要設置文字、圖片、按鈕的顏色和形狀，同時可根據 excludes、remove、hide等忽視或隱藏部分頁面元素，以獲取更優(yōu)的展示效果。

字段	類型	必填	默認值	說明
loading	String	No	spin	骨架屏顯示時的動畫:`spin` `chiaroscuro` `shine`
outline	Object	No		該配置接受一個 `remain` Boolean 字段，默認為 true ，表示保持邊框顏色，為 false 時，用 `replace` 字段替代 style.border
text	Object	No		該配置接受一個 `color` 字段，用于決定骨架頁面中文字塊的的顏色，顏色值支持 16 進制。
image	Object	No		該配置接受 3 個字段，`color`、`shape`、`shapeOpposite`。color 和 shape 用于確定骨架頁面中圖片塊的顏色和形狀，顏色值支持 16 進制，形狀支持兩個枚舉值，`circle` （圓形）和 `rect`（矩形）。shapeOpposite 字段接受一個數組，數組中每個元素是一個 DOM 選擇器，用于選擇 DOM 元素，被選擇 DOM 的形狀將和配置的 shape 形狀相反，例如，配置的是 `rect`那么，shapeOpposite 中的圖片塊將在骨架頁面中顯示成 circle 形狀（圓形）
button	Object	No		該配置接受兩個字段，`color` 和 `excludes`。color 用來確定骨架頁面中被視為按鈕塊的顏色，excludes 接受一個數組，數組中元素是 DOM 選擇器，用來選擇元素，該數組中的元素將不被視為按鈕塊。
pseudo	Object	No		該配置接受兩個字段，`color` 和 `shape`。color 用來確定骨架頁面中被視為偽元素塊的顏色，shape 用來設置偽元素塊的形狀，接受兩個枚舉值：circle 和 rect。
excludes	Array	No	`[]`	如果你有不需要進行骨架處理的元素，那么將該元素的 CSS 選擇器寫入該數組。
remove	Array	No	`[]`	不需要生成頁面骨架，且需要從 DOM 中移除的元素，配置值為移除元素的 CSS 選擇器。
hide	Array	No	`[]`	不需要移除，但是通過設置其透明度為 0，來隱藏該元素，配置值為隱藏元素的 CSS 選擇器。
empty	Array	No	`[]`	該數組中元素是 CSS 選擇器，被選擇的元素將被清空子元素
grayBlock	Array	No	`[]`	該數組中元素是 CSS 選擇器，被選擇的元素將被被插件處理成一個色塊，色塊的顏色和按鈕塊顏色一致。內部元素將不再做特殊處理，文字將隱藏
showNative	Boolean	No	false	顯示原生組件，為 `false` 時原生組件被處理為 view。
backgroundColor	String	No	transparent	骨架屏背景色
mode	String	No	fullscreen	默認為使用絕對定位占滿全屏。當對自定義組件使用，作為局部加載的樣式時，可設為 `auto`，高度隨內容撐開
templateName	String	No	skeleton	骨架屏模板的 name 值
cssUnit	String	No	rpx	支持的枚舉值：rpx, rem, vw, vh, vmin, vmax
decimal	Number	No	4	生成骨架頁面中 css 值保留的小數位數，默認值是 4

原生組件包括 camera, live-player, live-pusher, video, map, canvas, picker, input, textarea。

# 自定義屬性

有時我們需要讓骨架的某塊內容顯示特定的背景色，可以通過 data-skeleton-bgColor="#ff00000" 這樣的方式來指定。

在處理列表的時候，為了盡可能美觀，我們對列表進行了同化處理，后面的子項都是第一個子項的克隆。由于小程序的列表不是通過 ul/ol 標簽來聲明的，這里借助 data-* 屬性進行標示?？紤]到列表容器內可能插入其它結構，有如下兩種聲明方式：data-skeleton-list 的直接子節(jié)點將被處理成第一項的克??；data-skeleton-li 屬性相同的元素被認為是同一列表的子項。

<!-- 方式一：列表容器內容均為列表項 -->
<view wx:for="{{array}}" data-skeleton-list>
  <view class="list-item">子項內容</view>
</view>

<!-- 方式二：列表容器中插入了其它元素 -->
<view wx:for="{{array}}">
  <view class="other-block">其它</view>
  <view class="list-item" data-skeleton-li="goods">子項內容</view>
  <view class="list-item" data-skeleton-li="goods">子項內容</view>
  <view class="list-item" data-skeleton-li="goods">子項內容</view>
</view>

此外，頁面可能被劃分成不同的區(qū)域，通過不同的請求來獲取數據，它們的響應時間也不一致。骨架屏原本是一個整體，我們希望對其進行拆分，哪條請求返回了，就替換掉對應區(qū)域的骨架屏為真實內容，達到漸進式加載的效果。聲明 data-skeleton-hide 屬性的節(jié)點生成骨架屏時會被替換成 hidden 屬性，開發(fā)者可通過 data 控制其顯示/隱藏。需要注意的是，為了使真實數據的位置與骨架屏一致，此時應使用 absolute 方式定位頁面主模塊，詳情參考示例 demo。

<!-- 原 wxml 內容 -->
<view data-skeleton-hide="hideBlock1"></view>
<view data-skeleton-hide="hideBlock2"></view>

<!-- 骨架屏 wxml 內容 -->
<view hidden="{{hideBlock1}}"></view>
<view hidden="{{hideBlock2}}"></view>

# Tips

骨架屏僅包括頁面首屏中的可見區(qū)域，對于橫向滾動的 swiper 等容器，超出屏幕的子元素將被忽略；
骨架屏的布局復用開發(fā)者的頁面布局，需要骨架屏自適應頁面尺寸時，頁面布局應采用 rpx 等自適應方案；
部分組件如 movable-view、movable-area、rich-text、editor、picker、picker-view、picker-view-column、ad、officail-account和open-data 無法生成理想的骨架效果，可通過添加一個父容器，結合 grayBlock、empty 等配置，將其置灰。
請勿修改自動生成的骨架屏的代碼，當效果不理想時，建議調整相關配置，這樣當頁面變更時，仍可自動生成；
生成的骨架屏代碼中會包含預覽時的頁面數據，將被用來填充頁面；
骨架屏通常用于商品列表、新聞列表等頁面，對于動畫/原生組件較多的頁面展示效果不佳；
該能力除用于展示首屏骨架外，也可作為局部加載的 loading 樣式，可靈活使用；