173 lines
4.2 KiB
Markdown
173 lines
4.2 KiB
Markdown
|
# MQTT WebSocket 客户端插件
|
|||
|
|
|
|||
|
|
基于 WebSocket 的 MQTT 客户端插件，支持 uni-app 多端运行。
|
|||
|
|
|
|||
|
|
## 功能特性
|
|||
|
|
|
|||
|
|
- ✅ 支持 MQTT 3.1.1 和 MQTT 5.0 协议
|
|||
|
|
- ✅ 基于 uni-app 的 WebSocket API 实现
|
|||
|
|
- ✅ 自动心跳保活机制
|
|||
|
|
- ✅ 支持自动重连
|
|||
|
|
- ✅ 提供 JavaScript SDK 和 Vue 组件两种使用方式
|
|||
|
|
- ✅ 支持订阅/发布消息
|
|||
|
|
- ✅ 完整的连接状态管理
|
|||
|
|
- ✅ 多端兼容：App、小程序、H5
|
|||
|
|
|
|||
|
|
## 安装
|
|||
|
|
|
|||
|
|
1. 将本插件文件夹 `wsmqtt` 复制到项目的 `uni_modules` 目录下
|
|||
|
|
2. 在需要使用的页面或组件中引入
|
|||
|
|
|
|||
|
|
## 使用方式
|
|||
|
|
|
|||
|
|
### 方式一：JavaScript SDK（推荐）
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
import MQTTClient from '@/uni_modules/wsmqtt/js_sdk/index.js'
|
|||
|
|
|
|||
|
|
// 创建客户端实例
|
|||
|
|
const mqttClient = new MQTTClient({
|
|||
|
|
host: 'broker.emqx.io',
|
|||
|
|
port: 8083,
|
|||
|
|
path: '/mqtt',
|
|||
|
|
clientId: 'client_' + Date.now(),
|
|||
|
|
username: '',
|
|||
|
|
password: '',
|
|||
|
|
protocolVersion: 4, // 4 for MQTT 3.1.1, 5 for MQTT 5.0
|
|||
|
|
keepAlive: 60,
|
|||
|
|
connectTimeout: 10000,
|
|||
|
|
reconnectPeriod: 5000
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// 监听连接事件
|
|||
|
|
mqttClient.on('connect', () => {
|
|||
|
|
console.log('连接成功')
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// 监听消息事件
|
|||
|
|
mqttClient.on('message', (msg) => {
|
|||
|
|
console.log('收到消息:', msg)
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// 连接服务器
|
|||
|
|
mqttClient.connect()
|
|||
|
|
|
|||
|
|
// 发布消息
|
|||
|
|
mqttClient.publish('test/topic', 'Hello MQTT', 0)
|
|||
|
|
|
|||
|
|
// 订阅主题
|
|||
|
|
mqttClient.subscribe('test/topic', 0)
|
|||
|
|
|
|||
|
|
// 取消订阅
|
|||
|
|
mqttClient.unsubscribe('test/topic')
|
|||
|
|
|
|||
|
|
// 断开连接
|
|||
|
|
mqttClient.disconnect()
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 方式二：Vue 组件
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<view>
|
|||
|
|
<mqtt-client :options="mqttOptions" @connect="onConnect" @message="onMessage">
|
|||
|
|
<template v-slot="{ connect, disconnect, publish, status }">
|
|||
|
|
<button @click="connect">连接</button>
|
|||
|
|
<button @click="disconnect">断开</button>
|
|||
|
|
<text>状态: {{ status }}</text>
|
|||
|
|
</template>
|
|||
|
|
</mqtt-client>
|
|||
|
|
</view>
|
|||
|
|
</template>
|
|||
|
|
|
|||
|
|
<script>
|
|||
|
|
import mqttClient from '@/uni_modules/wsmqtt/components/mqtt-client.vue'
|
|||
|
|
|
|||
|
|
export default {
|
|||
|
|
components: {
|
|||
|
|
mqttClient
|
|||
|
|
},
|
|||
|
|
data() {
|
|||
|
|
return {
|
|||
|
|
mqttOptions: {
|
|||
|
|
host: 'broker.emqx.io',
|
|||
|
|
port: 8083,
|
|||
|
|
path: '/mqtt'
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
},
|
|||
|
|
methods: {
|
|||
|
|
onConnect() {
|
|||
|
|
console.log('连接成功')
|
|||
|
|
},
|
|||
|
|
onMessage(msg) {
|
|||
|
|
console.log('收到消息:', msg)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
</script>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## API 文档
|
|||
|
|
|
|||
|
|
### MQTTClient 类
|
|||
|
|
|
|||
|
|
#### 构造函数
|
|||
|
|
```javascript
|
|||
|
|
new MQTTClient(options)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 配置选项
|
|||
|
|
| 参数 | 类型 | 默认值 | 说明 |
|
|||
|
|
|------|------|--------|------|
|
|||
|
|
| host | string | '' | MQTT 服务器地址 |
|
|||
|
|
| port | number | 8083 | 端口号 |
|
|||
|
|
| path | string | '/mqtt' | WebSocket 路径 |
|
|||
|
|
| clientId | string | 'mqttx_' + Date.now() | 客户端 ID |
|
|||
|
|
| username | string | '' | 用户名 |
|
|||
|
|
| password | string | '' | 密码 |
|
|||
|
|
| protocolVersion | number | 4 | 协议版本：3(MQTT 3.1), 4(MQTT 3.1.1), 5(MQTT 5.0) |
|
|||
|
|
| clean | boolean | true | MQTT 3.1.1 Clean Session |
|
|||
|
|
| cleanStart | boolean | false | MQTT 5.0 Clean Start |
|
|||
|
|
| keepAlive | number | 60 | 心跳间隔（秒） |
|
|||
|
|
| sessionExpiryInterval | number | 4294967295 | 会话过期时间 |
|
|||
|
|
| connectTimeout | number | 10000 | 连接超时时间（毫秒） |
|
|||
|
|
| reconnectPeriod | number | 0 | 重连间隔（毫秒），0 表示不自动重连 |
|
|||
|
|
|
|||
|
|
#### 方法
|
|||
|
|
- `connect()`: 连接服务器
|
|||
|
|
- `disconnect()`: 断开连接
|
|||
|
|
- `publish(topic, message, qos)`: 发布消息
|
|||
|
|
- `subscribe(topic, qos)`: 订阅主题
|
|||
|
|
- `unsubscribe(topic)`: 取消订阅
|
|||
|
|
- `on(event, callback)`: 添加事件监听
|
|||
|
|
- `off(event, callback)`: 移除事件监听
|
|||
|
|
- `getStatus()`: 获取当前连接状态
|
|||
|
|
- `getSubscribedTopics()`: 获取已订阅的主题列表
|
|||
|
|
|
|||
|
|
#### 事件
|
|||
|
|
- `connect`: 连接成功
|
|||
|
|
- `disconnect`: 连接断开
|
|||
|
|
- `error`: 发生错误
|
|||
|
|
- `message`: 收到或发送消息
|
|||
|
|
- `statusChange`: 连接状态变化
|
|||
|
|
- `subscribed`: 订阅成功
|
|||
|
|
- `unsubscribed`: 取消订阅成功
|
|||
|
|
|
|||
|
|
## 示例
|
|||
|
|
|
|||
|
|
本项目包含完整的示例页面，位于 `pages/mqtt-demo/index.vue`，展示了插件的所有功能。
|
|||
|
|
|
|||
|
|
## 注意事项
|
|||
|
|
|
|||
|
|
1. 小程序端需要使用真机调试，部分模拟器可能不支持 WebSocket
|
|||
|
|
2. 确保服务器支持 WebSocket 协议的 MQTT
|
|||
|
|
3. 不同平台的 WebSocket 实现可能有差异，建议在各平台测试
|
|||
|
|
|
|||
|
|
## 更新日志
|
|||
|
|
|
|||
|
|
详见 [CHANGELOG.md](./changelog.md)
|
|||
|
|
|
|||
|
|
## 许可证
|
|||
|
|
|
|||
|
|
MIT License
|