RNSurface

基本介绍

RNSurface 是 React Native 的根容器，它是一个 Native View，用于将 React Native 组件渲染到 Native UI 中。RNSurface 主要负责将组件树渲染到屏幕上。在基于 ArkUI C-API 的适配方案中，rootView 是一个 NodeContent，用于占位，并挂载 C-API 的组件。本节主要介绍了 RNSurface 的接口类型以及使用方式。

其中，Surface 的创建需要调用 RNInstance 的createSurface，并且会在 RNInstance 触发 onDestory 的时候销毁。Surface 会在 RNSurface 的 onAreaChange 中启动（执行 start ），需要注意的是，startSurface 需要在 loadJSbundle 完成后执行，否则会导致页面白屏。您可以通过 RNInstance 的getBundleExecutionStatus获取 bundle 加载状态，确保时序的正确性。

关键参数

参数名	类型	必填	说明
ctx	RNOHContext | RNComponentContext	是	RN 组件上下文。
surfaceConfig	SurfaceConfig	是	surface配置参数。
constraints	Constraints | undefined	否	surface布局约束。

具体使用说明

RNSurface({
  ctx: this.ctx, //RNApp中创建的组件上下文
  surfaceConfig: {
    initialProps: this.initialProps ?? {}, //从RNApp传递来的初始属性
    appKey: this.appKey, //从RNApp传递来的应用名称
  } as SurfaceConfig2,
})

RNSurface 默认情况下会尽可能地填充可用区域，但也可以通过一些方法使其成为自适应容器，由内容决定其高度（宽度仍会尽可能地填充可用区域）。
要使用自适应的 RNSurface，移除对应 JS Bundle 中根容器 AppContainer 的样式中的 flex: 1 属性即可。

方法一

在打包需要使用自适应 RNSurface 特性的 JS Bundle 时，本地修改 node_modules\react-native\Libraries\ReactNative\AppContainer.js 中 AppContainer 的样式。

const styles = StyleSheet.create({
  appContainer: {
-    flex: 1,
  },
});

方法二

直接修改 JS Bundle 中 AppContainer 的样式。

  AppContainer.getDerivedStateFromError = undefined;
  var styles = _StyleSheet.default.create({
    appContainer: {
-      flex: 1
    }
  });
  module.exports = AppContainer;

SurfaceConfig

SurfaceConfig 拥有两个子类： SurfaceConfig1、 SurfaceConfig2，开发者在使用的时候可以根据需要分别选择不同的 config：

SurfaceConfig1

参数名	类型	必填	说明
surfaceHandle	SurfaceHandle	是	表示 RNSurface 的句柄，可由createSurface创建。

SurfaceConfig2

参数名	类型	必填	说明
appKey	string	是	开发者在 JS 侧使用 AppRegistry.registerComponent 注册的名称。
initialProps	Record<string, any>	是	React Native 应用的初始化原生参数。

updateViewRootTag

 public updateViewRootTag: ((rnInstance:RNInstance, rootViewTag: number) => void) | undefined;

返回该 RNSurface 对应的 RNInstance 以及 rootViewTag。

Constraints

参数名	类型	必填	说明
minWidth	number	否	表示 RNSurface 的布局最小宽度。
minHeight	number	否	表示 RNSurface 的布局最小高度。
maxWidth	number	否	表示 RNSurface 的布局最大宽度。
maxHeight	number	否	表示 RNSurface 的布局最大高度。

---

‌React Native on Harmony (RNOH)‌ 框架中关于 ‌RNSurface‌ 的配置和使用说明。

代码类型分析

这不是可执行代码‌，而是 ‌React Native 鸿蒙适配框架的配置文档‌。

核心功能说明

1. RNSurface 定义

根容器角色‌：React Native 组件在鸿蒙平台上的渲染载体
Native View‌：底层的原生视图组件
ArkUI C-API 适配‌：基于鸿蒙 ArkUI 的 C-API 架构实现

2. 技术架构特点

基于 NodeContent 占位‌：在鸿蒙 UI 树中为 RN 组件提供挂载点
生命周期管理‌：与 RNInstance 绑定，自动创建和销毁

3. 关键时序要求

JS Bundle 加载完成前‌：不能执行 startSurface，否则白屏
状态检查机制‌：通过 getBundleExecutionStatus 确保正确时序

4. 配置灵活性

提供两种配置方式：

SurfaceConfig1‌：使用 surfaceHandle（更底层控制）
SurfaceConfig2‌：使用 appKey + initialProps（更便捷）

5. 布局控制

默认行为‌：尽可能填充可用区域
自适应模式‌：移除 flex:1 后由内容决定高度

应用场景

这种架构设计主要服务于：

• React Native 应用‌：在鸿蒙平台的移植和运行
• 跨平台开发‌：保持 RN 开发体验，底层适配鸿蒙

这是一个框架级别的配置说明文档，用于指导开发者如何在鸿蒙平台上正确配置和使用 React Native 的根容器。