★ FEATURED ARTICLE OpenHarmony移动开发跨平台【免费下载链接】ohos_react_nativeReact Native鸿蒙化仓库项目地址https://gitcode.com/CPF-RN/ohos_react_native点击查看免费下载导读本文基于 docs/zh-cn/05-运维/上游社区不兼容变更.md 整理系统梳理 React Native 社区facebook/react-native从 0.73 到 0.77 期间引入的 24 项不兼容变更逐条说明其变更来源版本、对鸿蒙化开发者的具体影响以及影响场景。这些变更分布在 JS/TS 前端代码、原生 C 适配层、构建配置与运行时行为四个层面是 RNOHReact Native for OpenHarmony即react-native-oh/react-native-harmony开发者升级版本时必须对照检查的清单。读完本文你将掌握每项变更的成因、报错特征与推荐迁移写法并能结合本仓库源码证据完成自查。适用范围说明本仓库当前发布的 RNOH 版本基于社区RN 0.86.3进行适配见 版本说明 与 release-notes/react-native-harmony-v0.86.1.mdreact-native-harmony包的peerDependencies声明为react-native: 0.86.3见 packages/react-native-harmony/package.json。因此下文涉及的 0.73~0.77 社区变更均已越过鸿蒙化当前基线开发者从旧版本如 0.72、0.74升级到 0.86 基线时需逐条核对。一、为什么要跟踪上游社区不兼容变更React Native 的版本演进频繁社区在修复缺陷、重构架构时常常会删除或重命名 API、收紧类型检查、改变事件时序。这些变更对 Android/iOS 原生侧可能是透明的但对鸿蒙化适配层C 层RNOH代码、Codegen 生成的 TurboModule、JS 侧 polyfill却可能造成编译失败、打包失败或运行时行为偏差。本仓库在 docs/zh-cn/05-运维/README.md 中将 上游社区不兼容变更 归类为版本相关文档以 ⚡ 标记意味着它需要随版本发布同步更新与 RN升级需要开发者适配整理.md、稳定版本识别与安装.md、版本升级指导.md 共同构成升级适配的完整文档链。英文读者可对照同源文档 upstream-community-incompatible-changes.md该英文版记录了 22 条变更中文版在此基础上新增了RN 剪贴板 API 支持问题与移除 Metro 中的 console.log() 流式传输两条。影响场景总览影响维度涉及变更序号典型报错表现前端 JS/TS 代码编译#2、#3、#17、#20、#22TS2749 类型错误、bundle 打包报错原生 C 适配层编译#1、#4、#5、#7、#9、#18、#21编译失败、找不到符号构建/依赖配置#13、#14、#16、#19打包失败、so 集成问题运行时行为#6、#8、#23、#24列表锚点不稳、onLayout 时序变化性能与渲染#10、#11、#12、#15编译失败标志位/API 被移除二、影响前端 JS/TS 代码的变更开发态需改代码这类变更最容易被开发者直接感知因为报错发生在自己写的业务代码或依赖的三方库中。2.1 TouchableHighlight 不能再作为类型引用#20.75.0上游修正了TouchableHighlight的 ref 类型它本质是 View 的包装只能通过React.ElementReftypeof TouchableHighlight或View来引用不能再用TouchableHighlight本身作为useRef的类型参数。// ❌ 0.75.0 之后会报 TS2749 import {TouchableHighlight} from react-native; const ref useRefTouchableHighlight(); // TS2749: TouchableHighlight refers to a value, but is being used as a type here. // Did you mean typeof TouchableHighlight? // ✅ 推荐使用内置 RN 类型 React.ElementRef const ref useRefReact.ElementReftypeof TouchableHighlight(); // ✅ 备选直接用 View 作为类型 const ref useRefView();排查建议全局搜索useRefTouchableHighlight、useRefTouchableOpacity等写法尤其注意第三方 UI 库内部实现鸿蒙化场景下 RNOH 对 Touchable 系列组件的实现位于 packages/react-native-harmony/Libraries/Components/Touchable业务侧直接使用即可无需自行包装。2.2 TurboModule codegen 方法入参检查更严格#30.75.0在 NativeModule 中如果 codegen 方法定义为someMethod(value?: number): void;以前调用NativeModule.someMethod(null)不会报错0.75.0 之后向不接受 null 的函数传入 null 会报错。排查建议检查项目内所有 TurboModule 调用凡是 codegen 签名里参数不是?可空类型、也未用| null联合类型声明的调用时一律不要传null。RNOH 的 Codegen 工具链位于 packages/react-native-harmony-cli/src/codegen生成代码时同样会按上游规范收紧入参类型。2.3 TS 对 style 中 transform 语法检查更严格#170.73.0// ❌ 0.73.0 之后报错 View style{{transform: [{scale: 1, translateX: 1}]}} / // ✅ transform 数组内每个元素只能包含一个 transform 属性 View style{{transform: [{scale: 1}, {translateX: 1}]}} /影响打 JS bundle 失败报错Metro 调试运行时可能红屏。排查时可先搜索transform: [{开头且单个对象内含多个键的写法。2.4 JSX 中字典类型参数用逗号分隔多个字典#200.76.0// ❌ 不合法写法0.76.0 及以上 react-native/babel-preset 打包报错 View style{{key1: value1}, {key2: value2}} / // ✅ 正确写法 View style{{key1: value1, key2: value2}} /说明这种写法本身就不是合法的 tsx即使老版本不报构建错误也只有最后一个字典实际生效属于历史遗留的隐性 bug。0.76.0 之后 Babel 会直接报错开发者应顺手修正为合法的对象字面量写法。2.5 View Manager 定义不再支持 tsx 文件类型#220.73.0react-native/babel-preset引入react-native/babel-plugin-codegen插件后会校验 View Manager 定义文件的类型只支持.ts不支持.tsx。报错信息形如error xx.tsx: xx.tsx: Unable to parse file xx.tsx. Unsupported filename extension.排查建议把自定义 View Manager含 codegen 指令的组件定义文件后缀从.tsx改为.ts。仓库中规范的 View Manager 定义可参考 react-native-harmony-sample-package/src/specs 下各 spec 文件均为.ts。2.6 RN 剪贴板 API 废弃公告#23无版本号社区已公告剪贴板Clipboard接口废弃。使用剪贴板 API 的开发者需关注相关公告并及时迁移避免后续版本彻底移除后出现运行期崩溃。2.7 三方库 Flow 类型定义不再随 react-native 包发布#160.73.0上游将package/react-native/flow-typed/目录迁移至社区仓库react-native包不再包含部分三方库的 Flow 语法定义。引用这部分依赖时需改用新的路径。影响打 JS bundle 失败报错Metro 调试运行时可能红屏。排查方向检查node_modules/react-native/flow-typed/是否缺失以及业务/三方库中是否有flow-typed路径引用。三、影响原生 C 适配层的变更编译失败类这类变更主要影响自研 ScrollView、自封装组件、TurboModule 或直接使用react-native-harmony原生层 API 的开发者。仓库中的 C 适配层源码位于 packages/tester/harmony/react_native_openharmony/src/main/cppRNOH 实现与 packages/tester/harmony/react_native_openharmony/src/main/cpp/testsC-API stub 与单测。3.1 ScrollViewShadowNode 的 getContentOriginOffset 增加入参#10.74.0-rc4上游为getContentOriginOffset增加入参用于修复反转的 FlatList 无法滚动的问题。对开发者如果自行对 ScrollView 做了适配并调用getContentOriginOffset需要新增一个布尔值入参includeTransform用于判断是否考虑 style 中设置的transform// 旧签名示意 offset getContentOriginOffset() const; // 新签名增加 includeTransform判断是否考虑 style 中的 transform offset getContentOriginOffset(bool includeTransform) const;影响场景开发态——自定义 ScrollView 组件代码能否正常编译运行态——反转后的 FlatList 能否正常滑动。RNOH 中 ScrollView 组件实现位于 packages/react-native-harmony/Libraries/Components/ScrollView若是基于社区默认实现则无需处理只有自行继承/包装 ShadowNode 的项目需要关注。3.2 JsErrorHandler 回调类型更名#40.75.0C 侧JsErrorHandler::JsErrorHandlingFunc类型更名为JsErrorHandler::OnJsError。原来在RNInstance等类中以JsErrorHandler::JsErrorHandlingFunc类型注册 JS 错误回调的地方需改为JsErrorHandler::OnJsError。仓库中 RNOH 的 C-API stub 已按新类型组织错误处理参见 packages/tester/harmony/react_native_openharmony/src/main/cpp/tests/rni_capi_stubs/jserrorhandler/JsErrorHandler.h 及同目录下的rni_capi_stubs、mm_capi_stubs、mock/stubs三套测试替身均以OnJsError命名——这正体现了鸿蒙化适配层对上游 0.75.0 变更的同步。影响场景开发态编译失败运行态不受影响。3.3 ReactPrimitives.h 删除多余 include#50.75.0从ReactPrimitives.h中删除了folly/dynamic.h和memory的 include。若项目代码 include 了ReactPrimitives.h且依赖其间接引入的folly::dynamic或std::内存相关符号可能编译失败——只要通过编译就不存在问题若构建失败需在对应文件中显式 include 相应头文件。3.4 SyncCallback 禁止拷贝#70.75.0SyncCallback对象禁止拷贝新增了 move 支持。复制SyncCallback的代码将无法通过编译只需要一个回调对象改为 move需要多个回调创建多个。特别注意SyncCallback只能在独占 JS 引擎上下文中执行错误的使用方式可能导致崩溃。这是运行态风险点鸿蒙化场景下 JS 引擎为 Hermes涉及跨线程同步回调时需格外注意上下文约束。3.5 Animation 的__onEnd不再暴露给子类#90.77.0-rc.0子类应使用__debouncedOnEnd代替__onEnd。影响为编译不通过运行态不受影响。RNOH 的 Animated 实现与测试位于 packages/react-native-harmony/src/private/animated开发者如自定义 Animated 子类需同步调整。3.6 移除 YOGA 枚举与 CSS 属性#180.73.0移除 YOGA 中的枚举值YGExperimentalFeatureFixAbsoluteTrailingColumnMargin社区同时去除了fix-absolute-trailing-column-margin这个 CSS 属性。影响使用该被删除枚举值会编译报错fix-absolute-trailing-column-margin属性的移除可能导致组件布局发生变化。影响场景为开发态编译失败 运行态布局变化属于少数运行态也有影响的编译类变更。3.7 移除 butter 组件#210.73.0移除了ReactCommon中的butter组件C 代码中butternamespace 下所有符号不再可用需参考butter的实现进行替换一般可用folly或标准库等价能力替代。影响为编译报错。3.8 so 列表发生变化#190.76.0RN 0.76.0 起 so共享库列表发生变化可能影响开发者 CMakeLists 中集成 so 的配置导致编译不通过。原文档备注目前 0.77 版本 release 包尚未构建文档待方案确定后给出对于当前仓库的 0.86 基线RNOH 的依赖与构建配置请以 packages/react-native-harmony/package.jsonscripts.build通过 scripts/build-har.js 产出 har 包以及 tester 工程的 CMake 配置为准升级时核对 so 清单与 CMakeLists 的对应关系。四、构建配置与依赖相关的变更打包失败类4.1 移除 react-native-community 相关直接依赖#13、#140.76.0#130.76.0-rc.1移除react-native-community/cli的直接依赖#140.76.0-rc.0移除react-native-community的直接依赖。影响打包失败开发态编译失败运行态不受影响。若项目代码中直接 import 了react-native-community/*包如react-native-community/cli需改为显式声明为项目自己的依赖。仓库中 RNOH CLI 的实现独立维护在 packages/react-native-harmony-cli其package.json中显式声明了自身依赖不依赖 react-native 包间接传递这正是社区移除直接依赖后鸿蒙化侧的正确做法。4.2 enableOptimisedVirtualizedCells 标志位被移除#100.77.0-rc.0该标志位从代码层面移除默认效果由 false 变更为 true即虚拟化列表的优化单元始终开启。影响若业务/三方库仍引用该标志位则编译失败运行态为性能优化。仓库 JS 侧 feature flags 机制的实现与测试位于 packages/react-native-harmony/src/private/featureflags/tests/ReactNativeFeatureFlags-rnoh-test.js其测试验证了原生模块可用但方法未定义时提供默认值原生模块不可用时提供默认值等行为——即 feature flag 缺失时不会崩溃、回退到默认值这与上游移除标志位后的降级策略一致。4.3 concurrentRoot 启动项被移除#110.77.0-rc.0ConcurrentRoot不再用于决定是否以并发模式运行应用新架构下并发模式恒开启。引用该启动项的代码编译失败运行态不受影响。RNOH 的 RNInstance 启动参数以 C/ArkTS 对接升级时需移除对concurrentRoot的显式设置。4.4 移除 NativeMethods 中与 refs 相关的配置#120.77.0-rc.0字符串 refs 被废弃因此移除了NativeMethods的相关配置。引用被移除配置的代码编译失败运行态不受影响。React 19 之后字符串 refs 已不可用改用React.createRef()或回调 ref。4.5 渲染相关的三个特性 flag 默认值改为开启#150.74.1-rc0渲染相关的三个特性 flag 默认值由关闭改为开启开启后可打断渲染循环并响应 JS 事件即渲染不再阻塞 JS 事件处理。影响引用旧默认值的配置代码编译失败运行态为性能优化。这与 feature flags 机制强相关——仓库中ReactNativeFeatureFlags的默认值回退逻辑原生模块缺失时按默认值返回见上文测试文件保证了鸿蒙化侧在这些 flag 被上游移除/改默认值时依然行为可控。五、运行时行为类变更无感但需回归验证5.1 部分可见元素可以作为列表锚点#60.75.0旧实现只有完全展示的元素才能作为列表锚点变更后部分可见的元素也可以作为列表锚点。其目的是避免加载指示器等在列表中完全展示、但位置显隐状态不稳定的元素被选为锚点后导致列表展示不稳定。对开发者开发态无影响但建议测试列表加载新元素场景如onEndReached触发的分页加载确认列表行为仍符合预期——这是典型的需要回归验证的变更。5.2 组件 onLayout 事件优先级降低#80.74.0将组件onLayout事件的优先级由可配置异步批量/异步不批量改为固定异步批量。影响onLayout事件及时性变差依赖该回调进行动画或布局调整的场景动作时机可能受影响此外应关注onLayout与临近生命周期函数如componentDidUpdate之间的执行顺序。这是纯运行时变更开发者需审视对onLayout时序敏感的逻辑。5.3 移除 Metro 中 console.log() 流式传输#240.77.00.76 起废弃 Metro 的 console.log 流式传输机制log forwarding via Metro通过自定义通信通道向设备转发 console.log0.77 正式移除移除后改用Chrome DevTools ProtocolCDP统一处理日志。动机旧机制在 Fast Refresh 重新执行入口文件时会导致console.log多次打印。移除后Fast Refresh 触发时入口文件中的console.log不再重复打印。对开发者查看 JS 日志应改用 React Native DevTools 的 Console 面板或 CDP 调试器不再依赖 Metro 的 log streaming。开发态无影响运行态为 Fast Refresh 时console.log不再重复打印。六、开发者自查清单与升级路径6.1 按变更类别建立自查清单升级前建议按以下顺序逐项核对搜索代码关键字useRefTouchableHighlight、someMethod(null)、transform: [{scale:、style{{逗号字典、.tsx结尾的 View Manager spec、butter::、YGExperimentalFeatureFixAbsoluteTrailingColumnMargin、getContentOriginOffset、JsErrorHandlingFunc、concurrentRoot、enableOptimisedVirtualizedCells核对依赖确认项目是否直接引用react-native-community/*且未在自身package.json中显式声明回归测试重点场景列表加载新元素#6、onLayout驱动的动画/布局#8、Fast Refresh 日志#24、反转 FlatList 滚动#1关注废弃公告剪贴板 API#23需按社区公告规划迁移。6.2 升级时配合使用的仓库文档版本选型与安装稳定版本识别与安装.md选择接入版本时首读版本发布记录版本说明.md 与 release-notes/react-native-harmony-v0.86.1.md查看当前 0.86 基线的变更对齐上游 0.86.3、edge-to-edge 支持、DevTools 改进等升级操作步骤版本升级指导.mdAPI 变更适配总表RN升级需要开发者适配整理.md与本文的上游社区不兼容变更互为补充前者是 RNOH 自身 API 变化后者是社区上游变化构建配置hvigorfile配置.md 与 RN-JS打包.md处理打包失败类变更。6.3 验证仓库源码基线JS 侧源码与 polyfillpackages/react-native-harmony/src/private含 feature flags、Animated、渲染错误处理等模块及其测试组件实现packages/react-native-harmony/Libraries含 Components、Animated、Image 等C 适配层packages/tester/harmony/react_native_openharmony/src/main/cppRNOH 原生实现CLI 与 Codegenpackages/react-native-harmony-cli/srcautolinking、codegen、init 等子模块。注意仓库中的packages/react-native目录为上游子模块占位当前未初始化内容实际 JS 运行时代码由react-native-harmony包提供其package.json的peerDependencies声明依赖社区react-native0.86.3。因此排查上游 API 行为时应以react-native-harmony内的实现与测试为准。七、结语上游社区不兼容变更的影响可分为四类JS/TS 代码编译、C 适配层编译、构建配置依赖、运行时行为。其中绝大多数影响集中在开发态编译失败真正影响运行态行为的是列表锚点#6、onLayout 时序#8与日志通道#24等少数几项。开发者升级 RNOH 时将本文的 24 条清单与仓库内的 feature flags 测试、C-API stub、release notes 对照核查即可在编译阶段提前拦截大部分风险把运行时回归测试聚焦到列表加载、布局回调与调试日志这几个高价值场景上。输出文章赞分享OpenHarmony移动开发跨平台【免费下载链接】ohos_react_nativeReact Native鸿蒙化仓库项目地址https://gitcode.com/CPF-RN/ohos_react_native点击查看免费下载相关推荐上游社区不兼容变更梳理鸿蒙化 React Native 升级适配指南上游社区不兼容变更梳理鸿蒙化 React Native 升级适配指南 本指南以 ohos_react_native 仓库中 上游社区不兼容变更.md httpOpenHarmony移动开发跨平台如何在手机上实时监控您的卡车仪表盘ETS2 Telemetry Server完全指南如何在手机上实时监控您的卡车仪表盘ETS2 Telemetry Server完全指南 您是否梦想过将手机变成专业的卡车仪表盘实时查看欧洲卡车模拟2ETS2后端WebSocketReact Native 鸿蒙化RNOH升级适配指南从 v0.59 到 v0.72 的版本变更与开发者迁移要点React Native 鸿蒙化RNOH升级适配指南从 v0.59 到 v0.72 的版本变更与开发者迁移要点 本文是面向 React Native 鸿蒙OpenHarmony移动开发跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
