快應(yīng)用 接口概述

使用方法：

只有在調(diào)用異步接口的實參中不傳遞任何回調(diào)函數(shù)時，才會返回一個 ?Promise ?實例

若在調(diào)用異步接口的實參中，某個屬性（如：success）的值為函數(shù)，則調(diào)用異步接口的返回值為 undefined，切換至上面介紹的?使用回調(diào)函數(shù)?模式

因此，在框架中不能同時使用回調(diào)函數(shù)和使用Promise

在 ?Promise ?實例的 ?then ?方法中，可傳入兩個參數(shù)：

• 第一個參數(shù)為 ?resolve?（成功）的回調(diào)函數(shù)，對應(yīng)異步接口支持的回調(diào)函數(shù)中的?success ?和 ?callback?。參數(shù)的 data 屬性為返回的數(shù)據(jù)
• 第二個參數(shù)為 ?reject?（失?。┑幕卣{(diào)函數(shù)，對應(yīng)異步接口支持的回調(diào)函數(shù)中的 ?cancel ?或 ?fail?。失敗的回調(diào)函數(shù)的參數(shù)比成功的回調(diào)函數(shù)多一個 code 屬性，用于判斷具體狀態(tài)。若 code 為 100，對應(yīng) cancel；若 code 大于或等于 200，對應(yīng) fail

示例：

const promise = prompt.showContextMenu({
  itemList: ['item1', 'item2'],
  itemColor: '#ff33ff'
})
promise.then(
  res => {
    console.log(`異步接口返回的數(shù)據(jù)：${res.data}`)
  },
  res => {
    console.log(`異步接口返回的數(shù)據(jù)：${res.data}`)
    console.log(`異步接口返回的狀態(tài)碼：${res.code}`)
    if (res.code === 100) {
      // 對應(yīng)異步接口支持的回調(diào)函數(shù)中的cancel
    } else if (res.code >= 200) {
      // 對應(yīng)異步接口支持的回調(diào)函數(shù)中的fail
    }
  }
)

訂閱

訂閱接口不會立即返回調(diào)用結(jié)果，開發(fā)者需要在實參中傳遞相應(yīng)的回調(diào)函數(shù)；回調(diào)函數(shù)會在接口任務(wù)完成時執(zhí)行回調(diào)；由于是訂閱類型，回調(diào)函數(shù)可能執(zhí)行多次

訂閱接口支持的回調(diào)函數(shù)：

以監(jiān)聽地理位置（geolocation.subscribe）為例：

• 調(diào)用 geolocation.subscribe 監(jiān)聽地理位置的改變，則每次地理位置發(fā)生改變，都會調(diào)用傳入的 callback 回調(diào)，返回新的位置信息
• 若用戶拒絕授予權(quán)限，會調(diào)用 fail 回調(diào)函數(shù)并結(jié)束接口調(diào)用，callback 回調(diào)函數(shù)永遠(yuǎn)不會被調(diào)用

示例：

geolocation.subscribe({
  callback: function(data) {
    console.log(
      `handling success: longitude = ${data.longitude}, latitude = ${
        data.latitude
      }`
    )
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})

使用接口的注意事項

接口為只讀，不可覆蓋

執(zhí)行回調(diào)函數(shù)時判斷頁面狀態(tài)

由于異步和訂閱接口不會在調(diào)用后立即返回結(jié)果，而是一段時間后執(zhí)行回調(diào)函數(shù)并攜帶返回結(jié)果作為參數(shù)；因此，執(zhí)行回調(diào)函數(shù)時，調(diào)用接口的頁面，會屬于以下三種狀態(tài)之一：

1. 顯示中（用戶正在閱讀的頁面）：this.$valid && this.$visible
2. 已隱藏（加載新頁，導(dǎo)致頁面被隱藏）：this.$valid && !this.$visible
3. 已銷毀（退出當(dāng)前頁面，頁面被銷毀）：!this.$valid && !this.$visible

若執(zhí)行回調(diào)函數(shù)時，調(diào)用接口的頁面已隱藏或已銷毀，則存在以下問題：

• 若頁面已隱藏，在回調(diào)函數(shù)中更新 ViewModel 中的數(shù)據(jù)，會驅(qū)動頁面視圖更新，無意義的降低性能；建議在回調(diào)函數(shù)中緩存數(shù)據(jù)，當(dāng)頁面再次進(jìn)入顯示狀態(tài)時，再更新 ViewModel 中的數(shù)據(jù)
• 若頁面已銷毀，頁面中的 ViewModel 也會銷毀，在回調(diào)函數(shù)中更新 ViewModel 中的數(shù)據(jù)可能會引起報錯；建議在回調(diào)函數(shù)中先判斷頁面狀態(tài)，若頁面已被銷毀，則直接退出

提示：關(guān)于頁面狀態(tài)$valid、$visible，參見 script 腳本

示例：

geolocation.getLocation({
  success: function(data) {
    if (this.$valid && this.$visible) {
      // 頁面仍在顯示中
    } else if (this.$valid && !this.$visible) {
      // 頁面已隱藏
    } else {
      // 頁面已銷毀
    }
  }.bind(this),
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})

取消無意義的訂閱

訂閱接口的回調(diào)函數(shù)可能會被多次調(diào)用。若頁面已隱藏或已銷毀，仍繼續(xù)訂閱，既會影響框架的響應(yīng)速度，也會造成內(nèi)存泄露。因此，建議在頁面被銷毀后取消訂閱

在頁面銷毀后取消訂閱有以下兩種方式：

• 方式一：在頁面生命周期 onDestroy 中取消訂閱
• 方式二：在訂閱接口的回調(diào)函數(shù)中，先判斷頁面狀態(tài)，若頁面已被銷毀，取消訂閱

示例：

export default {
  onDestroy() {
    // 方式一：在頁面生命周期onDestroy中取消訂閱
    geolocation.unsubscribe()
  },
  onReady() {
    // 訂閱，監(jiān)聽地理位置
    geolocation.subscribe({
      callback: function(data) {
        // 方式二：在訂閱接口的回調(diào)函數(shù)中，先判斷頁面狀態(tài)，若頁面已被銷毀，取消訂閱
        if (!this.$valid) {
          geolocation.unsubscribe()
        }
        console.log(
          `handling success: longitude = ${data.longitude}, latitude = ${
            data.latitude
          }`
        )
      }.bind(this),
      fail: function(data, code) {
        console.log(`handling fail, code = ${code}`)
      }
    })
  }
}

注：若在應(yīng)用生命周期中調(diào)用訂閱接口，只要應(yīng)用仍然在運行，訂閱都是有效的；建議當(dāng)不再需要訂閱時，主動取消訂閱

權(quán)限控制

部分接口因為涉及到安全和隱私問題，增加了權(quán)限控制，調(diào)用時會出現(xiàn)用戶授權(quán)彈窗，待用戶授權(quán)后才能繼續(xù)執(zhí)行。 權(quán)限控制有兩種模式，一種是每次調(diào)用都需要授權(quán)，一種是授權(quán)后記住保存狀態(tài)，下次調(diào)用不再需要重復(fù)授權(quán)。

常見錯誤代碼