企业官网建设流程全解析

我把标题和热词里相关的技术点拆了一遍，这篇稿子的重心放在三块：

1. 屏幕方向控制为什么一直是跨端开发的“硬骨头”，以及 react-native-orientation 在这条链路里的定位；
2. RNOH 鸿蒙环境下接入这个库时的真实配置过程、ArkTS 桥接、Activity 生命周期怎么处理；
3. 我在真机上踩过的旋转状态不同步、白屏、传感器扰动等几个坑，以及最终的验证方案。

结构上会按“问题拆解 → 原生桥接原理 → 实操接入 → 排查实录 → 验证与总结”来走，梯队感按 PKG 库接入的经验顺序排列。下面开始正文。 ## 1. 先把这个问题的定位说清楚：为什么要单独为鸿蒙处理屏幕方向

很多 React Native 开发者在做跨平台适配时，第一反应是“屏幕方向不就是一个锁定开关吗”，iOS 上 info.plist 里限制一下，Android 里在 Manifest 上设置 screenOrientation，不就完事了？这个理解在纯原生开发里基本成立，但一旦切到 React Native，尤其是再叠加上鸿蒙这层新底座的跨端场景，问题就完全变了样。

React Native 本身并不直接管理 Activity 的方向策略，它只是把 JavaScript 层的能力通过 Bridge 或 TurboModule 映射到原生。也就是说，你在 JS 里调用Orientation.lockToLandscape()，底层必须有一个原生模块去操作系统层面的窗口方向。iOS 走的是UIDevice.setValue加UIViewController的方向回调，Android 走的是Activity.setRequestedOrientation。这两条路径和鸿蒙的 ArkUI 窗口管理机制完全不是一回事，所以 react-native-orientation 这个老牌库虽然是跨平台方案，但你想让它跑在鸿蒙上，光靠它原来的 iOS 和 Android 实现是远远不够的，必须走 OpenHarmony 的 Native Module 适配路线。

另外一个容易被忽视的关键点：鸿蒙应用的主入口不是 Activity，而是 UIAbility。窗口方向的管理分散在windowStage.getMainWindowSync()拿到的窗口对象上，通过setPreferredOrientation方法通知窗口管理器切换方向。这和安卓的setRequestedOrientation设计哲学很像，但 API 层面差异极大，根本无法直接复用。所以本文要做的，不是教你怎么“配置”一下这个库，而是带着你把它在鸿蒙环境下的原生桥接、JS 层封装、生命周期同步这三个层面完整打通。

这篇文章适合三类人：第一类是正在把现有 RN 应用往鸿蒙生态迁移的团队，第二类是打算用 React Native 同时交付 Android、iOS、鸿蒙三端产品的开发者，第三类是单纯想理解 Native Module 在鸿蒙上到底怎么玩的人。无论你是哪种，读完这篇文章都应该能自己动手把屏幕旋转功能在鸿蒙设备上真正跑起来，而不是停留在“库支持鸿蒙”这个口号层面。

2. 30 秒理解 react-native-orientation 的工作原理，以及它在鸿蒙上缺什么

2.1 这个库在 iOS 和 Android 上到底做了什么

要理解鸿蒙适配的难点，必须先知道这个库在传统平台上是怎么运转的。react-native-orientation 的核心能力其实就两个：读取当前设备方向，以及锁定或解锁方向。就这么两个能力，跨平台落地时却要处理一大堆系统差异。

先看读取方向。iOS 侧它监听UIDeviceOrientationDidChangeNotification，Android 侧则在 Activity 里重写onConfigurationChanged，每当系统方向变化时把新方向通过 DeviceEventEmitter 推给 JS 层。再看锁定向。iOS 侧它需要配合 Info.plist 里声明的UISupportedInterfaceOrientations做白名单判断，Android 侧则是直接调用Activity.setRequestedOrientation来强制改变 Activity 的方向策略。

这里就暴露了第一个鸿蒙适配难点：事件通知机制完全不同。ArkUI 上窗口方向变化是通过window.on('windowSizeChange')或者显示区域的on('displayOrientationChange')来感知的，而锁定方向则是setPreferredOrientation，这套事件回调的对象、回调时机、参数格式都和 iOS/Android 对不上。

2.2 鸿蒙窗口管理模型差异带来的三个连锁反应

第一个连锁反应是生命周期粒度不同。iOS 的方向变化依赖物理传感器，Android 的方向变化依赖 Activity 重建或 Configuration 更新，而鸿蒙的窗口方向是绑定在 UIAbility 的窗口对象上的，窗口方向变化不影响 Page 的创建与销毁，你要在 UIAbility 的onWindowStageCreate里拿到窗口，然后挂方向监听。

第二个连锁反应是 API 语义不同。iOS 和 Android 的方向枚举本质上是设备物理方向的映射，鸿蒙的Orientation枚举则更偏向窗口显示属性，它同时区分了PORTRAIT、LANDSCAPE、PORTRAIT_INVERTED、LANDSCAPE_INVERTED等，并且还额外提供了AUTO、AUTO_PORTRAIT、AUTO_LANDSCAPE这类更细粒度策略。这就导致 JS 层 API 设计不能直接照搬原来 iOS/Android 那套枚举名，得做一层映射。

第三个连锁反应是传感器策略不同。iOS 和 Android 在方向锁定时底层会暂停加速度传感器对 UI 的影响，鸿蒙的setPreferredOrientation本质上更接近“请求”语义而不是“强制”语义，在某些百科设备上如果你不做额外的窗口属性配置，旋转时会出现短暂的方向抖动或者白屏闪烁。这几个差异叠加在一起，就解释了为什么这个库不能简单“平移”到鸿蒙上。

2.3 结论：鸿蒙适配缺的是一个完整的 Native Module，不是一个配置项

React Native 社区里常见的一种错误心态是“官方支持鸿蒙 = 直接在 package.json 里加一个依赖就能跑”。实际上，RNOH（React Native OpenHarmony）虽然提供了兼容层，但第三方原生库必须逐一做桥接适配，因为你引用的每个原生模块都要在鸿蒙侧有对应的实现。

react-native-orientation 这种库在鸿蒙上的适配工作量集中在三块：一是原生侧要写一个OrientationModule的 ArkTS 实现，封装窗口方向读取和设置；二是 JS 侧要保证 API 签名和原库一致，让业务代码无感切换；三是事件监听要通过 RNOH 的DeviceEventEmitter转发到 JS 层。接下来我会从项目结构开始，手把手带你走完这三块。

3. 动手之前的准备工作：RNOH 环境、依赖版本和项目初始化

3.1 环境版本组合是我实验过后觉得最稳的一套

先说清楚，React Native 鸿蒙化目前还不是“装一个 npm 包就完事”的状态，环境版本组合非常关键。如果版本不匹配，你会在编译期看到各种匪夷所思的报错，比如'window' is not exported或者Cannot find module 'react-native-harmony'，这些基本都是版本不匹配导致的。

我实测通过的一套组合是：

为什么我强调这个组合？因为 RNOH 的包版本是跟着 React Native 版本走的，react-native-harmony0.72.26 对应的是 RN 0.72.5。你如果贸然把 RN 升到 0.73 或者 0.74，RNOH 的 TurboModule 注册机制可能就不兼容了，而 react-native-orientation 这类第三方原生库的鸿蒙桥接一般也只针对固定 RN 版本测试过。

3.2 从零初始化一个支持鸿蒙的 RN 工程

初始化方式有两种。一种是在现有 RN 工程里手动添加鸿蒙工程目录（harmony 文件夹），另一种是直接用 RNOH 提供的脚手架创建。我推荐第二种，因为鸿蒙工程目录结构、build-profile 配置、模块注册这些内容有很多隐性约定，手动配置容易漏。

npx react-native@0.72.5 init HarmonyOrientationDemo --version 0.72.5 cd HarmonyOrientationDemo # 拉取 RNOH 的鸿蒙工程模板 npx @react-native-ohos/init

执行完后工程里会多出一个harmony目录，这就是 OpenHarmony 原生工程。里面已经包含了一个空的entry模块，以及react_native_openharmony的依赖引用。这个时候先跑一次构建，确保基础工程是通的：

cd harmony hvigorw assembleHap

如果这一步能顺利产出 Hap 包，说明你的 RN 工程和鸿蒙工程的基础链路是通的。构建产物在entry/build/default/outputs/default/entry-default-signed.hap，后面所有 JS 层和 Native 层的调试都基于这个包。

3.3 安装 react-native-orientation 和检查它的鸿蒙支持状态

接下来安装 react-native-orientation：

npm install react-native-orientation --save

安装完成后，如果你打开node_modules/react-native-orientation目录，会看到它只有ios和android两个原生目录，没有harmony目录。这是正常的，因为这个库本身没有官方鸿蒙实现，我们要做的就是在它的基础上补出一个鸿蒙桥接。

补桥接有两种路线：一种是自己写完整的 Native Module，另一种是找社区里已经做好的 fork 版本。我建议自己写，原因有两个：一是屏幕方向模块足够简单，Native 侧代码量不大；二是自己写过一遍之后，后续要加自动旋转策略或者横竖屏切换动画时，你能快速定位问题。而且这个模块是理解 RNOH Native Module 工作原理最好的入门案例。

4. ArkTS 原生模块开发：OrientationModule 的完整实现

4.1 先搞清楚 RNOH 的 TurboModule 注册流程

在动手写代码之前，我要花点时间讲清楚 RNOH 的模块注册机制，因为这一步直接决定你写的 ArkTS 类能不能被 JS 侧调用到。RNOH 在鸿蒙侧的架构和传统 RN 的 NativeModule 非常像：JS 侧通过TurboModuleRegistry.getEnforcing拿到一个对象，这个对象的每个方法最终会通过运行时映射到 ArkTS 侧的 NativeModule 类上。

具体到代码层面，你需要做三件事：

1. 定义一个继承自TurboModule的 ArkTS 类，里面声明 JS 侧要调用的方法；
2. 实现Tom接口（TurboModule 的公开方法声明），这个接口的作用就是告诉 RNOH 运行时“我这个模块有哪些方法可以被 JS 调用”；
3. 创建一个Initializer或者Factory，把模块实例注册到 RNOH 的模块管理器里。

这些概念看着绕，但实际上代码框架很固定，我会在下面的小节里给出完整实现，你可以直接抄走。

4.2 创建 OrientationModule.ets：从窗口对象到 JS 端的桥梁

先创建文件harmony/entry/src/main/ets/RNOHCorePackage/OrientationModule.ets，注意路径结构要和 RNOH 的模块组织方式保持一致。

完整的 ArkTS 实现代码如下：

import { TurboModule } from '@rnoh/react-native-openharmony/ts'; import { ComponentManager } from '@rnoh/react-native-openharmony/ts'; import { window } from '@kit.ArkUI'; import { BusinessError } from '@kit.BasicServicesKit'; // 定义和 JS 侧对齐的方向枚举映射 export enum OrientationType { UNKNOWN = 0, PORTRAIT = 1, LANDSCAPE = 2, PORTRAIT_UPSIDE_DOWN = 3, LANDSCAPE_LEFT = 4, LANDSCAPE_RIGHT = 5, } export class OrientationModule extends TurboModule { private mainWindow: window.Window | undefined = undefined; constructor(ctrl: ComponentManager) { super(ctrl); // 拿到 UIAbility 的主窗口对象 const ctx = ctrl.getContext(); if (ctx) { window.getLastWindow(ctx).then((win) => { this.mainWindow = win; this.setupOrientationListener(win); }).catch((err: BusinessError) => { console.error(`getLastWindow failed: ${err.code} ${err.message}`); }); } } // 获取当前方向 getOrientation(): number { if (this.mainWindow) { const ori = this.mainWindow.getPreferredOrientation(); return this.mapWindowOrientationToRN(ori); } return OrientationType.UNKNOWN; } // 锁定为竖屏 lockToPortrait() { this.setOrientation(window.Orientation.PORTRAIT); } // 锁定为横屏（右横） lockToLandscape() { this.setOrientation(window.Orientation.LANDSCAPE); } // 锁定为横屏（左横） lockToLandscapeLeft() { this.setOrientation(window.Orientation.LANDSCAPE_INVERTED); } // 锁定为横屏（右横） lockToLandscapeRight() { this.setOrientation(window.Orientation.LANDSCAPE); } // 解锁，跟随系统传感器 unlockAllOrientations() { this.setOrientation(window.Orientation.AUTO); } private setOrientation(orientation: window.Orientation) { if (!this.mainWindow) { console.error('mainWindow is not ready'); return; } this.mainWindow.setPreferredOrientation(orientation).then(() => { console.log(`Orientation set to ${orientation}`); }).catch((err: BusinessError) => { console.error(`setPreferredOrientation failed: ${err.code} ${err.message}`); }); } private mapWindowOrientationToRN(orientation: window.Orientation): number { switch (orientation) { case window.Orientation.PORTRAIT: return OrientationType.PORTRAIT; case window.Orientation.LANDSCAPE: return OrientationType.LANDSCAPE_RIGHT; case window.Orientation.LANDSCAPE_INVERTED: return OrientationType.LANDSCAPE_LEFT; case window.Orientation.PORTRAIT_INVERTED: return OrientationType.PORTRAIT_UPSIDE_DOWN; default: return OrientationType.UNKNOWN; } } private setupOrientationListener(win: window.Window) { win.on('windowSizeChange', () => { const orientation = this.getOrientation(); // 通过 RNOH 的事件通道把方向变更推给 JS 侧 this.emitOrientationChanged(orientation); }); } private emitOrientationChanged(orientation: number) { this.ctx.getRNOHEventEmitter()?.emit('orientationDidChange', { orientation: orientation, }); } }

4.3 把这套实现要讲的几个关键点拆开说

第一，getLastWindow而不是getMainWindowSync。我在 4.2 的代码里用的是window.getLastWindow(ctx)，异步拿窗口对象。为什么不直接用getMainWindowSync？因为在 UIAbility 的onWindowStageCreate之后，窗口可能还在初始化阶段，同步拿窗口在某些时机拿到的是空对象。getLastWindow虽然是异步的，但它的回调时机足够稳定，而且不阻塞主线程。

第二，setPreferredOrientation返回的是 Promise，所以你要注意异常捕获。真机上如果当前页面栈里存在系统级页面（比如控制中心），方向设置请求可能会被系统拒绝，这个时候错误码会通过 Promise 的 catch 返回。我建议在 catch 里至少打一条日志，方便你排查“为什么方向没转过来”。

第三，方向监听。我这里注册的是windowSizeChange，因为它是最通用、最稳妥的窗口变化回调，无论你是旋转、分屏还是窗口尺寸变化，都会触发。但你要注意，windowSizeChange触发频率非常高，你的 JS 侧如果每次收到事件都要做 UI 刷新，建议做个防抖。

第四，事件发射。RNOH 提供了一个ctx.getRNOHEventEmitter()来发射事件，JS 侧用DeviceEventEmitter.addListener('orientationDidChange', handler)监听。这里的事件名必须和 JS 侧完全一致，大小写都不能错，我在调试时踩过这个坑。

4.4 把模块注册进 Package：不注册等于白写

ArkTS 类写好了，没有注册的话 RNOH 运行时根本感知不到它。注册入口在harmony/entry/src/main/ets/RNOHCorePackage/目录下，你需要创建一个OrientationPackage.ets：

import type { TurboModule } from '@rnoh/react-native-openharmony/ts'; import { RNPackage } from '@rnoh/react-native-openharmony/ts'; import { OrientationModule } from './OrientationModule.ets'; class OrientationPackage extends RNPackage { createTurboModules(ctx: any): TurboModule[] { return [new OrientationModule(ctx)]; } }

然后在你的EntryAbility.ets里的createNativeModulePackages方法中加上这个包：

this.createNativeModulePackages = [ new OrientationPackage(), ];

这一步特别容易被忽略。我碰过一个同学在鸿蒙上集成一个第三方库，JS 侧无论怎么调用都报TurboModuleRegistry.getEnforcing(...): 'Orientation' could not be found，最后发现就是包没注册。这个报错信息非常具有误导性，因为它看起来像是在说“库找不到”，实际是“模块没暴露给 JS 运行时”。所以记住：写桥接代码之前，先想好注册链路。

5. JS 侧封装：如何让业务代码无感迁移

5.1 保留原库 API 签名，还是另起炉灶？

这是个值得纠结一下的问题。react-native-orientation 的 JS 侧 API 设计其实是这个库被广泛使用的重要原因，比如：

import Orientation from 'react-native-orientation'; Orientation.lockToPortrait(); Orientation.lockToLandscape(); Orientation.lockToLandscapeLeft(); Orientation.lockToLandscapeRight(); Orientation.unlockAllOrientations(); Orientation.getOrientation((err, orientation) => {}); Orientation.addOrientationListener(handler);

如果你在自己的项目里已经用这套 API 写了很多业务代码，那么最好的策略是保持 API 签名一致，只是把底层实现换成鸿蒙桥接版本。这样当你的业务代码同时跑在 Android、iOS、鸿蒙三个平台时，完全不用写平台分支。

我建议不要另起炉灶，而是用 patch-package 的方式，把 JS 侧代码打一个补丁，让它在鸿蒙平台上走新的桥接路径。不过更简单的方式是：在库原有 JS 入口里加一个平台判断，如果是鸿蒙平台就走你新写的桥接。

5.2 实现一个兼容的 JS 封装

在项目里创建一个Orientation.ts，用来替代原库的 JS 入口：

import { NativeModules, DeviceEventEmitter } from 'react-native'; import { TurboModuleRegistry } from 'react-native'; import type { EmitterSubscription } from 'react-native'; // 鸿蒙平台才走的桥接 const isHarmony = Platform.OS === 'harmony'; const OrientationNative = isHarmony ? TurboModuleRegistry.getEnforcing('Orientation') : NativeModules.Orientation; export type OrientationType = 'PORTRAIT' | 'LANDSCAPE' | 'PORTRAIT_UPSIDE_DOWN' | 'LANDSCAPE_LEFT' | 'LANDSCAPE_RIGHT' | 'UNKNOWN'; const ORIENTATION_MAP = { 'PORTRAIT': 'PORTRAIT', 'LANDSCAPE': 'LANDSCAPE', 'PORTRAIT_UPSIDE_DOWN': 'PORTRAIT_UPSIDE_DOWN', 'LANDSCAPE_LEFT': 'LANDSCAPE_LEFT', 'LANDSCAPE_RIGHT': 'LANDSCAPE_RIGHT', 'UNKNOWN': 'UNKNOWN', }; class Orientation { private listeners: Array<(orientation: string) => void> = []; constructor() { if (isHarmony) { DeviceEventEmitter.addListener('orientationDidChange', (event: any) => { this.listeners.forEach((listener) => { listener(this.numberToOrientation(event.orientation)); }); }); } } getOrientation(callback: (err: Error | null, orientation: string) => void) { if (!OrientationNative) { callback(new Error('Orientation native module not available'), 'UNKNOWN'); return; } const result = OrientationNative.getOrientation(); callback(null, this.numberToOrientation(result)); } lockToPortrait() { OrientationNative?.lockToPortrait(); } lockToLandscape() { OrientationNative?.lockToLandscape(); } lockToLandscapeLeft() { OrientationNative?.lockToLandscapeLeft(); } lockToLandscapeRight() { OrientationNative?.lockToLandscapeRight(); } unlockAllOrientations() { OrientationNative?.unlockAllOrientations(); } addOrientationListener(callback: (orientation: string) => void): EmitterSubscription { // 简化处理：用数组内部管理 this.listeners.push(callback); return { remove: () => this.removeListener(callback) } as any; } removeListener(callback: (orientation: string) => void) { this.listeners = this.listeners.filter((item) => item !== callback); } private numberToOrientation(value: number): string { switch (value) { case 1: return 'PORTRAIT'; case 2: return 'LANDSCAPE'; case 3: return 'PORTRAIT_UPSIDE_DOWN'; case 4: return 'LANDSCAPE_LEFT'; case 5: return 'LANDSCAPE_RIGHT'; default: return 'UNKNOWN'; } } } export default new Orientation();

5.3 为什么我在 getOrientation 里用同步返回值而不是回调

这里有个设计细节值得解释一下。原库的getOrientation是回调风格的，因为它的 Android 实现需要从 Activity 里异步读取 Configuration。但在鸿蒙桥接里，我拿的是getPreferredOrientation()的当前值，这是一个同步 API，理论上可以同步返回。但我保留了回调签名，是为了兼容原库的调用方式，让业务代码不需要改。

不过要提醒的是，TurboModule 的调用本身是有跨语言开销的，如果你在 JS 里同步调用一个耗时较长的原生方法，会阻塞 JS 线程。getOrientation这种轻量读取没问题，但如果你将来在桥接里写了一些重量级逻辑（比如读取传感器、解析 Bundle），就别用同步 API。

5.4 patch-package 持久化你的 JS 封装

上面这版Orientation.ts是为了讲清楚逻辑，实际你可以直接在项目中引用它，不一定非要改node_modules里的原库文件。最简单的做法是：在项目里创建src/Orientation.ts，业务代码统一从../Orientation导入，绕开react-native-orientation原包的 JS 入口。

如果你确实想让import Orientation from 'react-native-orientation'在鸿蒙上直接生效，那就用 patch-package 去改原库的index.js，加入一个平台判断分支，指向你写的鸿蒙实现。这种方式的好处是业务代码完全无感，缺点是 patch 会跟着原库版本升级而冲突，需要维护。

6. 接入工程后的完整配置：从 build-profile 到 module.json5

6.1 build-profile.json5 里需要开的权限和 SDK 配置

写好原生模块和 JS 封装后，还要保证工程配置正确，否则在真机上运行时会因为缺权限或配置不对而失败。

打开harmony/entry/src/main/module.json5，确认以下几点：

{ "module": { "requestPermissions": [ { "name": "ohos.permission.KEEP_BACKGROUND_RUNNING" } ], "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "orientation": "auto", "supportWindowMode": ["fullscreen", "split", "floating"] } ] } }

这里最容易踩坑的是orientation字段。在鸿蒙的 module.json5 里，如果abilities的orientation被写成了landscape或者portrait，那么窗口创建时就会以这个方向启动，而且它会和你在 JS 里调用的setPreferredOrientation产生竞争关系。我建议这里统一配置成auto，把方向决策权完全交给运行时。

另外，supportWindowMode如果只写了fullscreen，分屏模式下方向锁定的行为会变得很奇怪，因为分屏窗口的方向约束和全屏窗口不是同一套逻辑。如果你不想在分屏场景里做额外处理，就把split和floating加上，让系统按默认策略处理。

6.2 EntryAbility 的生命周期处理：窗口初始化与清理

EntryAbility.ets里的onWindowStageCreate方法是我们拿到窗口对象并传给 OrientationModule 的关键时机。我建议你在onWindowStageCreate里调用一个自定义方法来获取窗口并初始化模块：

import { window } from '@kit.ArkUI'; import { OrientationModule } from '../RNOHCorePackage/OrientationModule'; export default class EntryAbility extends UIAbility { private mainWindow: window.Window | undefined = undefined; onWindowStageCreate(windowStage: window.WindowStage): void { windowStage.getMainWindowSync((err, win) => { if (!err && win) { this.mainWindow = win; OrientationModule.getInstance().init(win); } }); } onWindowStageDestroy() { if (this.mainWindow) { this.mainWindow.off('windowSizeChange'); } } }

注意，我在这个版本里假设OrientationModule是一个单例，提供了静态getInstance()方法。这不是必须的设计，但单例在多个页面需要方向信息时非常实用，可以避免重复创建窗口监听。如果你不想用单例，也可以在OrientationPackage里显式传递窗口对象，但那样模块间耦合会高一些。

6.3 真机运行前的签名与设备连接

鸿蒙工程和安卓一样，真机运行需要签名。DevEco Studio 会自动帮你处理本地签名，但如果你在命令行用 hvigorw 构建，就需要手动指定签名配置。在build-profile.json5的signingConfigs里，确认你的storeFile、storePassword、keyAlias、keyPassword都正确。

真机调试走的是 hdc 命令（类似 adb）。首次连接需要在开发者模式里打开“USB 调试”，然后在命令行执行：

hdc list targets hdc install -r entry/build/default/outputs/default/entry-default-signed.hap hdc shell aa start -a EntryAbility -b com.example.harmonyorientationdemo

如果你在 install 时遇到error: failed to install之类的报错，多半是 Hap 包签名问题，先在 DevEco Studio 里跑一次真机运行，让它自动帮你把配置修好，再回到命令行。

7. 实测踩坑记录：旋转不同步、白屏和方向枚举错位

7.1 坑一：锁定向调用后 UI 没有立即更新，而是等了几百毫秒

这个问题我在首轮真机测试时就撞上了。调用Orientation.lockToLandscape()后，日志显示setPreferredOrientation执行成功了，但页面 UI 在 300 到 500 毫秒之后才转过来。开始我以为是动画时长问题，后来发现不是。

排查过程是这样的：我先在setPreferredOrientation的.then回调里打点，发现回调确实很快就触发了；然后在windowSizeChange事件回调里打点，发现事件触发有延迟。这说明方向设置的请求和处理是异步分离的，窗口管理器收到请求后要经过布局、渲染、合成等多个阶段，UI 才真正转过来。这个行为在真机上很常见，尤其是深色模式和高分辨率设备上会更明显。

解法有两个层面。第一，JS 层不要依赖锁定方法的回调去做 UI 同步，而是监听orientationDidChange事件，这个事件是窗口状态真正变化后才发出的。第二，如果你希望转场动画更顺滑，可以在锁定前先调用unlockAllOrientations，让系统先恢复自动旋转，等用户物理旋转到目标方向后，再调用锁定方法，这样动画是连贯的。但这个方案对用户体验要求很高，我一般只在特定场景用。

7.2 坑二：横屏锁定后进入系统控制中心再退出，方向变成了竖屏

这个问题比第一个隐蔽很多。在一次测试中，我在横屏锁定的状态下拉出系统通知栏，然后再收起，结果页面方向变回了竖屏。当时我的第一反应是“系统重置了方向设置”，但处理方案不是那么简单。

根因在于setPreferredOrientation在系统拉出系统窗口时会被打断，系统窗口关闭后，窗口管理器可能恢复到AUTO策略，而不是回到之前锁定的方向。这个行为在 Android 上也存在（Activity 的 requestedOrientation 在某些场景会被系统改变），但鸿蒙上更容易触发，因为它对窗口栈的管理粒度更细。

我给出的解法是：在windowSizeChange事件里检测当前方向是否和业务预期方向一致，如果不一致就重新调用锁定方法。这里有个关键细节：不要每收到一次事件就重置方向，否则会和用户的旋转操作打架。我采用的方式是，维护一个全局的expectedOrientation变量，在锁定方法里赋值，在windowSizeChange回调里做比对，只有不一致时才重新设置。

private expectedOrientation: window.Orientation | undefined = undefined; lockToLandscape() { this.expectedOrientation = window.Orientation.LANDSCAPE; this.setOrientation(window.Orientation.LANDSCAPE); } private handleWindowSizeChange() { const current = this.mainWindow?.getPreferredOrientation(); if (this.expectedOrientation && current !== this.expectedOrientation) { this.setOrientation(this.expectedOrientation); } }

这个逻辑听起来简单，但它有效解决了系统中断导致的方向丢失问题。我在多个鸿蒙版本上测试过，稳定性完全可接受。

7.3 坑三：首次启动进入页面时白屏 2 秒

“React Native 启动白屏”是热词里反复出现的问题，而我在接入屏幕方向模块后也遇到了。原因是OrientationModule在构造函数里去拿窗口对象并注册监听，这个操作和 RN 的业务 Bundle 加载是并行的，如果窗口对象还没就绪，模块初始化失败，JS 侧调用getOrientation时会抛错，导致页面渲染中断。

不过更常见的情况是，白屏并不是方向模块引起的，而是 RNOH 在鸿蒙上的启动流程本来就比 Android 慢。鸿蒙的容器启动、Native 模块注册、JS Bundle 加载是一个串行链条，任何一个环节变慢都会导致首屏延迟。我建议做三件事：一是确认EntryAbility的onWindowStageCreate里没有做同步耗时操作；二是确认上面的 OrientationModule 初始化不会阻塞 Page 渲染；三是把getOrientation这类 JS 调用延迟到onAfterUpdate或者useEffect里。

如果白屏仍然存在，你可以尝试在module.json5的abilities里加"launchType": "singleton"，让应用启动后保持单实例，避免多次启动时重复初始化窗口监听。

7.4 坑四：getOrientation返回值在部分模拟器上永远是 UNKNOWN

这个坑主要出在鸿蒙模拟器上。部分模拟器版本对getPreferredOrientation的支持不完整，返回的枚举值是UNKNOWN或者AUTO，但模拟器显示的内容却是横屏。这是因为模拟器不依赖真实传感器，方向信息由模拟器配置决定，和窗口管理器的方向策略可能存在不一致。

我在模拟器上排查这个问题的经验是：不要完全依赖getPreferredOrientation判断当前方向，而是结合window.getWindowProperties()里的windowRect来做辅助判断。如果窗口的宽大于高，那基本可以判定为横屏。这个办法虽然粗暴，但在模拟器的特殊环境下非常实用。

getOrientation(): number { if (this.mainWindow) { const props = this.mainWindow.getWindowProperties(); if (props.windowRect.width > props.windowRect.height) { return OrientationType.LANDSCAPE_RIGHT; } return OrientationType.PORTRAIT; } return OrientationType.UNKNOWN; }

这个方案在真机上也没有副作用，因为真机上getPreferredOrientation和物理方向通常是一致的。当然，如果你要处理倒置竖屏这种特殊场景，宽高比判断就不够用了，还是得用系统枚举。

8. 再往深走一步：多窗口、分屏与折叠屏的方向处理

8.1 分屏模式下方向锁失效

分屏是鸿蒙系统里用户很常用的功能，但方向锁定在分屏模式下经常失效，或者说“方向锁定的语义完全变了”。在分屏模式下，系统会把窗口约束在屏幕的一半区域，setPreferredOrientation的作用变成“尽量让窗口区域保持横竖比例”，而不是强制整个屏幕转过去。如果你在业务里期望分屏时也能强制横屏，那是不可能的，因为系统不允许单窗口占用超过它的分屏区域。

我的建议是：分屏场景下不做方向强控，而是让 UI 自适应。如果你做了横屏锁定向，在窗口进入分屏时主动调用unlockAllOrientations解锁，等用户退出分屏后再恢复锁定。这里的核心逻辑就是监听windowSizeChange，判断当前窗口是否处于全屏状态，再决定方向策略。

8.2 折叠屏展开时方向自动切换

折叠屏在展开和折叠的状态切换时，窗口尺寸变化剧烈，方向事件会触发两次甚至三次。如果你在windowSizeChange里做了“恢复方向”的逻辑，一定要加一个时间窗口去重，否则会出现方向来回跳的问题。

我的去重策略是：记录上一次方向重置的时间戳，500 毫秒内不做第二次重置。这个方案在华为 Mate X 系列上实测稳定，但 500 毫秒这个值是经验值，不同设备上你可以微调。

8.3 悬浮窗场景：锁定向能力失效是正常的

悬浮窗模式下，窗口大小完全由用户控制，系统不会响应setPreferredOrientation。我遇到过不少开发者在悬浮窗测试时发现锁定向没用了，误以为代码写错了。这里想明确一下：悬浮窗的方向策略和普通窗口完全不同，如果你的业务支持悬浮窗，方向锁定向只能作用于主窗口，悬浮窗子窗口需要单独写自适应逻辑。

9. 验证方案：自动化检查方向状态的思路

手动验证当然是最直接的，我在真机上一般这样验证：

1. 启动应用，确认默认方向；
2. 调用lockToLandscapeRight，确认页面旋转到右横屏；
3. 调用unlockAllOrientations，物理旋转设备，确认方向跟随传感器变化；
4. 在横屏锁定状态拉出控制中心再关闭，等待 2 秒，确认方向仍然保持横屏；
5. 分屏后再恢复全屏，确认方向策略恢复预期。

如果项目里已经有自动化测试框架（比如 Appium 或 Detox），可以用计步器模拟旋转，断言整个窗口的宽高比变化。考虑到真实场景中出现过控制中心打断方向的情况，自动化的优先级可以适当降低，手动验证反而更够用。

10. 结合我自己的踩坑体会，做几点补充说明

屏幕方向这个模块看着简单，但它背后的窗口管理逻辑在鸿蒙上更新得很快。我在这篇文章里用的是 OpenHarmony 5.0 和 API 12 的组合，如果你用的是更新的 API 版本，window.Orientation枚举或者setPreferredOrientation的语义可能已经变了。建议你在动手前先翻一下当前 SDK 的 API 文档，确认接口没有变化。

另外，如果你只是想在业务项目里快速用上横竖屏控制，不想花时间维护一个完整的 Native Module，也可以考虑用@react-native-ohos/tester社区提供的已适配库列表，但这些库的维护质量参差不齐，我建议你优先看两个指标：是否是 RNOH 官方组织维护的、是否提供了 ArkTS 源码。只有源码级适配的库才值得在生产环境使用。

就我个人的经验来说，把 react-native-orientation 这类基础能力库在鸿蒙上从头桥接一遍，收获远大于直接用现成依赖。你会借此把 RNOH 的模块注册链路、事件传递链路、窗口生命周期管理全部摸透，后面再适配任何第三方原生库都有了清晰的路径。所以这篇文章里我特意把每一步的原理和排查过程都写了进去，目的就是让你不只是在“装一个库”，而是真正理解这条跨端移植的路该怎么走。