快应用接口概述

2020-08-10 13:44 更新

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

同步

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

使用示例：

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

异步

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

使用回调函数
使用 Promise 1010+

使用回调函数

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

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

回调函数	参数名	类型	必填	说明
success	data	Any	调用结果，可以是任意类型，参见接口使用文档	在调用成功时回调
fail	data	Any	错误信息，一般是描述错误信息的字符串，也可以是其他类型，参见接口使用文档	在调用失败时回调
	code	Number	错误代码，如果文档未特别说明，会返回200。如果返回其他错误代码，需要在文档中列举说明	在调用失败时回调
cancel	data	Any	调用结果，一般无内容，参见接口使用文档	在用户取消时回调。部分需要用户交互的接口调用中可能提供此回调支持
complete	无	无	无	在调用完成时回调

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

参数名	类型	说明
callback	Function	回调，每次订阅的对象变化时，都会被执行
fail	Function	失败回调，返回错误信息和错误代码。若文档未特别说明，错误代码为 200。若返回其他错误代码，参见具体的接口文档

使用接口的注意事项

接口为只读，不可覆盖

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

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

显示中（用户正在阅读的页面）：this.$valid && this.$visible
已隐藏（加载新页，导致页面被隐藏）：this.$valid && !this.$visible
已销毁（退出当前页面，页面被销毁）：!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}`)
      }
    })
  }
}

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

权限控制

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

常见错误代码

代码	含义
200	一般性错误
201	用户拒绝
202	参数非法
203	服务不可用
204	请求超时

以上内容是否对您有帮助：

快应用 接口概述

同步

使用示例：

异步

使用回调函数

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

使用示例：

使用 Promise

示例：

订阅

使用接口的注意事项

接口为只读，不可覆盖

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

示例：

取消无意义的订阅

权限控制

常见错误代码

快应用接口概述