文档模板：v0.4.2

react-native-system-setting

本项目基于 react-native-system-setting 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-system-setting（JS 别名 react-native-system-setting），版本所属关系如下：

简介

react-native-system-setting 提供音量、亮度、WiFi、定位、蓝牙、飞行模式等系统设置的读取与控制能力。

本库为其提供 React Native 鸿蒙（HarmonyOS）适配，基于 TurboModule 实现，支持音量/亮度获取与设置、各系统开关状态查询、跳转设置页、状态监听等接口。

下载安装

进入到工程目录并输入以下命令：

npm

npm install @react-native-ohos/react-native-system-setting

yarn

yarn add @react-native-ohos/react-native-system-setting

Link

使用AutoLink的工程需要根据该文档配置，Autolink框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过ManualLink配置。

{
  "overrides": {
    "@rnoh/react-native-openharmony": "~0.82.30" // 0.82 工程；0.84 工程改为对应 0.84.x 版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "@react-native-ohos/react-native-system-setting": "file:../../node_modules/@react-native-ohos/react-native-system-setting/harmony/react_native_system_setting.har"
  }

cd entry
ohpm install

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-system-setting/src/main/cpp" ./system_setting)
# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)
target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_system_setting)
# RNOH_END: manual_package_linking_2

#include "RNOH/PackageProvider.h"
+ #include "RNSystemSettingPackage.h"

using namespace rnoh;

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

  ...
+ import { RNSystemSettingPackage } from '@react-native-ohos/react-native-system-setting/ts';

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

运行

点击右上角的 sync 按钮

或者在终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

要使用此库，需要使用正确的 React-Native 和 RNOH 版本。另外，还需要使用配套的 DevEco Studio 和手机 ROM。

本文档内容基于以下版本验证通过：

1. RNOH: 0.82.7; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM: 6.0.0.328 SP26;
2. RNOH: 0.84.2; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.2.636; ROM: 6.0.0.125;

权限要求

由于此库涉及蓝牙、亮度等系统控制功能，使用对应接口时需要配置对应的权限，权限需配置在 entry/src/main/module.json5 中。其中部分权限需弹窗向用户申请授权。具体权限配置见文档：程序访问控制。

此库部分功能与接口需要 normal 权限：ohos.permission.ACCESS_BLUETOOTH、ohos.permission.GET_WIFI_INFO。

此库部分功能与接口需要 full sdk 与 system_basic 权限：ohos.permission.MANAGE_SECURE_SETTINGS、ohos.permission.MANAGE_WIFI_CONNECTION 等，full sdk获取地址，system_basic权限获取方式。

编译运行API要求

使用示例

下面的代码展示了这个库的基本使用场景：

import React, { useEffect, useState } from 'react';
import { ScrollView, Text, View, StyleSheet, TouchableOpacity } from 'react-native';
import SystemSetting, { EmitterSubscription } from 'react-native-system-setting';

export default function SystemSettingDemo() {
  const [bluetoothEnabled, setBluetoothEnabled] = useState<boolean>();

  useEffect(() => {
    // 初始获取蓝牙状态
    SystemSetting.isBluetoothEnabled().then(setBluetoothEnabled);
  }, []);

  let bluetoothEvent: EmitterSubscription;

  return (
    <ScrollView>
      <View style={styles.module}>
        <Text style={styles.moduleName}>Bluetooth(蓝牙模块)</Text>
        <Text style={styles.moduleContent}>
          蓝牙状态: {bluetoothEnabled === undefined ? '未获取' : bluetoothEnabled ? '开启' : '关闭'}
        </Text>
        <TouchableOpacity
          onPress={() => SystemSetting.isBluetoothEnabled().then(setBluetoothEnabled)}
          style={styles.moduleButton}>
          <Text style={styles.buttonText}>获取蓝牙状态</Text>
        </TouchableOpacity>
        <TouchableOpacity
          onPress={() => SystemSetting.switchBluetooth(() => console.log('跳转完成'))}
          style={styles.moduleButton}>
          <Text style={styles.buttonText}>切换蓝牙状态(跳转设置)</Text>
        </TouchableOpacity>
        <TouchableOpacity
          onPress={async () => {
            bluetoothEvent = await SystemSetting.addBluetoothListener(setBluetoothEnabled);
          }}
          style={styles.moduleButton}>
          <Text style={styles.buttonText}>开启蓝牙状态监听器</Text>
        </TouchableOpacity>
        <TouchableOpacity
          onPress={() => SystemSetting.removeListener(bluetoothEvent)}
          style={styles.moduleButton}>
          <Text style={styles.buttonText}>关闭蓝牙状态监听器</Text>
        </TouchableOpacity>
      </View>
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  module: { margin: 15 },
  moduleName: { fontSize: 25, fontWeight: '700', marginBottom: 4 },
  moduleContent: { fontSize: 16, fontWeight: '500', marginBottom: 4 },
  moduleButton: { marginBottom: 4, backgroundColor: 'deepskyblue', height: 34, borderRadius: 10 },
  buttonText: { fontSize: 18, fontWeight: '400', color: 'white', textAlign: 'center', lineHeight: 32 },
});

使用说明

音量

// 获取系统音量(0~1),type 可选: 'music' | 'system' | 'call' | 'ring' | 'alarm' | 'notification'
const vol = await SystemSetting.getVolume('music');

// 设置音量
SystemSetting.setVolume(0.5, { type: 'music', playSound: false, showUI: false });

// 监听音量变化(返回监听器)
const listener = SystemSetting.addVolumeListener((data) => {
  console.log(data.value); // iOS/Harmony 返回 value
});
SystemSetting.removeVolumeListener(listener); // 移除音量监听

亮度

const brightness = await SystemSetting.getBrightness();     // 获取系统亮度
await SystemSetting.setBrightness(0.8);                     // 设置系统亮度
await SystemSetting.setAppBrightness(0.5);                  // 仅设置应用亮度(无需权限)
const appBrightness = await SystemSetting.getAppBrightness(); // 获取应用亮度

SystemSetting.saveBrightness();        // 保存当前亮度
const saved = SystemSetting.restoreBrightness(); // 恢复保存的亮度(Harmony 恢复应用亮度)

WiFi / 定位 / 蓝牙 / 飞行模式

await SystemSetting.isWifiEnabled();       // 查询 WiFi 状态
SystemSetting.switchWifi(() => {});        // 跳转 WiFi 设置页
await SystemSetting.isLocationEnabled();   // 查询定位状态
SystemSetting.switchLocation(() => {});    // 跳转定位设置页
await SystemSetting.isBluetoothEnabled();  // 查询蓝牙状态
SystemSetting.switchBluetoothSilence(() => {}); // 静默切换蓝牙开关
await SystemSetting.isAirplaneEnabled();   // 查询飞行模式状态
SystemSetting.switchAirplane(() => {});    // 跳转系统设置页

监听器

const l1 = await SystemSetting.addBluetoothListener((enabled) => {});
const l2 = await SystemSetting.addWifiListener((enabled) => {});
const l3 = await SystemSetting.addLocationListener((enabled) => {});
const l4 = await SystemSetting.addAirplaneListener((enabled) => {});
SystemSetting.removeListener(l1); // 统一移除

其他

await SystemSetting.openAppSystemSettings(); // 打开应用的系统设置页

接口说明

详情请见react-native-system-setting

遗留问题

• 由于系统音量权限问题，HarmonyOS 暂无法实现的接口：issue#3
• 由于系统亮度与亮度模式权限问题，HarmonyOS 暂无法实现的接口：issue#4
• 由于系统 WiFi 权限问题，HarmonyOS 暂无法实现的接口：issue#5
• 由于系统未支持位置服务模式监听器相关接口，HarmonyOS 暂无法实现的接口：issue#7
• 由于系统未支持位置服务模式获取相关接口，HarmonyOS 暂无法实现的接口：issue#8
• 由于系统未支持获取飞行模式状态相关接口，HarmonyOS 暂无法实现的接口：issue#9
• 由于系统未支持飞行模式开关监听器相关接口，HarmonyOS 暂无法实现的接口：issue#10

其他

由于仅支持 Android/iOS 特有功能，HarmonyOS 暂无法实现的接口：issue#11

目录结构

/rntpc_react-native-system-setting   # 项目根目录
├── harmony                                    # 鸿蒙适配代码
│    └─ react_native_system_setting.har            # har 包
│    └─ react_native_system_setting                # 鸿蒙适配核心代码
│          └─ Index.ets                            # 鸿蒙适配代码入口
│          └─ ts.ets                               # ArkTS 侧类型导出入口
│          └─ src/main
│              └─ ets
│                  └─ RNSystemSettingPackage.ets           # 鸿蒙侧 Package（TurboModule 注册枢纽）
│                  └─ RNSystemSettingTurboModule.ts        # TurboModule 实现
│                  └─ Logger.ts                           # 日志
│                  └─ generated/                          # codegen 生成的 ArkTS 代码
│              └─ cpp
│                  └─ CMakeLists.txt                       # C++ 侧构建配置（目标 rnoh_system_setting）
│                  └─ RNSystemSettingPackage.h             # C++ Package
│                  └─ ReactNativeSystemSetting.cpp/.h      # TurboModule C++ 实现
├── src                                        # RN 侧 Spec
│    └─ ReactRNSystemSetting.ts                      # TurboModule Spec 定义（codegen 输入）
├── SystemSetting.js / SystemSetting.d.ts      # JS 入口与类型定义
├── example                                    # 示例工程（RN 0.84，上游 demo + 鸿蒙 demo）
├── README.md                                  # 中文文档
├── README_en.md                               # 英文文档

贡献代码

使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR 。

开源协议

本项目基于 The Mit License (MIT) ，请自由地享受和参与开源。