微信公眾號裡的網頁之所以能拍照、定位、分享、支付,靠的就是 JS-SDK。以下把整個接入流程與常用介面依序整理出來,方便查閱。(本文以 jweixin-1.0.0 版為例,實際開發請以微信官方最新文件為準。)
在需要呼叫 JS 介面的頁面加入:
https://res.wx.qq.com/open/js/jweixin-1.0.0.js
支援 https,也支援 AMD/CMD 標準模組載入方式。
所有使用 JS-SDK 的頁面都必須先注入設定,否則後續介面一律無法呼叫。同一個 URL 只需注入一次;若為 URL 會變動的 SPA,則需在每次路由變化時重新注入。
wx.config({
debug: true, // 開啟除錯模式,所有 api 回傳值會以 alert 顯示;參數則透過 log 印出(僅 PC 端)
appId: '', // 必填,公眾號唯一標識
timestamp: , // 必填,產生簽名的時間戳
nonceStr: '', // 必填,產生簽名的隨機字串
signature: '', // 必填,簽名(見附錄 1)
jsApiList: [] // 必填,要使用的 JS 介面清單(見附錄 2)
});
wx.ready(function () {
// config 驗證通過後執行。所有介面呼叫都必須在 config 取得結果之後,
// 因此頁面載入時就要執行的行為請放在這裡;
// 若是使用者操作才觸發的,直接呼叫即可。
});
wx.error(function (res) {
// 驗證失敗會進到這裡,例如簽名過期。可開 debug 模式或看 res 參數找出原因,
// SPA 可在這裡重新取簽名。
});
所有介面都透過 wx(或 jWeixin)物件呼叫,除各自的參數外,共通回呼有:
success:呼叫成功fail:呼叫失敗complete:不論成功或失敗都會執行cancel:使用者按下取消(僅部分有取消動作的 api)trigger:監聽選單按鈕點擊(僅 Menu 類介面)以上回呼都帶一個物件參數,除了介面自身回傳的資料,還有一個通用屬性 errMsg:
"xxx:ok""xxx:cancel"// 判斷當前客戶端是否支援指定介面
wx.checkJsApi({
jsApiList: ['chooseImage'],
success: function (res) {
// 以鍵值對回傳,可用為 true,不可用為 false
// 例:{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}
}
});
// 自訂「分享到朋友圈」
wx.onMenuShareTimeline({
title: '', link: '', imgUrl: '',
success: function () { /* 使用者確認分享 */ },
cancel: function () { /* 使用者取消分享 */ }
});
// 自訂「分享給朋友」
wx.onMenuShareAppMessage({
title: '', desc: '', link: '', imgUrl: '',
type: '', // music、video 或 link,預設 link
dataUrl: '', // type 為 music/video 時需提供的資料連結
success: function () {}, cancel: function () {}
});
// 自訂「分享到 QQ」
wx.onMenuShareQQ({ title: '', desc: '', link: '', imgUrl: '' });
// 自訂「分享到騰訊微博」
wx.onMenuShareWeibo({ title: '', desc: '', link: '', imgUrl: '' });
// 拍照或從相冊選圖
wx.chooseImage({
success: function (res) {
var localIds = res.localIds; // 本地 ID 清單,可直接作為 img 的 src
}
});
// 預覽圖片
wx.previewImage({ current: '', urls: [] });
// 上傳圖片
wx.uploadImage({
localId: '', // 由 chooseImage 取得
isShowProgressTips: 1, // 預設 1,顯示進度提示
success: function (res) {
var serverId = res.serverId; // 伺服器端 ID,即 media_id
}
});
// 下載圖片
wx.downloadImage({
serverId: '', // 由 uploadImage 取得
isShowProgressTips: 1,
success: function (res) {
var localId = res.localId;
}
});
備註:上傳後取得的 serverId 就是 media_id,可利用微信「下載多媒體檔案」介面取回檔案。
wx.startRecord(); // 開始錄音
wx.stopRecord({ // 停止錄音
success: function (res) { var localId = res.localId; }
});
wx.onVoiceRecordEnd({ // 錄音超過一分鐘自動停止
complete: function (res) { var localId = res.localId; }
});
wx.playVoice({ localId: '' }); // 播放
wx.pauseVoice({ localId: '' }); // 暫停
wx.stopVoice({ localId: '' }); // 停止
wx.onVoicePlayEnd({ // 播放完畢
success: function (res) { var localId = res.localId; }
});
wx.uploadVoice({ // 上傳語音
localId: '',
isShowProgressTips: 1,
success: function (res) { var serverId = res.serverId; }
});
wx.downloadVoice({ // 下載語音
serverId: '',
isShowProgressTips: 1,
success: function (res) { var localId = res.localId; }
});
// 語音識別
wx.translateVoice({
localId: '',
isShowProgressTips: 1,
success: function (res) { alert(res.translateResult); }
});
// 取得網路狀態,回傳 2g/3g/4g/wifi
wx.getNetworkType({
success: function (res) { var networkType = res.networkType; }
});
// 開啟微信內建地圖
wx.openLocation({
latitude: 0, longitude: 0,
name: '', address: '',
scale: 1, // 縮放級別 1~28
infoUrl: '' // 底部可點擊的超連結
});
// 取得當前座標
wx.getLocation({
timestamp: 0, nonceStr: '', addrSign: '', // 僅需相容 6.0.2 之前的版本時提供
success: function (res) {
var longitude = res.longitude;
var latitude = res.latitude;
var speed = res.speed; // 公尺/秒
var accuracy = res.accuracy; // 位置精度
}
});
wx.hideOptionMenu(); // 隱藏右上角選單
wx.showOptionMenu(); // 顯示右上角選單
wx.closeWindow(); // 關閉目前網頁
wx.hideAllNonBaseMenuItem(); // 隱藏所有非基礎按鈕
wx.showAllNonBaseMenuItem(); // 顯示所有功能按鈕
wx.hideMenuItems({ menuList: [] }); // 批量隱藏
wx.showMenuItems({ menuList: [] }); // 批量顯示
wx.scanQRCode({
needResult: 0, // 0 由微信處理結果,1 直接回傳
scanType: ["qrCode", "barCode"], // 可指定只掃 QR 或條碼
success: function (res) {
var result = res.resultStr; // needResult 為 1 時才有值
}
});
wx.editAddress({ /* 編輯收貨地址 */ });
wx.getLatestAddress({
success: function (res) {
var userName = res.userName; // 收貨人
var telNumber = res.telNumber; // 電話
var postalCode = res.postalCode; // 郵編
var provinceName = res.provinceName;
var cityName = res.cityName;
var countryName = res.countryName;
var address = res.address; // 詳細地址
var nationalCode = res.nationalCode; // 國家碼
}
});
// 跳轉商品頁
wx.openProductSpecificView({
productId: '',
viewType: '' // 0 普通詳情頁、1 掃一掃詳情頁、2 小店詳情頁
});
// 選取門店卡券
wx.chooseCard({
shopId: '', cardType: '', cardId: '',
timeStamp: 0, nonceStr: '', cardSign: '',
success: function (res) { var cardList = res.cardList; }
});
// 批量添加卡券
wx.addCard({
cardList: [{ cardId: '', cardExt: '' }],
success: function (res) { var cardList = res.cardList; }
});
// 打開卡包中的卡券
wx.openCard({ cardList: [{ cardId: '', code: '' }] });
// 發起支付
wx.chooseWXPay({
timestamp: 0, noncestr: '', package: '', paySign: ''
});
實際踩坑時,最常見的失敗原因不是程式寫錯,而是簽名對不上。簽名依賴 jsapi_ticket,而 ticket 有每日取用次數上限且會過期,務必在伺服器端做快取,不要每次請求都重新向微信換取。另外 timestamp 與 nonceStr 必須和計算簽名時用的值完全一致,字串排序與編碼方式也要照官方範例,否則一律回 invalid signature。
还有一点:微信已多次調整與下線部分介面(例如分享到 QQ、騰訊微博在近期版本已不建議使用)。上線前請務必對照官方最新介面清單,並善用 wx.checkJsApi 做能力偵測,避免在低版本客戶端直接報錯。