LimeMqtt MQTT通信组件

一个功能强大的MQTT通信组件，提供跨平台的MQTT协议通信能力，支持连接、订阅、发布、断开等基础操作，适用于物联网、实时通信等场景。支持安卓、IOS、鸿蒙Next、Web、微信小程序等平台。

文档链接

📚 组件详细文档请访问以下站点：

• MQTT通信组件文档 - 站点1
• MQTT通信组件文档 - 站点2
• MQTT通信组件文档 - 站点3

安装方法

1. 在uni-app 中搜索并导入lime-mqtt
2. 导入后可能需要重新编译项目
3. APP开发需要使用自定义基座

代码演示

初始化客户端

首先需要导入并初始化MQTT客户端。

import { useMQTT } from '@/uni_modules/lime-mqtt'
const mqttClient = useMQTT()

连接MQTT服务器

连接到MQTT服务器，可配置多种参数。

import type { MQTTConnectOptions } from '@/uni_modules/lime-mqtt'

mqttClient.connect({
  host: "broker.example.com",  // MQTT服务器地址
  port: 8083,                  // 服务器端口
  clientId: "myClient_123",    // 可选，默认自动生成
  username: "user",            // 可选，用户名
  password: "pass",            // 可选，密码
  useSSL: true,                // 是否使用SSL，默认true
  keepalive: 60,               // 心跳间隔，默认60秒
  timeout: 30,                 // 超时时间，默认30秒
  reconnect: false,            // 是否自动重连，默认false
  success: (res) => {
    console.log("连接成功:", res.data.errMsg)
  },
  fail: (err) => {
    console.error("连接失败:", err.errorCode, err.errorMessage)
  }
} as MQTTConnectOptions)

断开连接

主动断开与MQTT服务器的连接。

import type { MQTTDisconnectOptions } from '@/uni_modules/lime-mqtt'

mqttClient.disconnect({
  success: (res) => {
    console.log("已断开连接:", res.data.errMsg)
  },
  fail: (err) => {
    console.error("断开连接失败:", err.errorCode)
  }
} as MQTTDisconnectOptions)

订阅主题

订阅指定的MQTT主题，可设置服务质量(QoS)。

import type { MQTTSubscribeOptions } from '@/uni_modules/lime-mqtt'

mqttClient.subscribe({
  topic: "home/sensor/temperature",  // 要订阅的主题
  qos: 1,                            // 服务质量，0-2
  success: (res) => {
    console.log(`订阅成功: ${res.data.topic}, QoS: ${res.data.qos}`)
  },
  fail: (err) => {
    console.error("订阅失败:", err.errorCode)
  }
} as MQTTSubscribeOptions)

取消订阅

取消订阅指定的MQTT主题。

import type { MQTTUnSubscribeOptions } from '@/uni_modules/lime-mqtt'

mqttClient.unsubscribe({
  topic: "home/sensor/temperature",  // 要取消订阅的主题
  success: (res) => {
    console.log(`已取消订阅: ${res.data.topic}`)
  },
  fail: (err) => {
    console.error("取消订阅失败:", err.errorCode)
  }
} as MQTTUnSubscribeOptions)

发布消息

向指定主题发布消息。

import type { MQTTPublishOptions } from '@/uni_modules/lime-mqtt'

mqttClient.publish({
  topic: "home/light/control",  // 发布的主题
  payload: "turn_on",           // 消息内容
  qos: 1                        // 服务质量，0-2
  success: (res) => {
    console.log(`消息发送成功: ${res.data.topic}`)
  },
  fail: (err) => {
    console.error("消息发送失败:", err.errorCode)
  }
} as MQTTPublishOptions)

监听消息

监听订阅主题的消息。

import type { MQTTMessage } from '@/uni_modules/lime-mqtt'

// 定义消息处理函数
const messageHandler = (msg: MQTTMessage) => {
  console.log(`收到消息 [${msg.topic}]: ${msg.payloadString}`)
  console.log("QoS:", msg.qos)
  console.log("是否保留消息:", msg.retained)
  
  // 如果需要处理二进制数据
   console.log("二进制数据:", msg.payload)
}

// 添加消息监听
mqttClient.onMessage(messageHandler)

// 移除特定的消息监听
mqttClient.offMessage(messageHandler)

// 移除所有消息监听
mqttClient.offMessage()

监听连接状态

监听MQTT连接状态变化。

import type { StateChangeCallback } from '@/uni_modules/lime-mqtt'

// 定义状态变化处理函数
const stateHandler: StateChangeCallback = (stateInfo) => {
  console.log(`连接状态变化: ${stateInfo.state ? '已连接' : '已断开'}`)
  console.log(`状态变化时间: ${new Date(stateInfo.timestamp).toLocaleString()}`)
}

// 添加状态监听
mqttClient.onStateChange(stateHandler)

// 移除特定的状态监听
mqttClient.offStateChange(stateHandler)

// 移除所有状态监听
mqttClient.offStateChange()

API文档

IMQTTClient 接口

方法名	说明	参数	返回值
connect	连接MQTT服务器	MQTTConnectOptions	void
disconnect	断开MQTT连接	MQTTDisconnectOptions	void
subscribe	订阅主题	MQTTSubscribeOptions	void
unsubscribe	取消订阅	MQTTUnSubscribeOptions	void
publish	发布消息	MQTTPublishOptions	void
onMessage	监听消息	MessageCallback	void
offMessage	移除消息监听	MessageCallback (可选)	void
onStateChange	监听连接状态变化	StateChangeCallback	void
offStateChange	移除状态变化监听	StateChangeCallback (可选)	void

属性

属性名	说明	类型
isConnected	当前连接状态	boolean

参数类型

MQTTConnectOptions

参数名	说明	类型	必填	默认值
host	MQTT服务器地址	string	是	-
port	MQTT服务器端口	number	是	-
clientId	客户端ID	string	否	自动生成
username	用户名	string	否	-
password	密码	string	否	-
path	WebSocket路径	string	否	'/mqtt'
protocol	协议前缀(仅小程序)	string	否	-
useSSL	是否使用SSL	boolean	否	true
keepalive	心跳间隔(秒)	number	否	60
timeout	超时时间(秒)	number	否	30
reconnect	是否自动重连	boolean	否	false
success	连接成功回调	SuccessCallback	否	-
fail	连接失败回调	FailCallback	否	-
complete	完成回调	Function	否	-

MQTTDisconnectOptions

参数名	说明	类型	必填	默认值
success	断开成功回调	SuccessCallback	否	-
fail	断开失败回调	FailCallback	否	-
complete	完成回调	Function	否	-

MQTTSubscribeOptions

参数名	说明	类型	必填	默认值
topic	订阅的主题	string	是	-
qos	服务质量(0-2)	number	否	0
success	订阅成功回调	SuccessCallback	否	-
fail	订阅失败回调	FailCallback	否	-
complete	完成回调	Function	否	-

MQTTUnSubscribeOptions

参数名	说明	类型	必填	默认值
topic	取消订阅的主题	string	是	-
success	取消订阅成功回调	SuccessCallback	否	-
fail	取消订阅失败回调	FailCallback	否	-
complete	完成回调	Function	否	-

MQTTPublishOptions

参数名	说明	类型	必填	默认值
topic	发布的主题	string	是	-
payload	消息内容	string	是	-
qos	服务质量(0-2)	number	否	0
success	发布成功回调	SuccessCallback	否	-
fail	发布失败回调	FailCallback	否	-
complete	完成回调	Function	否	-

MQTTMessage

属性名	说明	类型
topic	消息主题	string
qos	服务质量	number
payload	二进制消息内容	Uint8Array
payloadString	字符串消息内容	string
retained	是否为保留消息	boolean

错误代码参考

错误码	说明
910001	连接异常
910002	订阅/取消订阅/发布失败
910004	未连接或连接已断开
910005	缺少host或port参数

常见问题

• iOS平台注意事项: iOS平台上的offMessage和offStateChange暂时无法清空指定函数，只能全部清空（HBuilderX 4.74版本）。
• 小程序连接问题: 微信小程序连接MQTT服务器时，需要在小程序管理后台配置域名白名单。
• 通配符订阅: 使用通配符订阅时，取消订阅也需要使用相同的通配符格式。
• 自动重连: 设置reconnect为true时，客户端会在连接断开后自动尝试重新连接。
• QoS级别:
  • QoS 0: 最多发送一次，可能丢失
  • QoS 1: 至少发送一次，可能重复
  • QoS 2: 只发送一次，不会丢失也不会重复

支持与赞赏

如果你觉得本插件解决了你的问题，可以考虑支持作者：

支付宝赞助	微信赞助

源代码

组件源码