@hxa-rn/react-native-push-notification

v8.1.1-beta.1

Published

2 days ago

React Native Local and Remote Notifications

0High
0Medium
0Low

react-native harmony harmonyos push notification

本项目基于 react-native-push-notification 开发。如果在使用过程中有任何问题，欢迎在 AtomGit 提交 Issue，会及时跟进。

当前适配包版本：8.1.1-beta.1。

项目介绍

@hxa-rn/react-native-push-notification 是上游 react-native-push-notification 的鸿蒙适配包，面向 React Native for OpenHarmony，提供本地通知、定时通知、通知渠道、应用角标，以及推送 Token / 主题订阅等相关能力。

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 8.1.1-beta.1 | 8.1.1 | 0.72+ | 是 | API12+ |

集成指南

npm install @hxa-rn/react-native-push-notification

业务侧仍从原包名 'react-native-push-notification' 导入（harmony.alias 映射到本适配包）。

peerDependencies：react-native（>=0.72）。

当前版本支持 Autolink。如需手动 Link：

本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@hxa-rn/react-native-push-notification": "file:../../node_modules/@hxa-rn/react-native-push-notification/harmony/push_notification.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@hxa-rn/react-native-push-notification/src/main/cpp" ./push_notification)

target_link_libraries(rnoh_app PUBLIC push_notification)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "PushNotificationPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<PushNotificationPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { ReactNativePushNotificationPackage } from '@hxa-rn/react-native-push-notification/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new ReactNativePushNotificationPackage(ctx),
  ];
}

使用说明

import PushNotification from 'react-native-push-notification';

PushNotification.configure({
  onRegister: ({ token }) => console.log('register token', token),
  onNotification: (notification) => console.log('notification', notification),
  onAction: (notification) => console.log('action', notification),
  requestPermissions: true,
  popInitialNotification: false,
});

PushNotification.presentLocalNotification({
  channelId: 'test_channel_1',
  title: '通知标题',
  message: '通知内容',
  playSound: true,
});

PushNotification.scheduleLocalNotification({
  channelId: 'test_channel_1',
  title: '定时通知',
  message: '这是一条定时通知',
  date: new Date(Date.now() + 10 * 1000),
});

平台差异要点：

本地通知依赖系统通知开关；建议先 requestPermissions() 或 configure({ requestPermissions: true })。
鸿蒙通知渠道为固定 SlotType 枚举，createChannel 的 channelId 按 importance 映射到对应槽位，粒度比 Android 粗。
定时/重复通知为进程内 setTimeout/setInterval 基线方案，进程被杀死后定时失效。
通知点击经 wantAgent → UIAbility.onNewWant，宿主需写入 AppStorage['PushNotificationWant']（Example 已实现）。

接口文档

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | configure | 配置通知监听与事件回调 | options: ConfigureOptions | void | ✅ 完全支持 | | unregister | 停止通知监听并移除事件回调 | 无 | void | ✅ 完全支持 | | requestPermissions | 请求开启通知并获取推送 Token | 无 | void | ⚠️ 部分支持 | | checkPermissions | 检查通知权限是否已开启 | 无 | callback({ alert }) | ✅ 完全支持 | | getPushToken | 获取推送 Token | 无 | Promise<string> | ⚠️ 需特定条件 | | subscribeToTopic | 订阅推送主题 | topic: string | Promise<boolean> | ⚠️ 需特定条件 | | unsubscribeFromTopic | 退订推送主题 | topic: string | Promise<boolean> | ⚠️ 部分支持（占位返回 true） | | presentLocalNotification | 立即展示本地通知 | details: NotificationDetails | Promise<number | null> | ✅ 完全支持 | | scheduleLocalNotification | 排程定时通知 | details: ScheduledNotificationDetails | Promise<number | null> | ⚠️ 部分支持 | | cancelLocalNotification | 取消本地通知 | notificationId: number | string | Promise<boolean> | ✅ 完全支持 | | clearLocalNotification | 清除通知中心单条通知 | notificationId: number | string | Promise<boolean> | ✅ 完全支持 | | cancelAllLocalNotifications | 取消全部本地通知与排程 | 无 | Promise<boolean> | ✅ 完全支持 | | getDeliveredNotifications | 查询已展示通知 | callback | void | ✅ 完全支持 | | getScheduledLocalNotifications | 查询已排程通知 | callback | void | ⚠️ 部分支持 | | removeAllDeliveredNotifications | 移除全部已展示通知 | 无 | Promise<void> | ✅ 完全支持 | | removeDeliveredNotifications | 移除指定已展示通知 | identifiers: string[] | Promise<void> | ✅ 完全支持 | | abandonPermissions | 放弃推送权限（删除 Token） | 无 | Promise<void> | ⚠️ 部分支持 | | createChannel | 新建通知渠道 | channelInfo: ChannelInfo | callback(boolean) | ⚠️ 部分支持 | | getChannels | 查询渠道列表 | callback | void | ✅ 完全支持 | | channelExists | 检查渠道是否存在 | channelId: string | callback(boolean) | ✅ 完全支持 | | channelBlocked | 检查渠道是否被阻塞 | channelId: string | callback(boolean) | ✅ 完全支持 | | deleteChannel | 删除渠道 | channelId: string | Promise<boolean> | ✅ 完全支持 | | invokeApp | 唤起应用 | data?: object | null | Promise<void> | ✅ 完全支持 | | setApplicationIconBadgeNumber | 设置应用角标数字 | number: number | Promise<boolean> | ⚠️ 部分支持 | | getApplicationIconBadgeNumber | 查询应用角标数字 | 无 | Promise<number> | ⚠️ 部分支持（Preferences 持久化值；系统 getBadgeNumber 仅 API 22+） | | getInitialNotification | 获取初始通知 | 无 | Promise<Object> | ⚠️ 需特定条件 |

未实现 / 占位：setNotificationCategories（鸿蒙无对应 API，JS 层 no-op）。

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ | | HarmonyOS SDK | API 12+ |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-push-notification.git
cd react-native-push-notification
git checkout br_rnoh0.72

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 进入 example 目录，安装依赖

cd example          # 或 example_auto
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

打开 DevEco Studio
选择 example/harmony（或 example_auto/harmony）目录
等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

鸿蒙 SDK：API 12+
上游 RN 库：react-native-push-notification 8.1.1
React Native / RNOH：0.72+
DevEco Studio：5.0+

权限

本地通知发布无需额外权限声明，但用户需已开启应用通知开关。
远程推送（getPushToken / subscribeToTopic）无需声明任何权限，其可用性取决于 AGC 推送服务是否开通，详见下方「远程推送环境配置」。

远程推送环境配置（AGC）

pushService.getToken() 的调用凭据来自签名 Profile，未按下列步骤配置时会失败，此时 getPushToken 降级返回 local_harmony_<timestamp>，subscribeToTopic 抛出带错误码的异常：

在 AppGallery Connect 创建项目与应用，包名需与 HAP 的 bundleName 一致。
在「项目设置 > 开放能力管理」中启用推送服务。
启用后重新申请 Profile 文件（.p7b）—— 遗漏此步会报 1000900010 Illegal application identity。
用新的证书与 Profile 替换工程 build-profile.json5 中的 signingConfigs，重新打包安装。
subscribeToTopic 的 topic 参数为 AGC 场景化消息模板 ID（entityId），非 FCM 式任意字符串；填错会报 1000900019 Illegal entity id。

常见错误码：1000900012 未开通推送权益、1000900020 应用 Token 为空、1000900021 应用未在 AGC 注册。

其它限制

定时/重复通知进程被杀后不触发；角标展示受桌面启动器/系统策略限制。
unsubscribeFromTopic 为占位实现（恒返回 true）：鸿蒙 Push Kit 未提供客户端退订接口，退订需在服务端完成。
华为 Token 与设备、应用绑定，abandonPermissions 删除后重新获取可能返回相同取值。

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

使用问题请在 AtomGit 提交 Issue。也可在 GitCode 仓库反馈：

https://gitcode.com/hxa-rn/react-native-push-notification

https://gitcode.com/hxa-rn/react-native-push-notification/issues