cordova-plugin-broadcaster

一款专为Cordova/PhoneGap应用设计的跨平台广播通信插件，支持iOS和Android平台实现应用内组件间、应用与原生系统间的消息传递，适配各系统原生广播机制，适用于模块化应用通信、原生事件监听、跨页面数据同步等场景。

概述

cordova-plugin-broadcaster封装了OHOS的HiAppEvent事件机制，结合Android和iOS的事件机制，提供了统一的JavaScript API接口。开发者无需深入原生开发即可快速实现跨平台的广播消息发送与接收，解决了Cordova应用中JavaScript层与原生层、应用内不同模块间的通信难题。插件支持自定义广播事件、携带复杂数据、指定广播范围（应用内/系统级）、注销监听等核心能力，广泛应用于模块化应用架构、原生功能触发、状态同步等场景。

支持平台

• iOS：11.0+（支持iPhone、iPad设备，适配iOS 16+通知权限新特性）

• Android：7.0+（支持Android 10+后台广播限制，适配Android 13+权限管理）

• OHOS: 5.0+

核心特性

• 跨层通信：支持JavaScript层与iOS/Android原生层双向通信，原生层可主动发送广播给JS层，JS层也可发送广播触发原生逻辑

• 应用内通信：支持JS层内部不同页面、不同模块间通过广播传递消息，无需依赖全局变量或页面参数

• 系统级广播：Android平台支持监听系统广播（如网络状态变化、电池状态变化），iOS支持监听系统通知

• 复杂数据传递：支持传递字符串、数字、布尔值、数组、对象等多种类型数据，自动处理跨层数据序列化与反序列化

• 广播标识自定义：支持自定义广播事件名称，建议采用"包名.事件名"格式避免冲突（如"com.example.app.USER_LOGIN"）

• 监听管理：支持注册监听、注销指定监听、注销所有监听，避免内存泄漏

• 广播范围控制：Android平台支持指定广播为应用内本地广播或系统全局广播，iOS支持控制通知的发送范围

• 回调支持：发送广播时支持成功/失败回调，监听广播时可实时获取消息内容

• 无侵入性：插件集成后不影响原有应用逻辑，API简洁易集成

安装

在Cordova项目根目录下执行以下命令安装插件，支持从GitHub或本地路径安装：

# 安装hcordova
npm install -g hcordova

# 基础安装
hcordova plugin add cordova-plugin-broadcaster

# 指定OHOS平台安装
hcordova plugin add cordova-plugin-broadcaster --platform ohos

# 从GitCode安装
hcordova plugin add https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-broadcaster.git --platform ohos

# 安装指定版本（如需特定版本）
hcordova plugin add https://github.com/OpenHarmony-Cordova/[email protected] --platform ohos

卸载

如需移除插件，在项目根目录执行以下命令：

# 全平台卸载
hcordova plugin remove cordova-plugin-broadcaster

# 指定OHOS平台卸载
hcordova plugin remove cordova-plugin-broadcaster --platform ohos

详细API

1. 注册事件API

window.broadcaster.addEventListener (eventname, globalFlagOrListener, listener);

参数说明

• eventname 事件名称
• globalFlagOrListener 是否全局监听，设置true
• listener 监听函数

使用示例

var isGlobal = true
var listener = function( e ) {
    console.log( "CONNECTIVITY_CHANGE: " + JSON.stringify(e)  );
    document.getElementById("writeAppEventInfo").innerHTML = "收到监听:"+JSON.stringify(e);
}

function RegisterWatcher() {
    window.broadcaster.addEventListener('CONNECTIVITY', isGlobal, listener);
}

2. 发送事件API

window.broadcaster.fireNativeEvent(eventname, globalFlagOrData, data, success, error)

参数说明

• eventname 事件名称
• globalFlagOrListener 是否全局监听，设置true
• data 发送的数据
• success 成功函数
• error 失败函数

使用示例

function WriteAppEvent( ) {
  window.broadcaster.fireNativeEvent("CONNECTIVITY", isGlobal, "chenlh", function() {
      console.log( "event success!" );
  },function(){
      console.log( "event failed!" );
  });
}

3. 注销事件API

window.broadcaster.removeEventListener(eventname, listener)

参数说明

• eventname 事件名称
• listener 监听函数

使用示例

function UnRegisterWatcher() {
  window.broadcaster.removeEventListener('CONNECTIVITY', listener);
}

许可证

本插件基于 Apache License 开源，详见 LICENSE 文件。

联系方式

OHOS Cordova https://gitcode.com/OpenHarmony-Cordova/cordova-plugin-broadcaster

Android/iOS：https://npmjs.com/cordova-plugin-broadcaster/issues