@bingtang-rn/react-native-notification-sounds for HarmonyOS

本项目基于 react-native-notification-sounds 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 0.5.8 | 0.5.8 | 0.72+ | 是 | API17+ |

安装

npm install @bingtang-rn/react-native-notification-sounds

使用

import NotificationSounds, {
  playSampleSound,
  stopSampleSound,
} from 'react-native-notification-sounds';

// 获取声音列表
const sounds = await NotificationSounds.getNotifications('notification');

// 试听播放
playSampleSound(sounds[0]);

// 停止试听
stopSampleSound();

import 时使用原库名 'react-native-notification-sounds'，而非鸿蒙包名（由 RNOH alias 自动映射）。

平台差异：

• HarmonyOS 上 getNotifications 返回的是应用内置示例铃声资源列表，而非系统铃声列表（鸿蒙公开 API 不提供枚举系统铃声能力）。
• url 字段语义为 rawfile 相对路径（如 "notification/notification_01.wav"），非 Android 的 content:// 或 iOS 的 file:// URI。

权限要求：

• 无需额外权限（rawfile 资源访问与 SoundPool 播放均不需要运行时权限）。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 是 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

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

1. Overrides RN SDK

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

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

2. 引入原生端依赖

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

"dependencies": {
  "@bingtang-rn/react-native-notification-sounds": "file:../../node_modules/@bingtang-rn/react-native-notification-sounds/harmony/notification_sounds.har"
}

执行 ohpm install。

3. 配置 CMakeLists

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

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

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-notification-sounds/src/main/cpp" ./notification_sounds)

target_link_libraries(rnoh_app PUBLIC notification_sounds)

4. 注册 Package（C++ 侧）

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

#include "NotificationSoundsPackage.h"

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

5. 注册 Package（ETS 侧）

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

import { NotificationSoundsPackage } from '@bingtang-rn/react-native-notification-sounds/ts';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | getNotifications | 按类型获取声音列表 | type: 'notification' | 'ringtone' | 'alarm' | Promise<Sound[]> | ⚠️ 部分支持（降级为应用内置铃声资源，非系统铃声） | | playSample | 试听播放指定声音 | uri: string | void | ✅ 完全支持（使用 SoundPool） | | stopSample | 停止当前试听播放 | 无 | void | ✅ 完全支持（使用 SoundPool.stop/unload） | | playSampleSound | 试听播放（JS 封装，取 sound.url 调 playSample） | sound: Sound | void | ✅ 完全支持 | | stopSampleSound | 停止试听（JS 封装，调 stopSample） | 无 | void | ✅ 完全支持 |

平台差异

• getNotifications：鸿蒙公开 API 不支持枚举系统通知/铃声/闹钟条目。@kit.RingtoneKit 仅提供 getSupportedRingtoneTypes/getSupportedDataTypes/getSupportedMaxDuration/startRingtoneSetting（查询可设置类型，不枚举条目）；@kit.AudioKit 的 systemSoundManager.SystemSoundType 仅含 PHOTO_SHUTTER/VIDEO_RECORDING_BEGIN/VIDEO_RECORDING_END。故降级为枚举应用 rawfile 内置铃声资源，保持「获取列表 + 试听」主流程可用。
• url 字段语义差异：原 Android 返回 content://media/... content Uri，原 iOS 返回 file:///... 绝对路径；鸿蒙侧为 rawfile 相对路径（如 "notification/notification_01.wav"），原生侧通过 resourceManager.getRawFd 加载。
• soundID 字段语义差异：原 Android 为系统铃声数据库 id，原 iOS 为 SystemSoundID（整数）；鸿蒙侧为文件名去扩展名（如 "notification_01"）。
• alarm 类型：原库标注 android only，鸿蒙侧降级方案下同样支持（返回应用内置 alarm 类铃声）。

未实现功能

无。三个核心 API 均已实现，行为对齐原库（含空值回退默认通知音、已有播放先停止再播放等边界行为）。

使用限制

• 声音来源为应用 rawfile 内置铃声资源（resources/rawfile/{notification,ringtone,alarm}/），非系统铃声。
• SoundPool 起始 API 10，短音效试听场景适用；不支持后台播放、音频焦点、跳过静音帧。
• 需 HarmonyOS SDK API17+（SoundPool + resourceManager.getRawFileList 均可用）。

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

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

cd example
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 目录
• 等待 Sync 完成

6. 编译并运行 HAP

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

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

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

• getNotifications 返回应用内置铃声资源而非系统铃声（鸿蒙公开 API 不支持枚举系统铃声条目）。

开源协议

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