# Miniprogram Websocket Polyfill

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

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

## 使用

以使用[socket.io-client](https://github.com/socketio/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。此时需一同传入调用[云托管服务的相关参数](https://developers.weixin.qq.com/miniprogram/dev/wxcloudrun/src/development/websocket/miniprogram.html)。
```
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](https://socket.io/docs/v4/client-installation/#from-a-cdn)下的代码保存在项目内直接使用。若使用npm包的形式引入，以webpack打包为例，可指定resolve.aliasField为`browser`，以指示webpack在构建过程能打包出支持在browser环境下运行的版本。同时，需要根据[官方指引](https://socket.io/docs/v4/client-installation/#from-npm)去除debug模块。
* socket.io-client默认使用XMLHttpRequest作连接创建的probe，该库目前尚不支持适配这一特性，请在调用方法创建websocket连接时，指定`transports: ['websocket']`
* 如果有连接多个云托管服务的需求，请在创建websocket连接前再次调用setup方法传入调用云托管服务的相关参数。