DIV CSS 佈局教程網

微信 JS-SDK 介面總整理與使用流程詳解
編輯:關於JavaScript     

微信公眾號裡的網頁之所以能拍照、定位、分享、支付,靠的就是 JS-SDK。以下把整個接入流程與常用介面依序整理出來,方便查閱。(本文以 jweixin-1.0.0 版為例,實際開發請以微信官方最新文件為準。)

一、接入三步驟

1. 引入 JS 檔

在需要呼叫 JS 介面的頁面加入:

https://res.wx.qq.com/open/js/jweixin-1.0.0.js

支援 https,也支援 AMD/CMD 標準模組載入方式。

2. 注入設定(config)

所有使用 JS-SDK 的頁面都必須先注入設定,否則後續介面一律無法呼叫。同一個 URL 只需注入一次;若為 URL 會變動的 SPA,則需在每次路由變化時重新注入。

wx.config({
    debug: true,     // 開啟除錯模式,所有 api 回傳值會以 alert 顯示;參數則透過 log 印出(僅 PC 端)
    appId: '',       // 必填,公眾號唯一標識
    timestamp: ,      // 必填,產生簽名的時間戳
    nonceStr: '',    // 必填,產生簽名的隨機字串
    signature: '',   // 必填,簽名(見附錄 1)
    jsApiList: []    // 必填,要使用的 JS 介面清單(見附錄 2)
});

3. 處理成功與失敗回呼

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 做能力偵測,避免在低版本客戶端直接報錯。

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