微信小程序 API

API

小程序開發(fā)框架提供豐富的微信原生 API，可以方便的調(diào)起微信提供的能力，如獲取用戶信息，本地存儲(chǔ)，支付功能等。詳細(xì)介紹請(qǐng)參考 API 文檔。

通常，在小程序 API 有以下幾種類型：

事件監(jiān)聽 API

我們約定，以 on 開頭的 API 用來監(jiān)聽某個(gè)事件是否觸發(fā)，如：wx.onSocketOpen，wx.onCompassChange 等。

這類 API 接受一個(gè)回調(diào)函數(shù)作為參數(shù)，當(dāng)事件觸發(fā)時(shí)會(huì)調(diào)用這個(gè)回調(diào)函數(shù)，并將相關(guān)數(shù)據(jù)以參數(shù)形式傳入。

代碼示例

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

同步 API

我們約定，以 Sync 結(jié)尾的 API 都是同步 API， 如 wx.setStorageSync，wx.getSystemInfoSync 等。此外，也有一些其他的同步 API，如 wx.createWorker，wx.getBackgroundAudioManager 等，詳情參見 API 文檔中的說明。

同步 API 的執(zhí)行結(jié)果可以通過函數(shù)返回值直接獲取，如果執(zhí)行出錯(cuò)會(huì)拋出異常。

代碼示例

try {
  wx.setStorageSync('key', 'value')
} catch (e) {
  console.error(e)
}

異步 API

大多數(shù) API 都是異步 API，如 wx.request，wx.login 等。這類 API 接口通常都接受一個(gè) Object 類型的參數(shù)，這個(gè)參數(shù)都支持按需指定以下字段來接收接口調(diào)用結(jié)果：

Object 參數(shù)說明

回調(diào)函數(shù)的參數(shù)

success，fail，complete 函數(shù)調(diào)用時(shí)會(huì)傳入一個(gè) Object 類型參數(shù)，包含以下字段：

異步 API 的執(zhí)行結(jié)果需要通過 Object 類型的參數(shù)中傳入的對(duì)應(yīng)回調(diào)函數(shù)獲取。部分異步 API 也會(huì)有返回值，可以用來實(shí)現(xiàn)更豐富的功能，如 wx.request，wx.connectSocket 等。

代碼示例

wx.login({
  success(res) {
    console.log(res.code)
  }
})

異步 API 返回 Promise

基礎(chǔ)庫(kù) 2.10.2 版本起，異步 API 支持 callback & promise 兩種調(diào)用方式。當(dāng)接口參數(shù) Object 對(duì)象中不包含 success/fail/complete 時(shí)將默認(rèn)返回 promise，否則仍按回調(diào)方式執(zhí)行，無返回值。

注意事項(xiàng)

1. 部分接口如 downloadFile, request, uploadFile, connectSocket, createCamera（小游戲）本身就有返回值， 它們的 promisify 需要開發(fā)者自行封裝。
2. 當(dāng)沒有回調(diào)參數(shù)時(shí)，異步接口返回 promise。此時(shí)若函數(shù)調(diào)用失敗進(jìn)入 fail 邏輯， 會(huì)報(bào)錯(cuò)提示 Uncaught (in promise)，開發(fā)者可通過 catch 來進(jìn)行捕獲。
3. wx.onUnhandledRejection 可以監(jiān)聽未處理的 Promise 拒絕事件。

代碼示例

// callback 形式調(diào)用
wx.chooseImage({
  success(res) {
    console.log('res:', res)
  }
})

// promise 形式調(diào)用
wx.chooseImage().then(res => console.log('res: ', res))