React Native for OpenHarmony 横竖屏适配实战指南

一开始我以为在 OpenHarmony 平板上让 React Native 页面支持横竖屏切换，也就是写几行样式、监听一下方向变化的事。毕竟 React Native 在 Android 和 iOS 上的横竖屏适配已经很成熟了，社区里要什么现成方案都有。但真正在 OpenHarmony 设备上跑起来之后，我发现这套经验一半都派不上用场——容器线程怎么重建、布局引擎怎么把宽高传递给 JS 层、设备树选错导致屏幕方向事件压根不触发，这些都是 Android 上根本没见过的坑。

这篇内容写给正在做 React Native for OpenHarmony 适配、或者准备把现有 RN 应用迁移到鸿蒙设备上的同学。我会从渲染链路讲起，然后依次拆解监听方案、布局适配、状态保持，最后把 RK3568 设备树选型和白屏排查这些实战中一定会遇到的坑讲清楚。文章里的代码都是我在真实项目里验证过的，你可以直接照着改。

1. 先摸清虚实：RN for OpenHarmony 的渲染链路与旋转机制

横竖屏切换看似是前端问题，但在 OpenHarmony 上更像一个"宿主环境"问题。不搞明白 RN 在鸿蒙上是怎么把 JS 页面画出来的，后面遇到方向变化时的闪烁、错位、甚至直接白屏，你连排查方向都没有。

1.1 RN 三驾马车：JS 引擎、C++ 桥接与 ArkUI 容器

React Native for OpenHarmony 的架构延续了 RN 经典的"三段式"设计：

• JS 层：你的业务代码、React 组件树、状态管理都跑在 JS 引擎里。OpenHarmony 社区用的是自研的 ArkTS 运行时来承载 JS 逻辑，虽然和 V8/Hermes 不同，但对 RN 应用来说，JS 层面的 API 基本是兼容的。
• C++ 桥接层：负责 JS 层与原生层之间的通信。横竖屏切换时，屏幕宽高的变化就通过这一层从原生传递到 JS 层。
• UI 层：RN 在 OpenHarmony 上最终通过 ArkUI 的 XComponent 或 CustomComponent 来承载渲染内容。ArkUI 的布局引擎负责把 RN 计算出来的布局结果绘制到屏幕上。

方向旋转对这套架构的影响是连锁的：系统屏幕方向变化 → 应用窗口尺寸改变 → ArkUI 容器重新布局 → 宽高数据通过桥接层传递给 JS → Dimensions 触发事件 → React 组件重新渲染。

1.2 为什么 OpenHarmony 上的旋转比 Android 更"伤筋动骨"

Android 上，即使屏幕旋转，Activity 帮你扛住了大部分生命周期问题，RN 的视图树可以原地刷新。但 OpenHarmony 的 UIAbility 生命周期模型不一样，屏幕方向变化在某些场景下会触发 UIAbility 的配置更新，如果 manifest 里没有处理好 orientation 相关配置，整个 RN 实例可能会被重建。

我在项目里遇到的情况是：旋转屏幕后，页面重新加载，JS bundle 重新执行，之前通过 Redux 存在内存里的数据全丢了，页面回到初始状态。这不是代码 bug，是 UIAbility 重新走了一遍 onCreate。

所以在动手写横竖屏适配代码之前，先确认两件事：

1. 模块配置文件 module.json5 里，UIAbility 的 orientation 属性是否声明了可旋转的取值（如 "auto_rotation" 或 "landscape"）。
2. 在 abilities 配置中是否设置了 "orientationChanged" 相关的配置项，让系统知道这个 UIAbility 允许旋转重建。

如果这两步没做对，后面 JS 层写再多判断代码都是白搭，因为根本收不到方向变更的事件。

2. 监听方向变化的四条技术路径与应用取舍

在 OpenHarmony 上监听横竖屏切换，有四种主要方式，但每一种的适用场景和坑都不太一样。我把它们全部列出来，方便你对号入座。

2.1 最优先选择：useWindowDimensions Hook

useWindowDimensions 是 RN 默认提供的 Hook，它会在窗口尺寸变化时自动触发组件渲染。在 OpenHarmony 上，这个 Hook 由 Dimensions 模块驱动，旋转屏幕后，宽高数据更新，Hook 自动返回新值。

typescript复制import { useWindowDimensions } from 'react-native';

function useOrientation() {
  const { width, height } = useWindowDimensions();
  return width > height ? 'LANDSCAPE' : 'PORTRAIT';
}

function GamePage() {
  const orientation = useOrientation();
  return (
    <View style={{ flex: 1, backgroundColor: '#141414' }}>
      {orientation === 'LANDSCAPE' ? (
        <GameBoardHorizontal />
      ) : (
        <GameBoardVertical />
      )}
    </View>
  );
}

这个方案最省心，因为它是"声明式"的：你告诉 React 当前是横屏还是竖屏，React 自动帮你切换视图。但我实测发现一个细节：useWindowDimensions 在旋转过程中可能连续触发多次渲染（表现为宽高中间的过渡态），如果页面里有重组件，会明显卡顿。

优化办法是引入防抖，或者在宽高变化较大时才认为是真正旋转了：

typescript复制import { useEffect, useState } from 'react';
import { useWindowDimensions } from 'react-native';

function useOrientationWithThreshold() {
  const { width, height } = useWindowDimensions();
  const [orientation, setOrientation] = useState<'PORTRAIT' | 'LANDSCAPE'>(
    width > height ? 'LANDSCAPE' : 'PORTRAIT'
  );

  useEffect(() => {
    const isLandscape = width > height;
    // 用 50 的阈值过滤旋转过程中的中间态
    const threshold = Math.abs(width - height) > 50;
    if (threshold) {
      setOrientation(isLandscape ? 'LAND