开发
API

tt.connectSocket

基础库版本 1.0.0 开始支持

创建一个 WebSocket 连接实例,并通过返回的socketTask操作该连接。网络相关的 API 在使用前需要配置域名白名单。请参考网络请求使用说明

语法

tt.connectSocket(options)

参数说明

options 为 Object 类型,属性如下:

属性名类型默认值必填说明最低支持版本
urlstring--Socket 连接地址1.0.0
headerobject--HTTP Header1.0.0
protocolsArray<string>null子协议数组1.0.0
successfunction--接口调用成功的回调函数1.0.0
failfunction--接口调用失败的回调函数1.0.0
completefunction--接口调用结束的回调函数(成功、失败都执行)1.0.0

回调成功

Object 类型,属性如下:

参数参数类型说明最低支持版本
errMsgstring回调信息1.0.0
socketTaskIdnumber当前创建的 sockTask 的序号1.0.0

回调失败

Object 类型,属性如下:

参数参数类型说明最低支持版本
errMsgstring错误信息1.0.0

返回值

SocketTask(Socket 任务对象),调用 tt.connectSocket 后返回的请求对象。

代码示例

<!-- index.ttml -->
  <view>
    <button size="default" bindtap="socketConnect">创建 WebSocket </button>
    <button size="default" bindtap="closeSocket"> 关闭 WebSocket </button>
    <input value="{{inputValue}}" bindinput="inputChange"></input>
    <button size="default" bindtap="sendSocket"> 发送 WebSocket 数据 </button>
  <view>
let socketTask;
Page({
  data: {
    inputValue: "",
  },
  socketConnect() {
    // 如果已经创建,就不再创建了
    if (socketTask) {
      return;
    }
    socketTask = tt.connectSocket({
      url: "wss://someurl",
      success: (res) => {
        // 创建成功的回调
        console.log("创建成功", res);
      },
      fail: (res) => {
        // 创建失败的回调
        console.log("创建失败", res);
      },
      complete: (res) => {
        // 创建完毕的回调
        console.log("创建完毕", res);
      },
    });

    socketTask.onOpen(() => {
      // 此时表示 websocket 已经处于 open 状态
      console.log("WebSocket 已连接");
    });

    socketTask.onClose(() => {
      // 此时表示 websocket 已经处于 closed 状态
      console.log("WebSocket 已断开");
    });

    socketTask.onError((error) => {
      // 此处表示 websocket 有错误发生
      console.error("WebSocket 发生错误:", error);
    });

    socketTask.onMessage((message) => {
      // 每次 WebSocket 发送的信息
      console.log("socket message:", message);
    });
  },
  closeSocket() {
    // 主动关闭 websocket 连接
    console.log("---- close");
    if (socketTask) {
      socketTask.close({
        success: (res) => {
          // 关闭成功的回调
          console.log("close success", res);
        },
        fail: (res) => {
          // 关闭失败的回调
          console.log("close fail", res);
        },
      });
    }
  },
  sendSocket() {
    // 向 websocket 发送信息
    console.log("---- send", this.data.inputValue);
    if (socketTask) {
      // send 发送的数据必须是 object类型
      socketTask.send({
        // 具体发送的数据的 key 必须是 data
        data: this.data.inputValue,
        success: (res) => {
          // 发送成功的回调
          console.log("send success", res);
        },
        fail: (res) => {
          // 发送失败的回调
          console.log("send fail", res);
        },
      });
    }
  },
  inputChange(e) {
    this.setData({
      inputValue: e.detail.value,
    });
  },
});

Bug & Tip

  • Tip:header 不支持设置 referer 字段。
  • Tip:在当前小程序页面已经有一个WebSocket 连接的情况下,如果再创建一个WebSocket 连接,会重新创建一个 WebSocket 连接,但是之前创建的WebSocket 连接并不会自动关闭。
  • Tip:在使用 send 方法时,参数必须是 object 类型,而具体发送的数据必须在 objectdata 字段。
  • Tip:WebSocket 服务器接口地址必须是 wss 协议,且域名必须是后台配置的合法域名。
  • Tip:线上版本只支持 wss 协议的请求,且域名必须是后台配置的合法域名;测试版同时支持 ws 和 wss 协议,请注意提审版本中的协议配置。
  • Tip:在创建 WebSocket 时,如果参数中 protocols 是非空,请确保 WebSocket 服务器能解析并且返回相应的 protocol,否则会创建 WebSocket 失败。
点击纠错
评价此篇文档