洛汐文档库

外观

system.internal.messagecenter

约 875 字大约 3 分钟

2026-07-15

MiConnect/Message Center 的跨设备消息桥，提供 subscribe、unsubscribe、publish 和 unpublish。所有方法使用 options 对象和快应用标准回调。

确认成员

成员/字段类型说明
subscribeFunction订阅 topic；回调收到基础数据和扩展数据
unsubscribeFunction取消指定 topic 订阅
publishFunction发布消息
unpublishFunction取消发布/停止某 topic 的持续发布
trustlevelIntegerMiConnect 信任级别
dispatchtypeInteger分发类型
devicefilterString[]设备过滤列表
dstdevicelistString[]目标设备列表
sendtypesInteger[]发送通道/类型列表
basedataString/TypedArray基础数据
extenddataString/TypedArray扩展数据

固件日志还确认订阅回调至少关联 topic_name、basedata 和 extenddata，并分别记录两段数据长度。底层为 MiConnect 消息中心，发布选项会被转换成 device filter、目标设备列表和 send type 列表。

建议的探测方式

import app from '@system.app'

const feature = '@system.internal.messagecenter'
const methods = ['subscribe', 'unsubscribe', 'publish', 'unpublish']

for (const method of methods) {
  console.log(method, app.canIUse(`${feature}.${method}`))
}

参数定义

interface MessageCallbacks {
  success?: (data?: object) => void
  fail?: (data: object, code?: number) => void
  complete?: () => void
}

interface MessageData {
  topic: string
  basedata?: string | ArrayBuffer | Uint8Array
  extenddata?: string | ArrayBuffer | Uint8Array
  trustlevel?: number
  dispatchtype?: number
  devicefilter?: string[]
  dstdevicelist?: string[]
  sendtypes?: number[]
}

subscribe(options: MessageCallbacks & {
  topic: string
  listener: (message: ReceivedMessage) => void
}): void

unsubscribe(options: MessageCallbacks & { topic: string }): void
publish(options: MessageCallbacks & MessageData): void
unpublish(options: MessageCallbacks & { topic: string }): void

米家应用的订阅回调使用单个结果对象，并读取 basedata、extenddata 与 datatype；不同后端也可能把 topic 放在结果中。接收二进制时先判断 ArrayBuffer/TypedArray，再进行 UTF-8 或协议解码。

发布对象

const options = {
  topic: 'vendor.topic',       // topic 字段由实现日志确认，成员字符串可能被全局去重
  trustlevel: 0,
  dispatchtype: 0,
  devicefilter: [],
  dstdevicelist: [],
  sendtypes: [],
  basedata: new Uint8Array(),
  extenddata: new Uint8Array()
}

字段含义：

字段用法建议
topic非空业务主题；四个操作都围绕它工作
trustlevelMiConnect 信任级别；枚举值未从固件恢复，不要随意提高
dispatchtype分发策略；枚举值未知
devicefilter允许/筛选设备标识列表；固件逐个复制字符串
dstdevicelist明确目标设备列表；固件逐个复制字符串
sendtypes传输通道/类型整数列表；枚举未知
basedata主负载，建议使用 Uint8Array
extenddata附加元数据，建议使用 Uint8Array

调用示例

topic、信任级别、分发类型和 send type 必须由真实 MiConnect 协议提供。下面使用占位 topic，不能直接用于业务：

import messagecenter from '@system.internal.messagecenter'

const topic = 'vendor.protocol.topic'

messagecenter.subscribe({
  topic,
  listener(message) {
    console.log(message.topic, message.datatype)
  },
  fail(data, code) { console.error('subscribe', code) }
})

messagecenter.publish({
  topic,
  basedata: new Uint8Array([1, 2, 3]),
  extenddata: new Uint8Array(0),
  success() { console.log('published') },
  fail(data, code) { console.error('publish', code) }
})

// 页面销毁时
messagecenter.unsubscribe({ topic })
messagecenter.unpublish({ topic })

固件日志中的常见失败点包括：参数错误、topic 复制失败、发布数据创建失败、option 创建失败、未先订阅就取消订阅，以及底层 publish/unpublish 失败。

生命周期

从 wrapper 与日志可以确认合理顺序为：

  1. subscribe(...) 建立 topic 订阅；
  2. 订阅回调接收 topic、基础数据和扩展数据；
  3. 不再接收时 unsubscribe(...)；
  4. 发布侧用 publish(...)，持续发布场景再用 unpublish(...) 停止。

trustlevel、dispatchtype、sendtypes 的枚举整数及设备标识格式仍属于 MiConnect 私有协议。预装米家应用在常用发布场景只传 topic、basedata、extenddata 与回调；不需要定向分发时不要凭空补齐这些高级字段。

机型可用性

Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
△△

获取源代码