請注意:以下 API 僅能在微信客戶端內測試,電腦瀏覽器開啟不會有任何反應。
WeixinJSBridge 是微信客戶端注入到網頁中的橋接物件,讓 H5 頁面能呼叫原生的能力:分享、掃碼、支付、取地理位置、開啟其他 App 等。本文整理它的基本用法與可呼叫的介面清單,並在最後說明它與現行「微信 JS-SDK」的關係。
WeixinJSBridge 是 asynchronously 注入的,頁面載入時可能還不存在,因此必須等 WeixinJSBridgeReady 事件觸發後才能呼叫:
function onBridgeReady() {
// 這裡才能安全地使用 WeixinJSBridge
}
if (typeof WeixinJSBridge === "undefined") {
if (document.addEventListener) {
document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
}
} else {
onBridgeReady(); // 已經存在就直接執行
}
WeixinJSBridge 有 on(監聽)與 invoke(呼叫)兩個主要方法,兩者常成對出現。
WeixinJSBridge.on('menu:share:appmessage', function (argv) {
WeixinJSBridge.invoke('sendAppMessage', {
"link": "https://m.exmail.qq.com/",
"desc": "描述文字",
"title": "分享標題"
}, function (res) {
WeixinJSBridge.log(res.err_msg);
});
});
WeixinJSBridge.on('menu:share:timeline', function (argv) {
WeixinJSBridge.invoke("shareTimeline", {
"link": "https://m.exmail.qq.com",
"img_url": "https://example.com/logo.png",
"img_width": "172",
"img_height":"40",
"desc": "描述",
"title": "標題"
}, function (e) {
alert(e.err_msg);
});
});
以下依功能分類整理 invoke 的第一個參數(介面名稱):
imagePreview(預覽圖片,可傳 urls 陣列與 current 指定目前顯示的圖)profile(查看 profile)、addContact(加入聯絡人)、jumpToBizProfile(跳轉指定公眾號)、openSpecificViewshareWeibo、shareFB、sendAppMessage、shareTimeline、timelineCheckIn(朋友圈簽到)scanQRCodehideOptionMenu / showOptionMenu(右上角按鈕)、hideToolbar / showToolbar(底部導航欄)、setPageState、closeWindowgetNetworkType、geoLocation、getInstallStateopenLocation(開啟地圖查看位置,參數含 latitude、longitude、name、address、scale、infoUrl)getBrandWCPayRequest(公眾號支付)、getBrandIAPPayRequest(IAP)、getCanIAPPay、getBrandWCPayCreateCreditCardRequest(開通信用卡)editAddress(編輯)、getLatestAddress(取得最近使用)addEmoticon、cancelAddEmoticon、hasEmoticonsendEmail、openUrlByExtBrowser(用系統瀏覽器開啟)、launch3rdApp、jumpWCMall、openProductView
document.getElementById("getBrandWCPayRequest").addEventListener("click", function () {
WeixinJSBridge.invoke("getBrandWCPayRequest", {
"appId": "wx8888888888888888", // 商戶 appid
"timeStamp": "189026618", // 時間戳
"nonceStr": "adssdasssd13d", // 隨機字串
"package": "prepay_id=wx201410272009395522657a690389285100", // 由後端下單取得
"signType": "SHA1", // 簽名方式
"paySign": "b737015b5b1eabe5db580945a07eac08c7bb55f8" // 支付簽名
}, function (res) {
if (res.err_msg === "get_brand_wcpay_request:ok") {
alert("支付成功");
} else {
alert("支付取消或失敗:" + res.err_msg);
}
});
}, false);
這些參數必須由伺服器端產生。package 中的 prepay_id 來自微信的統一收單介面,paySign 則需要用商戶金鑰對參數做簽名。金鑰絕對不能寫在前端 JavaScript 裡,否則任何人都能偽造支付請求。
1. 事件綁定用 addEventListener。原範例中大量使用 element.addEventListener("click", fn, !1),第三個參數 !1 就是 false,表示在冒泡階段處理。這段寫法本身沒問題,但為了可讀性建議直接寫 false。
2. 檢查 err_msg 而非只看有沒有回呼。每個 invoke 的回呼都會帶 err_msg,支付與分享一定要判斷它是否為 xxx:ok,否則使用者取消時也會被當成成功。
3. WeixinJSBridge 已被 JS-SDK 取代。這個物件是微信早期(2013 年前後)提供的低階介面,功能有限、無權限管控、也不必搭配簽名驗證。現行的官方方案是微信 JS-SDK,特色包括:
jsapi_ticket 並計算 signature,透過 wx.config() 注入權限。wx.ready() 取代 WeixinJSBridgeReady 事件。wx.chooseImage()、wx.previewImage()、wx.scanQRCode()、wx.getLocation()、wx.chooseWXPay() 等具名 API 取代 invoke 的字串介面名。基本的 JS-SDK 用法長這樣:
wx.config({
debug: false,
appId: 'wx8888888888888888',
timestamp: 1414587457,
nonceStr: 'randomstring',
signature: '由後端計算的簽名',
jsApiList: ['scanQRCode', 'chooseImage', 'previewImage', 'getLocation']
});
wx.ready(function () {
document.getElementById('scan').addEventListener('click', function () {
wx.scanQRCode({
needResult: 1,
success: function (res) { console.log('掃描結果:' + res.resultStr); }
});
});
});
wx.error(function (res) {
console.error('JS-SDK 初始化失敗', res);
});
4. 分享內容的控制權已轉移。早期用 menu:share:appmessage 可以自訂分享標題與圖片,但微信後續改版後,分享內容改以頁面中的 JS-SDK 設定為準,未設定時則抓取頁面本身的 title 與描述。因此新專案請直接走 JS-SDK 的 updateAppMessageShareData / updateTimelineShareData。
總結:WeixinJSBridge 這套 API 只有歷史參考價值。若你要在微信中做 H5,請直接查閱微信官方文件的 JS-SDK 章節,並確認你的域名已完成 JS 接口安全域名的設定。