微信早期的 WebView 除了分享,還開放了一大批原生能力給網頁呼叫:預覽圖片、掃描 QR Code、取得網路狀態、查看地圖位置、發起支付、編輯收貨地址、甚至下載表情。這些全部透過 WeixinJSBridge.invoke() 呼叫。本文把它們依功能分類整理,並標出哪些需要後端配合。
前提:請在微信內測試。這些接口在電腦瀏覽器或其他 App 的 WebView 裡全部是 undefined。
// 發送給好友
WeixinJSBridge.invoke('sendAppMessage', {
"link": "https://example.com", "desc": "描述", "title": "標題"
}, function (res) { WeixinJSBridge.log(res.err_msg); });
// 分享到朋友圈
WeixinJSBridge.invoke('shareTimeline', {
"link": "https://example.com",
"img_url": "https://example.com/thumb.png",
"img_width": "172", "img_height": "40",
"desc": "描述", "title": "標題"
}, function (e) { alert(e.err_msg); });
// 分享到微博
WeixinJSBridge.invoke('shareWeibo', {
"type": "link", "link": "https://example.com"
}, function (e) { alert(e.err_msg); });
// 分享到 Facebook
WeixinJSBridge.invoke('shareFB', { "link": "https://example.com" });
document.getElementById("imagePreview").addEventListener("click", function () {
WeixinJSBridge.invoke("imagePreview", {
"urls": [
"https://example.com/1.png",
"https://example.com/2.png",
"https://example.com/3.png"
],
"current": "https://example.com/2.png" // 起 initially 顯示第幾張
});
}, false);
urls 是整組圖片,current 指定初始顯示的那張——這個設計讓使用者可以在預覽模式裡左右滑動瀏覽全部。
// 加入聯絡人/關注
WeixinJSBridge.invoke("addContact", { "webtype": "1", "username": "gh_xxxxxxxxxxxx" },
function (e) { alert(e.err_msg); });
// 查看 profile
WeixinJSBridge.invoke("profile", { "username": "gh_xxxxxxxxxxxx", "nickname": "某公眾號" });
// 跳轉到指定公眾號頁面
WeixinJSBridge.invoke("jumpToBizProfile", { "tousername": "gh_xxxxxxxxxxxx" },
function (e) { alert(e.err_msg); });
// 用微信團隊的 webview 打開指定頁面
WeixinJSBridge.invoke("openSpecificView", { "specificview": "contacts" },
function (e) { alert(e.err_msg); });
WeixinJSBridge.invoke("scanQRCode", {}, function (e) { alert(e.err_msg); });
// 取得網路狀態,回傳值需自行對照
var netType = {
"network_type:wifi": "wifi 網絡",
"network_type:edge": "非 wifi,包含 3G/2G",
"network_type:fail": "網絡斷開連接",
"network_type:wwan": "2g 或者 3g"
};
WeixinJSBridge.invoke("getNetworkType", {}, function (e) {
alert(netType[e.err_msg]);
});
WeixinJSBridge.invoke("closeWindow", {}, function (e) {});
// 介面元素的顯示與隱藏,用 call 即可
WeixinJSBridge.call('hideOptionMenu'); // 隱藏右上角三個點
WeixinJSBridge.call('showOptionMenu');
WeixinJSBridge.call('hideToolbar'); // 隱藏底部導航欄
WeixinJSBridge.call('showToolbar');
介面控制類用 call()(無參數、無回呼),其餘用 invoke(),這個分工與上一篇所述一致。
// 開啟地圖查看某個座標
WeixinJSBridge.invoke("openLocation", {
"latitude": 23.113, "longitude": 113.23,
"name": "TIT創意園", "address": "廣州市海珠區新港中路397號",
"scale": 14, // 地圖縮放級別
"infoUrl": "https://example.com" // 底部超連結
}, function (e) { alert(e.err_msg); });
// 取得使用者目前位置(需使用者授權)
WeixinJSBridge.invoke("geoLocation", {}, function (e) { alert(e.err_msg); });
取得使用者位置屬於敏感操作,除了使用者授權,也務必在隱私政策裡說明用途,並在後端避免長期保存精確座標。
WeixinJSBridge.invoke("addEmoticon", {
"url": "https://example.com/emoji.png",
"thumb_url": "https://example.com/thumb.png"
}, function (e) { alert(e.err_msg); });
WeixinJSBridge.invoke("cancelAddEmoticon", { "url": "https://example.com/emoji.png" },
function (e) { alert(e.err_msg); });
WeixinJSBridge.invoke("hasEmoticon", { "url": "https://example.com/emoji.png" },
function (e) { alert(e.err_msg); });
支付與收貨地址這兩類,前端只能拿到「已經算好的簽名」,簽名本身必須由伺服器端產生:
document.getElementById("getBrandWCPayRequest").addEventListener("click", function () {
WeixinJSBridge.invoke("getBrandWCPayRequest", {
"appId": "wxXXXXXXXXXXXXXXXX", // 商戶的 appId,由後端提供
"timeStamp": "1500000000", // 時間戳,由後端產生
"nonceStr": "a1b2c3d4e5", // 隨機串
"package": "prepay_id=wx1xxxxxxxxxxxx", // 由後端下單取得
"signType": "SHA1",
"paySign": "由後端以商戶金鑰計算出的簽名"
}, function (e) { alert(e.err_msg); });
}, false);
這裡要特別強調一個安全原則:商戶金鑰(API Key / mch_key)永遠不能出現在前端程式碼裡。原始範例為了示意,把 appId、paySign、addrSign 直接寫成看似真實的值,這是示範用的佔位資料;實際上請一律由後端產生並透過自己的 API 傳給前端,且該 API 需驗證使用者身分,否則任何人都能用你的帳號發起交易。
// 編輯收貨地址 / 取得最近使用的地址
WeixinJSBridge.invoke("editAddress", {
"appId": "wxXXXXXXXXXXXXXXXX", "timeStamp": "1500000000",
"nonceStr": "a1b2c3d4e5", "signType": "SHA1",
"addrSign": "由後端計算", "scope": "snsapi"
}, function (e) { alert(e.err_msg); });
sendEmail // 開啟郵件撰寫,帶入標題與內容 openUrlByExtBrowser // 改用系統瀏覽器(iOS 上是 Safari)開啟連結 launch3rdApp // 啟動第三方 App getInstallState // 查詢某 App 是否已安裝(傳 packageUrl,如 "teamcircle://") openProductView // 跳轉微信商品頁 jumpWCMall // 跳轉微信購物商城,需 funcId timelineCheckIn // 朋友圈簽到,可帶入縮圖與 POI 資訊 setPageState // 設定頁面狀態 getCanIAPPay / getBrandIAPPayRequest // iOS 內購支付 getBrandWCPayCreateCreditCardRequest // 開通微信信用卡
原始範例的做法是替每個功能放一個 <input type="button">,然後在 WeixinJSBridgeReady 之後逐一 addEventListener。這個結構可以簡化成資料驅動,避免幾十行重複:
var apis = {
imagePreview: { urls: ["https://example.com/1.png"], current: "https://example.com/1.png" },
scanQRCode: {},
closeWindow: {},
geoLocation: {}
};
document.addEventListener("WeixinJSBridgeReady", function () {
Object.keys(apis).forEach(function (name) {
var btn = document.getElementById(name);
if (!btn) return;
btn.addEventListener("click", function () {
WeixinJSBridge.invoke(name, apis[name], function (e) { alert(e.err_msg); });
}, false);
});
});
wx.config + wx.ready + wx.chooseImage / wx.chooseWXPay / wx.openLocation 等),並要求後端簽名。getBrandWCPayRequest 不同,請查閱微信支付官方文件的當前版本。alert 除錯正式流程。改用 WeixinJSBridge.log() 或 console.log(),並在正式環境移除。err_msg 都要處理。使用者拒絕授權、網路中斷、掃碼取消都會回傳不同的 err_msg,一律當成功處理會讓狀態不一致。這份清單最大的價值不是「照抄可用」,而是作為一份地圖:知道微信 WebView 曾經開放過哪些原生能力、每個能力需要哪些參數、哪些一定要後端簽名。換成 JS-SDK 之後,這些分類與參數概念幾乎一比一對應得上。