DIV CSS 佈局教程網

WeixinJSBridge API 使用整理(微信內 H5 頁面)
編輯:關於JavaScript     

請注意:以下 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(跳轉指定公眾號)、openSpecificView
  • 分享:shareWeibo、shareFB、sendAppMessage、shareTimeline、timelineCheckIn(朋友圈簽到)
  • 掃碼:scanQRCode
  • 介面控制:hideOptionMenu / showOptionMenu(右上角按鈕)、hideToolbar / showToolbar(底部導航欄)、setPageState、closeWindow
  • 網路與環境:getNetworkType、geoLocation、getInstallState
  • 地理位置:openLocation(開啟地圖查看位置,參數含 latitude、longitude、name、address、scale、infoUrl)
  • 支付:getBrandWCPayRequest(公眾號支付)、getBrandIAPPayRequest(IAP)、getCanIAPPay、getBrandWCPayCreateCreditCardRequest(開通信用卡)
  • 收貨地址:editAddress(編輯)、getLatestAddress(取得最近使用)
  • 表情:addEmoticon、cancelAddEmoticon、hasEmoticon
  • 其他:sendEmail、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 安全域名,未在清單中的網域無法使用。

基本的 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 接口安全域名的設定。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved