《HarmonyOS技术精讲-NearLink Kit（星闪服务）》第4篇：广播通信——一对多广播应用实现

《HarmonyOS技术精讲-NearLink Kit（星闪服务）》第4篇：广播通信------一对多广播应用实现

广播模式：解决的不只是消息传递问题

HarmonyOS NEXT 开发里，星闪广播通信是一个被低估的能力。很多人在需要"一对多"消息分发时，下意识会去用分布式数据管理或者文件传输，但忽略了NearLink Kit自带的高效广播通道。

广播通信解决的核心问题很简单：一台设备发消息，多个设备同时收到，不需要建立点对点连接。这在智能家居场景里特别实用------批量开关灯、群发场景指令、设备发现与同步，都是广播的典型应用。

它的价值体现在三个地方：

效率：一条消息发出去，所有监听设备同时收到，O(1) 的发送复杂度
延迟：基于星闪底层技术，广播延迟可以控制在毫秒级
灵活性：支持消息过滤和组播，不是所有设备都回复，可以按业务维度订阅

当然，它也有不适合的场景：如果要求消息100%到达，或者需要确认每个接收端都收到了，广播模式不适合。这时候应该用NearLink的可靠传输通道。

对比：广播 vs 点对点通信

维度	广播通信	点对点通信
连接数	1发N收	1对1
消息可靠性	不保证100%到达	可靠传输
延迟	低（毫秒级）	低（毫秒级）
典型场景	场景控制、设备发现	数据同步、文件传输

环境说明

text 复制代码

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：手机 / 平板 / 开发板（支持星闪功能）

核心实现：从零搭建广播应用

整个实现分三步：权限配置、发送端、接收端。

第一步：权限配置

能在 module.json5 里增加星闪权限。这一步很多人会漏掉，导致真机测试时一直报错。

json 复制代码

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.ACCESS_NEARLINK",
        "reason": "$string:app_name",
        "usedScene": {
          "abilities": [
            "MainAbility"
          ],
          "when": "always"
        }
      }
    ]
  }
}

注意：ACCESS_NEARLINK 是 system_basic 等级的权限，所以调试时需要在设备上先授权。如果不在授权列表中，广播创建会失败。

第二步：发送端实现

发送端需要创建一个 BroadcastChannel，然后通过 broadcastData 把消息推出去。这段代码实现的是"一键关灯"的批量指令。

typescript 复制代码

// Sender.ets
import { nearLink } from '@kit.ConnectivityKit';

@Entry
@Component
struct Sender {
  private channel: nearLink.BroadcastChannel | null = null
  @State sendResult: string = ''

  aboutToAppear() {
    this.initChannel()
  }

  initChannel() {
    try {
      // 创建广播通道，参数是服务类型标识
      this.channel = nearLink.createBroadcastChannel({
        serviceType: 'com.demo.smarthome.light'
      })
      this.sendResult = '通道创建成功'
    } catch (error) {
      this.sendResult = `通道创建失败: ${error.message}`
    }
  }

  sendMessage() {
    if (!this.channel) {
      this.sendResult = '通道未初始化'
      return
    }

    // 构造广播数据
    const data = new Uint8Array([0x01, 0x00, 0x00]) // 关灯指令
    try {
      this.channel.broadcastData(data, {
        // 可选参数：消息权重和有效期
        priority: nearLink.DataPriority.HIGH,
        ttl: 3000 // 3秒内未发送成功则丢弃
      })
      this.sendResult = `消息已广播: ${new Date().toLocaleTimeString()}`
    } catch (error) {
      this.sendResult = `发送失败: ${error.message}`
    }
  }

  build() {
    Column() {
      Text('智能灯控 - 广播发送端')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 20 })

      Button('一键关灯（广播）')
        .onClick(() => this.sendMessage())
        .margin({ bottom: 16 })

      Text(this.sendResult)
        .fontSize(16)
        .fontColor(Color.Gray)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

关键点：

serviceType 是广播通道的标识，发送端和接收端必须一致
broadcastData 第二个参数是配置项，建议设置 ttl 防止消息堆积
广播数据是 Uint8Array 格式，业务层需要自己定义消息格式

第三步：接收端实现

接收端需要监听同一个 serviceType 的广播通道，通过 onReceive 回调处理收到的消息。为了避免多个设备同时响应造成冲突，这里加了一个消息过滤，只处理关灯（0x01）指令。

typescript 复制代码

// Receiver.ets
import { nearLink } from '@kit.ConnectivityKit';

@Entry
@Component
struct Receiver {
  private channel: nearLink.BroadcastChannel | null = null
  @State receiveLog: string = ''
  @State lightStatus: string = '关'

  aboutToAppear() {
    this.initReceiver()
  }

  aboutToDisappear() {
    this.destroyChannel()
  }

  initReceiver() {
    try {
      this.channel = nearLink.createBroadcastChannel({
        serviceType: 'com.demo.smarthome.light'
      })
      // 注册消息接收回调
      this.channel.onReceive((data: Uint8Array) => {
        this.handleBroadcastData(data)
      })
      this.receiveLog = '接收端初始化成功，等待广播...'
    } catch (error) {
      this.receiveLog = `初始化失败: ${error.message}`
    }
  }

  handleBroadcastData(data: Uint8Array) {
    // 消息格式：第1个字节是命令码
    const command = data[0]
    if (command === 0x01) {
      this.lightStatus = '关'
      this.receiveLog = `[${new Date().toLocaleTimeString()}] 收到关灯指令`
    } else if (command === 0x02) {
      this.lightStatus = '开'
      this.receiveLog = `[${new Date().toLocaleTimeString()}] 收到开灯指令`
    } else {
      this.receiveLog = `[${new Date().toLocaleTimeString()}] 未知指令: ${command}`
    }
  }

  destroyChannel() {
    this.channel?.offReceive()
    this.channel = null
  }

  build() {
    Column() {
      Text(`智能灯控 - 接收端 (${this.lightStatus})`)
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 20 })

      Text(this.receiveLog)
        .fontSize(16)
        .fontColor(Color.Gray)
        .margin({ bottom: 16 })

      Text(`当前灯光状态: ${this.lightStatus}`)
        .fontSize(20)
        .fontColor(this.lightStatus === '开' ? Color.Orange : Color.Black)
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

注意事项：

aboutToDisappear 里一定要销毁通道和回调，否则页面退出后还在监听，容易导致内存泄漏
onReceive 回调在子线程执行，不要在里面直接做主线程耗时操作
广播数据是原始字节，业务层要制定协议。我这里用第1字节作为命令码，简单但可扩展

消息过滤与组播

接收端可以通过 serviceType 进行消息过滤。比如智能家居里，灯控的设备订阅 'com.demo.smarthome.light'，窗帘的设备订阅 'com.demo.smarthome.curtain'。发送时按业务维度发到对应频道，天然实现组播。

更精细的过滤可以在应用层做，比如数据包的第2字节作为分组ID，接收端判断分组ID是否匹配再处理。这样同一个频道里还可以划分更多逻辑组。

常见问题与踩坑记录

问题1：广播数据收不到

现象：发送端日志显示发送成功，但接收端一直没触发 onReceive。

原因：排查发现两个设备的 serviceType 字符串不一致。发送端写的是 'com.demo.smarthome.light'，接收端写成了 'com.demo.smarthome.lighting'。广播通道是严格按 serviceType 匹配的，差一个字符都不行。

解决方案 ：把 serviceType 定义成全局常量，发送端和接收端引用同一个常量值。

问题2：页面退出后接收端还活着

现象：用户关闭接收端页面，但日志还持续打印广播消息。

原因：aboutToDisappear 里只置空了 this.channel = null，但没调用 offReceive() 解除回调注册。旧的回调对象还在内存里，继续接收消息。

解决方案 ：严格按照 aboutToDisappear → offReceive() → channel = null 的顺序清理资源。

typescript 复制代码

aboutToDisappear() {
  this.channel?.offReceive()
  this.channel = null
}

最佳实践

不要在 onReceive 里直接修改 UI 状态

广播回调在子线程执行，直接赋值给 @State 变量虽然能触发刷新，但如果有多个回调同时修改，会出现状态不一致。推荐在回调里统一派发到主线程，或者在临界区做同步。
广播数据用简单协议编码

不要往 Uint8Array 里塞 JSON 字符串，解析开销大。实际项目里建议用 TLV 格式（Type-Length-Value），解析快、扩展性好。上面示例里的命令码方式已经很实用了。
发送频率不要太高

星闪广播没有明确的频率限制，但频繁发送会占用无线信道，影响其他近场通信。建议发送间隔不低于100ms。如果业务需要高频率，可以考虑合并多条消息后再广播。

FAQ

Q：为什么真机上广播能收到，模拟器上却不行？

A：模拟器不支持星闪硬件，所以广播功能在模拟器上无法运行。所有 NearLink 相关功能都依赖硬件支持。

Q：广播发给自己设备的其他应用，serviceType 必须一样吗？

A：同一设备上跨应用广播，serviceType 必须一致，并且两个应用都需要在 module.json5 里声明 ACCESS_NEARLINK 权限。

Q：广播丢失率高吗？有没有办法确认接收端收到了？

A：广播是尽力送达，在高干扰环境下确实可能丢包。如果业务需要确认接收，建议在应用层实现 ACK 机制------接收端收到后用点对点通信回复确认。