WebSocket

說明

推薦使用 SocketTask 的管道去管理webSocket連結，每一條連結的生命週期都更加可控，同時存在多個webSocket的連結的情况下使用wx首碼的方法可能會帶來一些和預期不一致的情况。

sendSocketMessage

TIP

該API使用方法為： wx.sendSocketMessage(Object object)

• 功能說明： 通過WebSocket連接發送數據。 需要先wx.connectSocket ，並在 wx.onSocketOpen 回檔之後才能發送。。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  data	string/ArrayBuffer	-	是	需要發送的內容
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• 示例代碼：

let socketOpen = false
let socketMsgQueue = []
wx.connectSocket({
  url: 'test.php'
})

wx.onSocketOpen(function(res) {
  socketOpen = true
  for (let i = 0; i < socketMsgQueue.length; i++){
    sendSocketMessage(socketMsgQueue[i])
  }
  socketMsgQueue = []
})

function sendSocketMessage(msg) {
  if (socketOpen) {
    wx.sendSocketMessage({
      data:msg
    })
  } else {
    socketMsgQueue.push(msg)
  }
}

onSocketOpen

TIP

該API使用方法為： wx.onSocketOpen(function listener)

• 功能說明： 監聽WebSocket連接打開事件

• 參數及說明： function listener， WebSocket連接打開事件的監聽函數。。

  内容	類型	說明
  header	object	連接成功的HTTP響應Header

onSocketMessage

TIP

該API使用方法為： wx.onSocketMessage(function listener)

• 功能說明： 監聽WebSocket接收到服務器的消息事件。

• 參數及說明： function listener， WebSocket接收到服務器的消息事件的監聽函數。。

  内容	類型	說明
  data	string/ArrayBuffer	服務器返回的消息

onSocketError

TIP

該API使用方法為： wx.onSocketError(function listener)

• 功能說明： 監聽WebSocket錯誤事件。

• 參數及說明： function listener， WebSocket錯誤事件的監聽函數。。

  内容	類型	說明
  errMsg	string	錯誤資訊

onSocketClose

TIP

該API使用方法為： wx.onSocketClose(function listener)

• 功能說明： 監聽WebSocket連接關閉事件。

• 參數及說明： function listener， WebSocket連接關閉事件的監聽函數。。

  内容	類型	說明
  code	number	一個數位值表示關閉連接的狀態號，表示連接被關閉的原因
  reason	reason	一個可讀的字串，表示連接被關閉的原因

connectSocket

TIP

該API使用方法為： SocketTask wx.connectSocket(Object object)

• 功能說明： 創建一個WebSocket連接。 使用前請注意閱讀 相關說明。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  url	string	-	是	開發者服務器wss接口地址
  header	Object	-	否	HTTP Header，Header中不能設定Referer
  protocols	Array.<string>	-	否	子協定數組
  tcpNoDelay	boolean	false	否	建立TCP連接的時候的TCP_NODELAY設定
  timeout	number	-	否	超時時間，單位為毫秒
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• 返回值： SocketTask

• 併發數

  • 1.5.0及以上版本，最多可以同時存在5個WebSocket連接。
  • 1.5.0以下版本，一個小程序同時只能有一個WebSocket連接，如果當前已存在一個WebSocket連接，會自動關閉該連接，並重新創建一個WebSocket連接。

• 示例代碼：

wx.connectSocket({
  url: 'wss://example.qq.com',
  header:{
    'content-type': 'application/json'
  },
  protocols: ['protocol1']
})

closeSocket

TIP

該API使用方法為： wx.closeSocket(Object object)

• 功能說明： 關閉WebSocket連接，使用方法為。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  code	number	1000（表示正常關閉連接）	否	一個數位值表示關閉連接的狀態號，表示連接被關閉的原因
  reason	string	-	否	一個可讀的字串，表示連接被關閉的原因。 這個字串必須是不長於123位元組的UTF-8文字（不是字元）
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• 示例代碼：

wx.connectSocket({
  url: 'test.php'
})

//Please note that there may be timing issues here,
//If wx.connectSocket has not yet called back wx.onSocketOpen, and wx.closeSocket is called first, then the purpose of closing the WebSocket cannot be achieved.
//It is imperative to call wx.closeSocket during the WebSocket's open period to effectuate closure.
wx.onSocketOpen(function() {
  wx.closeSocket()
})

wx.onSocketClose(function(res) {
  console.log('WebSocket has been closed!')
})

SocketTask

.close

TIP

該API使用方法為： SocketTask.close(Object object)

• 功能說明： 關閉WebSocket連接。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  code	number	1000（表示正常關閉連接）	否	一個數位值表示關閉連接的狀態號，表示連接被關閉的原因
  reason	string	-	否	一個可讀的字串，表示連接被關閉的原因。 這個字串必須是不長於123位元組的UTF-8文字（不是字元）
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

.onClose

TIP

該API使用方法為： SocketTask.onClose(function listener)

• 功能說明： 監聽WebSocket連接關閉事件。

• 參數及說明： function listener， WebSocket連接關閉事件的監聽函數。。

  内容	類型	說明
  code	number	一個數位值表示關閉連接的狀態號，表示連接被關閉的原因
  reason	reason	一個可讀的字串，表示連接被關閉的原因

.onError

TIP

該API使用方法為： SocketTask.onError(function listener)

• 功能說明： 監聽WebSocket錯誤事件。

• 參數及說明： function listener， WebSocket錯誤事件的監聽函數。。

  内容	類型	說明
  errMsg	string	錯誤資訊

.onMessage

TIP

該API使用方法為： SocketTask.onMessage(function listener)

• 功能說明： 監聽WebSocket接收到服務器的消息事件。

• 參數及說明： function listener， WebSocket接收到服務器的消息事件的監聽函數。。

  内容	類型	說明
  data	string/ArrayBuffer	服務器返回的消息

.onOpen

TIP

該API使用方法為： SocketTask.onOpen(function listener)

• 功能說明： 監聽WebSocket連接打開事件

• 參數及說明： function listener， WebSocket連接打開事件的監聽函數。。

  内容	類型	說明
  header	object	連接成功的HTTP響應Header

.send

TIP

該API使用方法為： SocketTask.send(Object object)

• 功能說明： 通過WebSocket連接發送數據

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  data	string/ArrayBuffer	-	是	需要發送的內容
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）