4.小程序API

API分类

  1. 事件监听 API

  2. 同步 API

  3. 异步 API

  4. 异步 API 返回 Promise

事件监听 API

我们约定，以 on 开头的 API 用来监听某个事件是否触发，如：wx.onSocketOpen，wx.onCompassChange 等。

这类 API 接受一个回调函数作为参数，当事件触发时会调用这个回调函数，并将相关数据以参数形式传入。

代码示例

wx.onCompassChange(function (res) {
  console.log(res.direction)
})

### 同步 API

同步API通常以sync结尾，但是也有特例：wx.createWorker、wx.getBackgroundAudioManager这俩也是同步的，作用后面用到再学。

异步 API

异步API，大多数接口都是异步API，会返回一个object：

Object 参数说明

参数名类型必填说明
successfunction否接口调用成功的回调函数
failfunction否接口调用失败的回调函数
completefunction否接口调用结束的回调函数（调用成功、失败都会执行）
其他Any-接口定义的其他参数

可以看到success，fail，complete 是三个函数，主要用于回调。

回调函数的参数

success，fail，complete 函数调用时会传入一个 Object 类型参数，包含以下字段：

属性类型说明
errMsgstring错误信息，如果调用成功返回 ${apiName}:ok
errCodenumber错误码，仅部分 API 支持，具体含义请参考对应 API 文档，成功时为 0。
其他Any接口返回的其他数据

异步 API 返回 Promise

最后一种promise的，基础库 2.10.2 版本起，异步 API 支持 callback & promise 两种调用方式。当接口参数 Object 对象中不包含 success/fail/complete 时将默认返回 promise，否则仍按回调方式执行，无返回值。

注意事项
  1. 部分接口如 downloadFile, request, uploadFile, connectSocket, createCamera（小游戏）本身就有返回值， 它们的 promisify 需要开发者自行封装。
  2. 当没有回调参数时，异步接口返回 promise。此时若函数调用失败进入 fail 逻辑， 会报错提示 Uncaught (in promise)，开发者可通过 catch 来进行捕获。
  3. wx.onUnhandledRejection 可以监听未处理的 Promise 拒绝事件。

代码示例

// callback 形式调用
wx.chooseImage({
  success(res) {
    console.log('res:', res)
  }
})

// promise 形式调用
wx.chooseImage().then(res => console.log('res: ', res))

Q.E.D.