MQTT 在 HarmonyOS 中的应用

MQTT 在 HarmonyOS 中的应用

一、前言

在 HarmonyOS 的智能家居、物联网等场景中，设备之间通常需要一种轻量、实时、低功耗的通信方式。
MQTT 正是这样一种非常适合 HarmonyOS 场景的消息协议。

本文将基于 HarmonyOS （ArkTS），介绍：

• MQTT 的基本使用流程
• MQTT 在 HarmonyOS 中的统一封装方案
• 两个 Page 同时接收同一主题消息的完整实现

二、MQTT 简介

MQTT（Message Queuing Telemetry Transport）是一种基于发布/订阅模式的轻量级消息协议，具有以下特点：

• 协议简单、数据量小
• 支持一对多消息推送
• 非常适合物联网、智能设备、状态同步等场景

在 HarmonyOS 中，MQTT 常用于：

• 设备状态同步
• 实时控制（灯光、空调、传感器）
• 多页面共享实时数据

三、HarmonyOS 中使用 MQTT 的整体步骤

1. 引入 MQTT 客户端库

HarmonyOS 本身不内置 MQTT 协议支持，通常使用 JavaScript / TypeScript 版本的 MQTT 客户端（如 mqtt.js）。

2. 封装统一的 MQTT 管理类

设计一个全局的 MQTT 管理类，用于：

• 管理连接（只连接一次）
• 统一订阅主题
• 分发消息给多个页面

3. 页面通过事件订阅消息

页面不直接操作 MQTT，只监听消息事件，从而实现解耦。

四、MQTT 封装设计思路

为了实现 多个 Page 同时接收同一主题的消息，需要注意以下几点：

• MQTT 连接应为单例
• 消息接收后进行统一分发
• 页面通过事件机制监听消息

整体结构如下：

MQTT 整体结构设计

五、MQTTManager 封装实现

1. MqttManager.ts

路径示例：common/mqtt/MqttManager.ts

import mqtt from 'mqtt'
import emitter from '@ohos.events.emitter'

const EVENT_MQTT_MESSAGE = 10001

class MqttManager {
  private static instance: MqttManager
  private client?: mqtt.MqttClient
  private isConnected: boolean = false

  static getInstance(): MqttManager {
    if (!MqttManager.instance) {
      MqttManager.instance = new MqttManager()
    }
    return MqttManager.instance
  }

  connect() {
    if (this.isConnected) {
      return
    }

    const options = {
      clientId: 'harmony_' + Date.now(),
      username: 'test',
      password: 'test',
      keepalive: 60,
      clean: true
    }

    this.client = mqtt.connect('ws://broker.emqx.io:8083/mqtt', options)

    this.client.on('connect', () => {
      console.info('[MQTT] connected')
      this.isConnected = true
      this.subscribe('demo/topic')
    })

    this.client.on('message', (topic: string, payload: Uint8Array) => {
      const msg = new TextDecoder().decode(payload)

      emitter.emit({
        eventId: EVENT_MQTT_MESSAGE,
        data: {
          topic,
          msg
        }
      })
    })

    this.client.on('error', err => {
      console.error('[MQTT] error', err)
    })
  }

  subscribe(topic: string) {
    this.client?.subscribe(topic)
  }

  publish(topic: string, message: string) {
    this.client?.publish(topic, message)
  }

  onMessage(callback: (topic: string, msg: string) => void) {
    emitter.on({
      eventId: EVENT_MQTT_MESSAGE,
      priority: emitter.EventPriority.HIGH
    }, event => {
      callback(event.data.topic, event.data.msg)
    })
  }

  offMessage() {
    emitter.off(EVENT_MQTT_MESSAGE)
  }
}

export default MqttManager.getInstance()

六、PageA：接收并发送 MQTT 消息

import MqttManager from '../common/mqtt/MqttManager'

@Entry
@Component
struct PageA {
  @State message: string = '等待消息...'

  aboutToAppear() {
    MqttManager.connect()

    MqttManager.onMessage((topic, msg) => {
      this.message = `PageA 收到：${msg}`
    })
  }

  aboutToDisappear() {
    MqttManager.offMessage()
  }

  build() {
    Column() {
      Text('Page A').fontSize(24)

      Text(this.message)
        .fontSize(18)
        .margin(20)

      Button('发送消息')
        .onClick(() => {
          MqttManager.publish('demo/topic', 'Hello from PageA')
        })
    }
    .padding(20)
  }
}

七、PageB：接收同一主题的消息

import MqttManager from '../common/mqtt/MqttManager'

@Entry
@Component
struct PageB {
  @State message: string = '等待消息...'

  aboutToAppear() {
    MqttManager.connect()

    MqttManager.onMessage((topic, msg) => {
      this.message = `PageB 收到：${msg}`
    })
  }

  aboutToDisappear() {
    MqttManager.offMessage()
  }

  build() {
    Column() {
      Text('Page B').fontSize(24)

      Text(this.message)
        .fontSize(18)
        .margin(20)
    }
    .padding(20)
  }
}

八、运行效果说明

• MQTT 只建立一次连接
• PageA 与 PageB 同时订阅 demo/topic
• 任意一页发布消息，两页都会实时收到

该模式非常适合：

• 设备控制页 + 状态展示页
• 多 UI 同步设备数据
• 实时推送场景

九、总结

本文基于 HarmonyOS Stage 模型，实现了：

• MQTT 的基本接入

• 全局 MQTT 单例封装

• 多 Page 同主题消息分发方案

在实际项目中，可以进一步扩展：

• 断线重连

• 心跳检测

• JSON 消息解析

• 设备模型抽象

十、后续扩展方向

• MQTT + MVVM 架构设计

• 设备状态统一管理

• HarmonyOS NEXT 真机适配

• 智能家居完整通信方案

最近加入了一个班级，不仅能学习点技术，还能有考试建议，推荐大家想学习的或者想考证的加入下
班级链接：https://developer.huawei.com/consumer/cn/training/classDetail/d0d15d9039414a8fad9f99ac4a3f5096?type=1%3Fha_source%3Dhmosclass&ha_sourceId=89000248