mqtt

uni_modules/yh-wsmqtt/wsmqtt/README.md

@@ -0,0 +1,173 @@
+# 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