# API

小程序开发框架提供丰富的原生 API，可以方便的调起App提供的能力，如获取用户信息，本地存储，定位功能等。详细介绍请参考 API 文档。通常，在小程序 API 有以下几种类型：

# 事件监听 API

我们约定，以 on 开头的 API 用来监听某个事件是否触发，如：wx.onLocationChange 等。这类 API 接受一个回调函数作为参数，当事件触发时会调用这个回调函数，并将相关数据以参数形式传入。

# 代码示例

wx.onLocationChange((data) =>{
  console.log(data)
})

# 同步 API

我们约定，以 Sync 结尾的 API 都是同步 API，如 wx.setStorageSync，wx.getSystemInfoSync 等。此外，也有一些其他的同步 API，如 wx.createAnimation等，详情参见 API 文档中的说明。

# 代码示例

setStorageSync("key","value")
const res = getStorageSync("key")

# 异步 API

大多数 API 都是异步 API，如 wx.getLocation，wx.getStorage 等。这类 API 接口通常都接受一个 Object 类型的参数，这个参数都支持按需指定以下字段来接收接口调用结果：

# Object 参数说明

属性	类型	默认值	必填	说明
success	function	无	否	接口调用成功的回调函数
fail	function	无	否	接口调用失败的回调函数
complete	function	无	否	接口调用结束的回调函数（调用成功、失败都会执行）
其他	Any	无	否	接口调用结束的回调函数（调用成功、失败都会执行）

# 回调函数的参数

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

属性	类型	说明
errMsg	string	错误信息，如果调用成功返回 ${apiName}:ok
其他	any	接口返回的其他数据

异步 API 的执行结果需要通过 Object 类型的参数中传入的对应回调函数获取。部分异步 API 也会有返回值，可以用来实现更丰富的功能，如 wx.uploadFile等。

# 代码示例

const task = wx.uploadFile({
  filePath: "Lightresource://xxxx",
  success: (data) =>{
    console.log(data)
  }
})

# 异步 API 返回 Promise

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

# 注意事项

1.部分接口如 downloadFile, request, uploadFile本身就有返回值，它们的 promisify 需要开发者自行封装。

2.当没有回调参数时，异步接口返回 promise。此时若函数调用失败进入 fail 逻辑，会输出错误信息，开发者可通过 catch 来获取错误信息。

# 代码示例

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

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

// promise 形式调用2
try {
  const res = await wx.chooseImage()
  console.log('res: ', res)
} catch (e) {
  console.error('error', JSON.stringify(e))
}