qin.connectSocket

创建一个 WebSocket 连接。

在各个小程序平台运行时，网络相关的 API 在使用前需要配置域名白名单。

OBJECT 参数说明

参数名	类型	必填	说明	平台差异说明
url	String	是	服务器接口地址	小程序中必须是 wss:// 协议
header	Object	否	HTTP Header , header 中不能设置 Referer	小程序
method	String	否	默认是GET，有效值：OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE, CONNECT	仅微信小程序支持
protocols	Array<String>	否	子协议数组	H5、微信小程序、抖音小程序
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

qin.connectSocket({
  url: 'wss://www.example.com/socket',
  header: {
    'content-type': 'application/json'
  },
  protocols: ['protocol1'],
  method: 'GET'
});

qin.connectSocket({
  url: 'wss://www.example.com/socket',
  header: {
    'content-type': 'application/json'
  },
  protocols: ['protocol1'],
  method: 'GET'
});

返回值

如果希望返回一个 socketTask 对象，需要至少传入 success / fail / complete 参数中的一个。例如：

var socketTask = qin.connectSocket({
  url: 'wss://www.example.com/socket', //仅为示例，并非真实接口地址。
  complete: ()=> {}
});

var socketTask = qin.connectSocket({
  url: 'wss://www.example.com/socket', //仅为示例，并非真实接口地址。
  complete: ()=> {}
});

如果没有传入 success / fail / complete 参数，则会返回封装后的 Promise 对象： Promise 封装

注意事项

• 网络请求的 超时时间 可以统一在 manifest.json 中配置 networkTimeout。
• 微信小程序平台 1.7.0 及以上版本，最多可以同时存在 5 个 WebSocket 连接。老版本只支持一个socket连接。

qin.onSocketOpen

监听 WebSocket 连接打开事件。

平台兼容性

抖音小程序不支持

CALLBACK 返回参数

属性	类型	说明
header	Object	连接成功的 HTTP 响应 Header

示例代码：

qin.connectSocket({
  url: 'wss://www.example.com/socket',
});
qin.onSocketOpen(() => {
  console.log('WebSocket连接已打开！');
});

qin.connectSocket({
  url: 'wss://www.example.com/socket',
});
qin.onSocketOpen(() => {
  console.log('WebSocket连接已打开！');
});

qin.onSocketError

监听 WebSocket 错误。

平台兼容性

抖音小程序不支持

示例代码

qin.connectSocket({
  url: 'wss://www.example.com/socket',
});
qin.onSocketOpen(() => {
  console.log('WebSocket连接已打开！');
});
qin.onSocketError(() => {
  console.log('WebSocket连接打开失败，请检查！');
});

qin.connectSocket({
  url: 'wss://www.example.com/socket',
});
qin.onSocketOpen(() => {
  console.log('WebSocket连接已打开！');
});
qin.onSocketError(() => {
  console.log('WebSocket连接打开失败，请检查！');
});

qin.sendSocketMessage(OBJECT)

通过 WebSocket 连接发送数据，需要先 qin.connectSocket ，并在 qin.onSocketOpen 回调之后才能发送。

平台兼容性

抖音小程序不支持

OBJECT 参数说明：

参数名	类型	必填	说明
data	String/ArrayBuffer	是	需要发送的内容
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

示例代码

let socketOpen = false;
let socketMsgQueue = [];

qin.connectSocket({
  url: 'wss://www.example.com/socket'
});

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

function sendSocketMessage(theMsg) {
  if (socketOpen) {
    qin.sendSocketMessage({
      data: theMsg,
    });
  } else {
    socketMsgQueue.push(theMsg);
  }
}

let socketOpen = false;
let socketMsgQueue = [];

qin.connectSocket({
  url: 'wss://www.example.com/socket'
});

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

function sendSocketMessage(theMsg) {
  if (socketOpen) {
    qin.sendSocketMessage({
      data: theMsg,
    });
  } else {
    socketMsgQueue.push(theMsg);
  }
}

qin.onSocketMessage

监听 WebSocket 接受到服务器的消息事件。

平台兼容性

抖音小程序不支持

CALLBACK 返回参数

参数	类型	说明
data	String/ArrayBuffer	服务器返回的消息

示例代码：

qin.connectSocket({
  url: 'wss://www.example.com/socket',
});

qin.onSocketMessage((theRes) => {
  console.log('收到服务器内容：' + theRes.data);
});

qin.connectSocket({
  url: 'wss://www.example.com/socket',
});

qin.onSocketMessage((theRes) => {
  console.log('收到服务器内容：' + theRes.data);
});

qin.closeSocket

关闭 WebSocket 连接。

平台兼容性

抖音小程序不支持

OBJECT 参数说明

参数名	类型	必填	说明
code	Number	否	一个数字值表示关闭连接的状态号，表示连接被关闭的原因。如果这个参数没有被指定，默认的取值是 1000 （表示正常连接关闭）
reason	String	否	一个可读的字符串，表示连接被关闭的原因。这个字符串必须是不长于 123 字节的 UTF-8 文本（不是字符）
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

qin.onSocketClose

监听WebSocket关闭。

平台兼容性

抖音小程序不支持

qin.connectSocket({
  url: 'wss://www.example.com/socket',
});

// 注意这里有时序问题，
// 如果 qin.connectSocket 还没回调 qin.onSocketOpen，而先调用 qin.closeSocket，那么就做不到关闭 WebSocket 的目的。
// 必须在 WebSocket 打开期间调用 qin.closeSocket 才能关闭。
qin.onSocketOpen(() => {
  qin.closeSocket();
});

qin.onSocketClose(() => {
  console.log('WebSocket 已关闭！');
});

qin.connectSocket({
  url: 'wss://www.example.com/socket',
});

// 注意这里有时序问题，
// 如果 qin.connectSocket 还没回调 qin.onSocketOpen，而先调用 qin.closeSocket，那么就做不到关闭 WebSocket 的目的。
// 必须在 WebSocket 打开期间调用 qin.closeSocket 才能关闭。
qin.onSocketOpen(() => {
  qin.closeSocket();
});

qin.onSocketClose(() => {
  console.log('WebSocket 已关闭！');
});