@wxcloud/miniprogram-websocket-polyfill

Miniprogram Websocket Polyfill

为第三方库（如socket.io-client）使用浏览器WebSocket对象提供适配小程序的版本。支持创建连接WSS/微信云托管的WebSocket。

连接WSS的后台服务：依赖小程序基础库版本 >= 1.7.0 的环境 连接微信云托管的后台服务：依赖小程序基础库版本 >= 2.22.1 的环境

使用

以使用socket.io-client创建WebSocket客户端为例，大致步骤如下：

1. 通过 npm 安装：

npm install --save @wxcloud/miniprogram-websocket-polyfill

2. 执行setup，默认指定创建WSS连接

import { setup } from '@wxcloud/miniprogram-websocket-polyfill'
import * as socketIO from 'socket.io-client'

let socket

Page({
  onLoad() {
    this.testLocalSocketIO()
  },
  // 连接HTTP
  testLocalSocketIO() {
    setup()
    socket = socketIO.io('ws://127.0.0.1:3000', { transports: ['websocket'], query: { test: '112' } })
        
    socket.on('connect', () => {
      console.log('HTTP socket client connected')
    })
    socket.on('message', (msg) => {
      console.log('HTTP socket client reveived: ', msg)
    })
    socket.on('connect_error', (e) => {
      console.log('HTTP connect_error', e)
    })
  },
  onSengMsg() {
    socket.emit('message', '这是HTTP点击触发信息')
  }
})

3. 执行setup时，可指定选用创建连接微信云托管服务的WebSocket。此时需一同传入调用云托管服务的相关参数。

import { setup } from '@wxcloud/miniprogram-websocket-polyfill'
import * as socketIO from 'socket.io-client'

let socket

Page({
  onLoad() {
    this.testContainerSocketIO()
  },
  testContainerSocketIO() {
    setup({
      container: true,
      containerConfigs: {
        config: {
          env: 'env-id' // 环境id
        },
        service: 'socket-io-sever',// 服务名
      }
    })
    // 这里兼容socketio，可任意传入一个符合URL规范的字符串
    socket = socketIO.io('wss://clound-container', { transports: ['websocket'] })
    
    socket.on('connect', () => {
      console.log('socket client connected')
    })
    socket.on('message', (msg) => {
      console.log('socket client reveived: ', msg)
    })
    socket.on('connect_error', (e) => {
      console.log('connect_error', e)
    })
  },
  onSengMsg() {
    socket.emit('message', '这是HTTP点击触发信息')
  }
})

接口

setup(configs?：IMiniprogramWebsocketPolyfill.initOptions)

initOptions类型可参考dist/index.d.ts里的定义

说明

• 示例中，引入的socket.io-client需是browser版本。由于目前工具构建npm不识别第三方库package.json中的browser字段，直接使用工具的构建无法获得符合预期的构建结果，这种情况下可以直接将官方库提供的cdn下的代码保存在项目内直接使用。若使用npm包的形式引入，以webpack打包为例，可指定resolve.aliasField为browser，以指示webpack在构建过程能打包出支持在browser环境下运行的版本。同时，需要根据官方指引去除debug模块。
• socket.io-client默认使用XMLHttpRequest作连接创建的probe，该库目前尚不支持适配这一特性，请在调用方法创建websocket连接时，指定transports: ['websocket']
• 如果有连接多个云托管服务的需求，请在创建websocket连接前再次调用setup方法传入调用云托管服务的相关参数。