@bingtang-rn/react-native-orientation-director for HarmonyOS

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

版本对应关系

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

安装

npm install @bingtang-rn/react-native-orientation-director

使用

import RNOrientationDirector, {
  Orientation,
  OrientationType,
  useDeviceOrientation,
  useInterfaceOrientation,
} from 'react-native-orientation-director';

// 实时获取设备 / 界面方向
const deviceOrientation = useDeviceOrientation();
const interfaceOrientation = useInterfaceOrientation();

// 锁定到竖屏
RNOrientationDirector.lockTo(Orientation.portrait);

// 解锁
RNOrientationDirector.unlock();

// 查询当前锁定状态
const locked = RNOrientationDirector.isLocked();

import 时使用原库名 'react-native-orientation-director'，RNOH 通过 alias 自动重定向到 @bingtang-rn/react-native-orientation-director。

平台差异：

• isAutoRotationEnabled() 在 HarmonyOS 上返回 AutoRotation.unknown（鸿蒙无直接对应系统自动旋转开关 API），原生 stub 不被实际调用。
• 设备方向由 @ohos.sensor SensorId.GRAVITY 传感器 x/y/z 分量计算（含 faceUp/faceDown），与 Android 的 OrientationEventListener + TYPE_ROTATION_VECTOR 算法等价但实现不同。
• 界面方向变化监听使用 @ohos.display on('change') 事件，替代 Android 的 BroadcastReceiver。
• 横屏方向（landscapeLeft/Right）在设备↔界面间做了反转，与原库 iOS 行为对齐。

权限要求：

• 无需任何 ohos.permission.* 运行时权限。传感器订阅、display/window API 均为普通应用能力，module.json5 的 requestPermissions 为空。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 3.0.2 | 是 |

如使用版本支持 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-orientation-director": "file:../../node_modules/@bingtang-rn/react-native-orientation-director/harmony/orientation_director.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-orientation-director/src/main/cpp" ./orientation_director)

target_link_libraries(rnoh_app PUBLIC orientation_director)

4. 注册 Package（C++ 侧）

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

#include "OrientationDirectorPackage.h"

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

5. 注册 Package（ETS 侧）

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

import { OrientationDirectorPackage } from '@bingtang-rn/react-native-orientation-director';

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

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | getInterfaceOrientation | 获取当前界面方向 | 无 | Promise<Orientation> | ✅ 完全支持 | | getDeviceOrientation | 获取当前设备方向 | 无 | Promise<Orientation> | ✅ 完全支持 | | lockTo | 锁定到指定方向 | orientation: Orientation, orientationType?: OrientationType | void | ✅ 完全支持 | | unlock | 解除方向锁定 | 无 | void | ✅ 完全支持 | | isLocked | 查询是否已锁定 | 无 | boolean | ✅ 完全支持 | | resetSupportedInterfaceOrientations | 恢复初始方向配置 | 无 | void | ✅ 完全支持 | | isAutoRotationEnabled | 查询系统自动旋转开关 | 无 | AutoRotation | ❌ 不支持 | | enableOrientationSensors | 开启方向传感器 | 无 | void | ✅ 完全支持 | | disableOrientationSensors | 关闭方向传感器 | 无 | void | ✅ 完全支持 | | onDeviceOrientationChanged | 设备方向变化事件 | { orientation: number } | EventEmitter | ✅ 完全支持 | | onInterfaceOrientationChanged | 界面方向变化事件 | { orientation: number } | EventEmitter | ✅ 完全支持 | | onLockChanged | 锁定状态变化事件 | { locked: boolean } | EventEmitter | ✅ 完全支持 | | useDeviceOrientation | Hook：设备方向 | 无 | Orientation | ✅ 完全支持 | | useInterfaceOrientation | Hook：界面方向 | 无 | Orientation | ✅ 完全支持 | | useIsInterfaceOrientationLocked | Hook：是否锁定 | 无 | boolean | ✅ 完全支持 | | Orientation | 方向枚举（0-7） | — | — | ✅ 完全支持 | | AutoRotation | 自动旋转枚举（0-2） | — | — | ⚠️ 部分支持 | | OrientationType | 方向类型枚举 | — | — | ✅ 完全支持 | | convertOrientationToHumanReadableString | 方向转可读字符串 | Orientation | string | ✅ 完全支持 | | convertAutoRotationToHumanReadableString | 自动旋转转可读字符串 | AutoRotation | string | ✅ 完全支持 | | isLockableOrientation | 判断是否可锁定方向 | Orientation | boolean | ✅ 完全支持 |

平台差异

• 事件通道：RNOH codegen-harmony 不生成 Spec EventEmitter<T> 属性，原生侧通过 ctx.rnInstance.emitDeviceEvent 发送，JS 侧通过 DeviceEventEmitter.addListener 订阅，事件名（OrientationDirector.deviceOrientationChanged 等）与 payload 结构（{orientation: number} / {locked: boolean}）与原库一致。
• 横屏镜像：设备横屏方向与界面横屏方向互为镜像（landscapeLeft ↔ landscapeRight），与 iOS 行为对齐；lockTo 的 OrientationType.device 分支由 JS 门面完成反转。
• 传感器按需启停：首个设备方向监听注册时开启 GRAVITY 传感器，最后一个取消时关闭；构造时也短暂启动以计算初始方向。

未实现功能

| API | 原因 | |-----|------| | isAutoRotationEnabled | HarmonyOS 无直接对应系统自动旋转设置 API（@ohos.settings 无此项，display/window 无查询接口），JS 层对非 android 平台返回 AutoRotation.unknown，与 iOS 行为一致 |

使用限制

• Example 的 module.json5 需将 ability 的 orientation 设为 auto_rotation，lockTo 各方向与自动旋转才能生效。
• window.setPreferredOrientation 的方向锁定语义需真机校准（文档未明确 LANDSCAPE/LANDSCAPE_INVERTED 的物理旋转方向），代码注释已标注校准点。

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

遗留问题

无（或列出已知问题）

开源协议

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