# API 小程序開發框架提供豐富的微信原生 API，可以方便的調起微信提供的能力，如獲取用戶信息，本地存儲，支付功能等。詳細介紹請參考?[API 文檔](https://www.w3cschool.cn/weixinapp/hpm41q8p.html)。 通常，在小程序 API 有以下幾種類型： ## 事件監聽 API 我們約定，以?on?開頭的 API 用來監聽某個事件是否觸發，如：[wx.onSocketOpen](https://www.w3cschool.cn/weixinapp/weixinapp-network-socket.html)，[wx.onCompassChange](https://www.w3cschool.cn/weixinapp/weixinapp-api-campass.html)?等。 這類 API 接受一個回調函數作為參數，當事件觸發時會調用這個回調函數，并將相關數據以參數形式傳入。 代碼示例 ~~~ wx.onCompassChange(function (res) { console.log(res.direction) }) ~~~ ## 同步 API 我們約定，以?Sync?結尾的 API 都是同步 API， 如?[wx.setStorageSync](https://www.w3cschool.cn/weixinapp/weixinapp-apidate.html)，[wx.getSystemInfoSync](https://www.w3cschool.cn/weixinapp/weixinapp-device.html)?等。此外，也有一些其他的同步 API，如?[wx.createWorker](https://www.w3cschool.cn/weixinapp/weixinapp-eqvm2m8l.html)，[wx.getBackgroundAudioManager](https://www.w3cschool.cn/weixinapp/weixinapp-gxae38fm.html)?等，詳情參見 API 文檔中的說明。 同步 API 的執行結果可以通過函數返回值直接獲取，如果執行出錯會拋出異常。 代碼示例 ~~~ try { wx.setStorageSync('key', 'value') } catch (e) { console.error(e) } ~~~ ## 異步 API 大多數 API 都是異步 API，如?[wx.request](https://www.w3cschool.cn/weixinapp/weixinapp-network-request.html)，[wx.login](https://www.w3cschool.cn/weixinapp/weixinapp-api-login.html)?等。這類 API 接口通常都接受一個?Object?類型的參數，這個參數都支持按需指定以下字段來接收接口調用結果： Object 參數說明 | 參數名 | 類型 | 必填 | 說明 | | --- | --- | --- | --- | | success | function | 否 | 接口調用成功的回調函數 | | fail | function | 否 | 接口調用失敗的回調函數 | | complete | function | 否 | 接口調用結束的回調函數（調用成功、失敗都會執行） | | 其他 | Any | \- | 接口定義的其他參數 | 回調函數的參數 success，fail，complete?函數調用時會傳入一個?Object?類型參數，包含以下字段： | 屬性 | 類型 | 說明 | | --- | --- | --- | | errMsg | string | 錯誤信息，如果調用成功返回?`${apiName}:ok` | | errCode | number | 錯誤碼，僅部分 API 支持，具體含義請參考對應 API 文檔，成功時為?`0`。 | | 其他 | Any | 接口返回的其他數據 | 異步 API 的執行結果需要通過?Object?類型的參數中傳入的對應回調函數獲取。部分異步 API 也會有返回值，可以用來實現更豐富的功能，如?[wx.request](https://www.w3cschool.cn/weixinapp/weixinapp-network-request.html)，[wx.connectSocket](https://www.w3cschool.cn/weixinapp/weixinapp-network-socket.html)?等。 代碼示例 ~~~ wx.login({ success(res) { console.log(res.code) } }) ~~~ ## 異步 API 返回 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)) ~~~