@bingtang-rn/react-native-settings for HarmonyOS

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

版本对应关系

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

安装

npm install @bingtang-rn/react-native-settings

使用

import RNSettings from 'react-native-settings';

// 查询位置开关
RNSettings.getSetting(RNSettings.LOCATION_SETTING).then(result => {
  if (result === RNSettings.ENABLED) {
    console.log('location is enabled');
  }
});

// 跳转位置设置页，返回后 resolve 最新状态
RNSettings.openSetting(RNSettings.ACTION_LOCATION_SOURCE_SETTINGS).then(
  result => {
    console.log('location is now', result);
  },
);

// 监听位置开关变化
import { DeviceEventEmitter } from 'react-native';
DeviceEventEmitter.addListener(RNSettings.GPS_PROVIDER_EVENT, e => {
  console.log(e[RNSettings.LOCATION_SETTING]);
});

import 时使用原库名 'react-native-settings'，由 RNOH alias 映射到 @bingtang-rn/react-native-settings，无需修改业务代码。

平台差异：

• 飞行模式查询（AIRPLANE_MODE_SETTING）为语义降级：HarmonyOS 无公开飞行模式查询 API，使用 radio.isRadioOn() 间接推断（airplaneOn = !isRadioOn）。用户单独关闭蜂窝时会误判为飞行模式已开。
• 无障碍字幕 API（CAPTIONING_SETTINGS）自 API 12 起废弃，部分设备可能不可用。
• openSetting(ACTION_AIRPLANE_MODE_SETTINGS) 跳转移动网络页（无独立飞行模式设置页 URI）。

权限要求：

• 飞行模式查询需在 module.json5 声明 ohos.permission.GET_NETWORK_INFO（normal 级，安装时授予）。
• 位置开关查询、字幕查询、事件订阅均无需额外权限。

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-settings": "file:../../node_modules/@bingtang-rn/react-native-settings/harmony/settings.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-settings/src/main/cpp" ./settings)

target_link_libraries(rnoh_app PUBLIC settings)

4. 注册 Package（C++ 侧）

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

#include "SettingsPackage.h"

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

5. 注册 Package（ETS 侧）

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

import SettingsPackage from '@bingtang-rn/react-native-settings';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | getSetting(LOCATION_SETTING) | 查询位置服务总开关 | LOCATION_SETTING | Promise<'ENABLED'|'DISABLED'> | ✅ 完全支持 | | getSetting(AIRPLANE_MODE_SETTING) | 查询飞行模式状态 | AIRPLANE_MODE_SETTING | Promise<'ENABLED'|'DISABLED'> | ⚠️ 部分支持（radio.isRadioOn 间接推断，语义降级） | | getSetting(CAPTIONING_SETTINGS) | 查询无障碍字幕开关 | CAPTIONING_SETTINGS | Promise<'ENABLED'|'DISABLED'> | ⚠️ 部分支持（API 12 起废弃，部分设备不可用） | | openSetting(ACTION_LOCATION_SOURCE_SETTINGS) | 跳转位置设置页 | ACTION_LOCATION_SOURCE_SETTINGS | Promise<'ENABLED'|'DISABLED'> | ✅ 完全支持 | | openSetting(ACTION_AIRPLANE_MODE_SETTINGS) | 跳转飞行模式设置页 | ACTION_AIRPLANE_MODE_SETTINGS | Promise<'ENABLED'|'DISABLED'> | ⚠️ 部分支持（跳转移动网络页，无独立飞行模式设置页） | | openSetting(ACTION_CAPTIONING_SETTINGS) | 跳转字幕设置页 | ACTION_CAPTIONING_SETTINGS | Promise<'ENABLED'|'DISABLED'> | ⚠️ 部分支持（跳转辅助功能首页，无独立字幕设置页） | | GPS_PROVIDER_EVENT | 位置开关变化事件 | 无 | {LOCATION_SETTING: 'ENABLED'|'DISABLED'} | ✅ 完全支持 | | AIRPLANE_MODE_EVENT | 飞行模式变化事件 | 无 | {AIRPLANE_MODE_SETTING: 'ENABLED'|'DISABLED'} | ✅ 完全支持 | | CAPTIONING_EVENT | 字幕开关变化事件 | 无 | {CAPTIONING_SETTINGS: 'ENABLED'|'DISABLED'} | ⚠️ 部分支持（API 12 起废弃） | | 常量导出 | 事件名/设置名/ACTION名/ENABLED·DISABLED | — | — | ✅ 完全支持 |

平台差异

• getSetting(AIRPLANE_MODE_SETTING)：HarmonyOS 无公开飞行模式查询 API，使用 @ohos.telephony.radio.isRadioOn() 间接推断（airplaneOn = !isRadioOn）。飞行模式开启时蜂窝无线电通常关闭，但用户单独关闭蜂窝时会误判为飞行模式已开。
• getSetting(CAPTIONING_SETTINGS)：accessibility.getCaptionsManager() 自 API 12 起废弃，部分设备可能返回固定值或不可用。
• openSetting(ACTION_AIRPLANE_MODE_SETTINGS)：HarmonyOS 系统设置无独立飞行模式设置页 URI，跳转到 mobile_network_entry（移动网络页）作为最近邻入口。
• openSetting(ACTION_CAPTIONING_SETTINGS)：HarmonyOS 系统设置无独立字幕设置页 URI，跳转到 accessibility_feature（辅助功能首页）。
• 常量 ACTION_* 值取键名本身（与 Android 的 Settings.ACTION_* 不同），跨平台契约 openSetting(RNSettings.ACTION_*) 保持一致。

使用限制

• 飞行模式查询需声明 ohos.permission.GET_NETWORK_INFO（normal 级，安装时授予，无需运行时申请）。

快速验证（运行 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+

遗留问题

• CAPTIONING_SETTINGS 查询与 CAPTIONING_EVENT 事件依赖的 CaptionsManager 自 API 12 起废弃，系统不再开放相关功能，在 API17+ 设备上可能不可用。
• AIRPLANE_MODE_SETTING 查询为语义降级（radio.isRadioOn() 间接推断），与原库 Android 实现的精确查询不完全对等。

开源协议

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