RNInstance

基本介绍

RNInstance 是 React Native 的实例，在使用 RN 框架的时候，一定要创建和启动一个或多个RNInstance。RNInstance 负责管理 React Native 的生命周期，维护 React Native 组件树，本节主要介绍了 RNInstance 的接口类型以及使用方式。

RNInstance创建、销毁流程

创建

我们一般使用 RNOHCoreContext 中的 createAndRegisterRNInstance 方法来创建和注册 RNInstance，下面是详细步骤：

1. 应用启动执行 RNAbility 中的 onCreate 方法，创建了 RNInstancesCoordinator 对象实例。该类为 RNInstance 的协调者，引导 React Native 并将设备事件转发给 RNInstance，且这个类是为 UIAbility 的使用而创建的。

   this.rnInstancesCoordinator = RNInstancesCoordinator.create({
     fontSizeScale: this.context.config.fontSizeScale,
     logger: this.createLogger(),
     uiAbilityContext: this.context,
     defaultBackPressHandler: () => {
       this.defaultBackPressHandler()
     },
   }, {
     launchURI: want.uri, onGetPackagerClientConfig: (buildMode) => buildMode === "DEBUG" ? {
       host: "localhost",
       port: 8081
     } : undefined,
     defaultHttpClient: this.onCreateDefaultHttpClient()
   })
   AppStorage.setOrCreate('RNOHCoreContext', this.rnInstancesCoordinator.getRNOHCoreContext())
   

   这时会把 RNOHCoreContext 存储到应用全局，后续可通过 AppStorage.get 方法获取 RNOHCoreContext 实例对象。

2. 在 RNApp 初始化时，会调用 RNOHCoreContext 中的 createAndRegisterRNInstance 方法来创建和注册 RNInstance。

   private getOrCreateRNInstance(): Promise<RNInstance> {
     if (Object.keys(this.rnInstanceConfig).includes("rnInstance")) {
       return Promise.resolve((this.rnInstanceConfig as CustomRNInstance).rnInstance)
     } else {
       const options = this.rnInstanceConfig
       this.shouldDestroyRNInstance = true
       return this.rnohCoreContext!.createAndRegisterRNInstance(options as RNInstanceOptions)
     }
   }
   ...
   this.rnInstance = await this.getOrCreateRNInstance()
   

RNInstanceOptions

参数名	类型	必填	说明
createRNPackages	void	是	外部功能包管理（向框架提供额外的功能特性）。
enableDebugger	boolean	否	是否启动Hermes debugger模式。
enableBackgroundExecutor	boolean	否	是否启动后台线程，建议关闭后台线程。
enableNDKTextMeasuring	boolean	否	是否启用C++原生文本测算接口。
enableImageLoader	boolean	否	是否启动图片缓存。
enableCAPIArchitecture	boolean	否	是否使用CAPI架构，默认开启。
assetsDest	string	否	指定资源文件路径。
arkTsComponentNames	Array	是	ArkTS自定义组件的名称。
hspModuleName	string	否	存放图片资源的HSP模块名称。
backPressHandler	() => void	否	当RN JS端不处理侧滑返回事件时的自定义处理逻辑。
httpClient	HttpClient	否	指定Http客户端处理类。
caPathProvider	(url: string) => string	否	指定CA证书路径规则
fontResourceByFontFamily	Record<string, Resource>	否	注册自定义字体。
jsvmInitOptions	ReadonlyArray	否	JSVM启动项

销毁

RNApp 执行 aboutToDisappear 时，会调用 RNOHCoreContext 的 destroyAndUnregisterRNInstance 方法来销毁 RNInstance。

aboutToDisappear() {
  this.cleanUp()
}

private async cleanUp() {
  const stopTracing = this.logger.clone("cleanUp").startTracing()
  this.shouldShow = false
  if (this.shouldDestroyRNInstance) {
    await this.rnohCoreContext!.destroyAndUnregisterRNInstance(this.rnInstance)
  }
  this.cleanUpCallbacks.forEach(cleanUp => cleanUp())
  stopTracing()
}

关键参数

参数名	类型	说明
descriptorRegistry	DescriptorRegistry	Descriptor注册表，用于管理ArkTS Fabric组件的数据。
cppEventEmitter	EventEmitter<Record<string, unknown[]>>	ArkTS侧订阅CPP侧传过来的消息，并进行处理。
componentManagerRegistry	ComponentManagerRegistry	ArkTS 组件管理注册表。

方法

getLifecycleState()

获取生命周期状态。

返回类型：LifecycleState

枚举值	说明
BEFORE_CREATE	创建前。
PAUSED	暂定。
READY	就绪。

subscribeToLifecycleEvents

subscribeToLifecycleEvents: <TEventName extends keyof LifecycleEventArgsByEventName>(
  eventName: TEventName,
  listener: (...args: LifecycleEventArgsByEventName[TEventName]) => void
) => () => void;

订阅生命周期事件。

参数

参数名	类型	必填	说明
eventName	TEventName	是	事件名称。
listener	void	是	监听回调方法。

callRNFunction

callRNFunction(moduleName: string, functionName: string, args: unknown[]): void

回调 React js 端的函数。

参数

参数名	类型	必填	说明
moduleName	string	是	JavaScript文件的名称。
functionName	string	是	在module中定义的函数名，在JS文件中导出。
args	unknown[]	是	函数应该接收的参数。

emitDeviceEvent

emitDeviceEvent(eventName: string, payload: any): void

向 React js 端的 RCTDeviceEventEmitter 模块的 emit 发送事件件。

参数

参数名	类型	必填	说明
eventName	string	是	事件名称。
payload	any	是	发送的数据。

emitComponentEvent

emitComponentEvent(tag: Tag, eventName: string, payload: any): void

发送组件事件，该事件由 C++ 端的 EventEmitRequestHandler 接收。该处理程序调用组件的 EventEmitter 上的适当方法。

参数

参数名	类型	必填	说明
tag	Tag	是	组件对应的Tag。
eventName	string	是	事件名称。
payload	any	是	发送的数据。

getBundleExecutionStatus

getBundleExecutionStatus(bundleURL: string) : BundleExecutionStatus | undefined

获取 bundle 执行状态，RNApp 用来避免两次加载相同的包。

参数

参数名	类型	必填	说明
bundleURL	string	是	bundle 地址。

返回类型：BundleExecutionStatus | undefined

BundleExecutionStatus 枚举类型。

枚举值	说明
RUNNING	运行中。
DONE	完成。

enableFeatureFlag

enableFeatureFlag(featureFlagName: FeatureFlagName): void

启用特性标志。它可能会在将来被删除，因为通常在创建 RNInstance 时需要提供特性标志。

参数

参数名	类型	必填	说明
featureFlagName	FeatureFlagName	是	特性标识枚举值。

FeatureFlagName枚举类型

枚举值	说明
ENABLE_RN_INSTANCE_CLEAN_UP	启动RNInstance清理。
NDK_TEXT_MEASUREMENTS	使用C++原生测算接口。
IMAGE_LOADER	使用图片缓存。
C_API_ARCH	使用CAPI架构。

isFeatureFlagEnabled

isFeatureFlagEnabled(featureFlagName: FeatureFlagName): boolean

判断给定的特性标识是否开启。

参数

参数名	类型	必填	说明
featureFlagName	FeatureFlagName	是	特性标识枚举值。

runJSBundle

runJSBundle(jsBundleProvider: JSBundleProvider): Promise<void>;

读取 JS Bundle 并执行加载流程。

参数

参数名	类型	必填	说明
jsBundleProvider	JSBundleProvider	是	JS Bundle提供者。

getTurboModule

getTurboModule<T extends TurboModule>(name: string): T

获取对应 TurboModule 实例。

参数

参数名	类型	必填	说明
name	string	是	TurboModule对应名称。