快应用 接口概述

接口方法有同步、异步、回调、异步回调四种类型，不同类型的接口方法，提供的能力也不相同。

同步

同步接口会直接返回调用结果，结果可以是任意类型，参见相关的接口文档。

使用示例：

console.log(JSON.stringify(app.getInfo()))

异步

异步接口不会立即返回调用结果，在异步接口任务完成后执行某些操作，可选择以下方式之一：

• 使用回调函数
• 使用 Promise 1010+

使用回调函数

开发者可以在调用异步接口的实参中传递相应的回调函数；回调函数会在接口任务完成时根据状态执行回调。任意回调函数最多执行一次

异步接口支持的回调函数有：

success、fail和cancel三个回调函数是互斥的，每次接口调用都会且仅会调用这三个回调函数中的一个，之后会再调用一次complete回调。

使用示例：

prompt.showContextMenu({
  itemList: ['item1', 'item2'],
  itemColor: '#ff33ff',
  success: function(data) {
    console.log("handling callback");
  },
  fail: function(data, code) {
    console.log("handling fail, code=" + code);
  },
  cancel: function(data) {
    console.log("handling cancel");
  },
  complete: function() {
    console.log("handling complete");
  },
})

使用 Promise

支持调用异步接口返回 ​Promise​ 实例，开发者可以在返回的 ​Promise​ 实例上使用 ​then​, ​catch​ 方法绑定回调函数

​Promise ​实例的状态是 resolve（成功）还是 reject（失败），依赖于异步接口任务执行的结果。若任务成功，则 ​Promise ​实例的状态为 ​resolve​；否则，​Promise​实例的状态为 ​reject​

使用方法：

只有在调用异步接口的实参中不传递任何回调函数时，才会返回一个 ​Promise ​实例

若在调用异步接口的实参中，某个属性（如：success）的值为函数，则调用异步接口的返回值为 undefined，切换至上面介绍的​使用回调函数​模式

因此，在框架中不能同时使用回调函数和使用Promise

在 ​Promise ​实例的 ​then ​方法中，可传入两个参数：

• 第一个参数为 ​resolve​（成功）的回调函数，对应异步接口支持的回调函数中的​success ​和 ​callback​。参数的 data 属性为返回的数据
• 第二个参数为 ​reject​（失败）的回调函数，对应异步接口支持的回调函数中的 ​cancel ​或 ​fail​。失败的回调函数的参数比成功的回调函数多一个 code 属性，用于判断具体状态。若 code 为 100，对应 cancel；若 code 大于或等于 200，对应 fail

示例：

const promise = prompt.showContextMenu({
  itemList: ['item1', 'item2'],
  itemColor: '#ff33ff'
})
promise.then(
  res => {
    console.log(`异步接口返回的数据：${res.data}`)
  },
  res => {
    console.log(`异步接口返回的数据：${res.data}`)
    console.log(`异步接口返回的状态码：${res.code}`)
    if (res.code === 100) {
      // 对应异步接口支持的回调函数中的cancel
    } else if (res.code >= 200) {
      // 对应异步接口支持的回调函数中的fail
    }
  }
)

订阅

订阅接口不会立即返回调用结果，开发者需要在实参中传递相应的回调函数；回调函数会在接口任务完成时执行回调；由于是订阅类型，回调函数可能执行多次

订阅接口支持的回调函数：

以监听地理位置（geolocation.subscribe）为例：

• 调用 geolocation.subscribe 监听地理位置的改变，则每次地理位置发生改变，都会调用传入的 callback 回调，返回新的位置信息
• 若用户拒绝授予权限，会调用 fail 回调函数并结束接口调用，callback 回调函数永远不会被调用

示例：

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}`)
  }
})

使用接口的注意事项

接口为只读，不可覆盖

执行回调函数时判断页面状态

由于异步和订阅接口不会在调用后立即返回结果，而是一段时间后执行回调函数并携带返回结果作为参数；因此，执行回调函数时，调用接口的页面，会属于以下三种状态之一：

1. 显示中（用户正在阅读的页面）：this.$valid && this.$visible
2. 已隐藏（加载新页，导致页面被隐藏）：this.$valid && !this.$visible
3. 已销毁（退出当前页面，页面被销毁）：!this.$valid && !this.$visible

若执行回调函数时，调用接口的页面已隐藏或已销毁，则存在以下问题：

• 若页面已隐藏，在回调函数中更新 ViewModel 中的数据，会驱动页面视图更新，无意义的降低性能；建议在回调函数中缓存数据，当页面再次进入显示状态时，再更新 ViewModel 中的数据
• 若页面已销毁，页面中的 ViewModel 也会销毁，在回调函数中更新 ViewModel 中的数据可能会引起报错；建议在回调函数中先判断页面状态，若页面已被销毁，则直接退出

提示：关于页面状态$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}`)
  }
})

取消无意义的订阅

订阅接口的回调函数可能会被多次调用。若页面已隐藏或已销毁，仍继续订阅，既会影响框架的响应速度，也会造成内存泄露。因此，建议在页面被销毁后取消订阅

在页面销毁后取消订阅有以下两种方式：

• 方式一：在页面生命周期 onDestroy 中取消订阅
• 方式二：在订阅接口的回调函数中，先判断页面状态，若页面已被销毁，取消订阅

示例：

export default {
  onDestroy() {
    // 方式一：在页面生命周期onDestroy中取消订阅
    geolocation.unsubscribe()
  },
  onReady() {
    // 订阅，监听地理位置
    geolocation.subscribe({
      callback: function(data) {
        // 方式二：在订阅接口的回调函数中，先判断页面状态，若页面已被销毁，取消订阅
        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}`)
      }
    })
  }
}

注：若在应用生命周期中调用订阅接口，只要应用仍然在运行，订阅都是有效的；建议当不再需要订阅时，主动取消订阅

权限控制

部分接口因为涉及到安全和隐私问题，增加了权限控制，调用时会出现用户授权弹窗，待用户授权后才能继续执行。 权限控制有两种模式，一种是每次调用都需要授权，一种是授权后记住保存状态，下次调用不再需要重复授权。

常见错误代码