Appendix

注意

本文档内容仍处于实验阶段，内容会随着版本的迭代进行修改。您可随时在我们的工作组的讨论区发送反馈。 此外，本文档还包含了若干需手动配置的步骤，但这不代表新架构稳定版的最终开发体验。我们仍在开发相关的工具、模板和第三方库，帮助你更快地迁移到新架构上，而非从头开始配置环境。

一、术语

整个与新架构相关的指南将遵循以下术语：

• 传统原生组件 - 指运行在旧版 React Native 架构上的组件。
• 传统原生模块 - 指运行在旧版 React Native 架构上的模块。
• Fabric 原生组件 - 指已经适配以与新架构（即新渲染器）良好协同工作的组件。为简洁起见，您可能会看到它们被称为Fabric 组件。
• Turbo 原生模块 - 指已经适配以与新架构（即新原生模块系统）良好协同工作的模块。为简洁起见，您可能会看到它们被称为Turbo 模块。

II. Flow 类型到原生类型的映射

您可以使用以下表格作为参考，了解每个平台支持哪些类型以及它们在各个平台上的映射关系：

string

Nullable Support?	?string
Android (Java)	String
iOS	NSString

boolean

Nullable Support?	?boolean
Android (Java)	Boolean
iOS	NSNumber

对象字面量

比起普通的Object来说我们更推荐使用对象字面量，其更具有类型安全性。

示例: {| foo: string, ... |}

Nullable Support?	?{| foo: string, ...|}
Android (Java)	-
iOS	-

Object

note

推荐使用对象字面量。

Nullable Support?	?Object
Android (Java)	ReadableMap
iOS	@ (untyped dictionary)

Array<*>

Nullable Support?	?Array<*>
Android (Java)	ReadableArray
iOS	NSArray (or RCTConvertVecToArray when used inside objects)

Function

Nullable Support?	?Function
Android (Java)	-
iOS	-

Promise<*>

Nullable Support?	?Promise<*>
Android (Java)	com.facebook.react.bridge.Promise
iOS	RCTPromiseResolve and RCTPromiseRejectBlock

类型联合

类型联合仅支持作为回调函数。

Example: 'SUCCESS' | 'FAIL'

Nullable Support?	Only as callbacks.
Android (Java)	-
iOS	-

回调函数

回调函数没有类型检查，并且被泛化为Object。

Example: () =>

Nullable Support?	Yes
Android (Java)	com.facebook.react.bridge.Callback
iOS	RCTResponseSenderBlock

note

您可能还会发现参考 React Native 中核心模块的 JavaScript 规范很有用。这些规范位于 React Native 存储库中的Libraries/目录内。

III. TypeScript 到原生类型映射

您可以使用以下表格作为参考，了解支持的类型以及它们在每个平台上的映射关系：

string

Nullable Support?	string | null
Android (Java)	String
iOS	NSString

boolean

Nullable Support?	boolean | null
Android (Java)	Boolean
iOS	NSNumber

number

Nullable Support?	No
Android (Java)	double
iOS	NSNumber

Object literal

This is recommended over using plain Object, for type safety.

Example: {| foo: string, ... |}

Nullable Support?	{| foo: string, ...|} | null
Android (Java)	-
iOS	-

Object

note

Recommended to use Object literal instead.

Nullable Support?	Object | null
Android (Java)	ReadableMap
iOS	@ (untyped dictionary)

Array<*>

Nullable Support?	Array<*> | null
Android (Java)	ReadableArray
iOS	NSArray (or RCTConvertVecToArray when used inside objects)

Function

Nullable Support?	?Function | null
Android (Java)	-
iOS	-

Promise<*>

Nullable Support?	Promise<*> | null
Android (Java)	com.facebook.react.bridge.Promise
iOS	RCTPromiseResolve and RCTPromiseRejectBlock

Type Unions

Type unions are only supported as callbacks.

Example: 'SUCCESS' | 'FAIL'

Nullable Support?	Only as callbacks.
Android (Java)	-
iOS	-

Callbacks

Callback functions are not type checked, and are generalized as Objects.

Example: () =>

Nullable Support?	Yes
Android (Java)	com.facebook.react.bridge.Callback
iOS	RCTResponseSenderBlock

您可能还会发现参考 React Native 中核心模块的 JavaScript 规范很有用。这些规范位于 React Native 存储库的Libraries/目录内。

IV. 在开发过程中调用代码生成

本节包含特定于 React Native v0.66 的信息。

通常在构建时调用 Codegen，但是您可能会发现按需生成本机接口代码以进行故障排除很有用。

如果您希望手动调用 codegen，有两个选项：

1. 直接调用 Gradle 任务（Android）。
2. 手动调用脚本。

Android - 直接调用 Gradle 任务

您可以通过调用以下任务来触发 Codegen：

./gradlew generateCodegenArtifactsFromSchema --rerun-tasks

额外的 --rerun-tasks 标志被添加以确保 Gradle 忽略对该任务的 UP-TO-DATE 检查。在正常开发过程中，您不应该需要它。

generateCodegenArtifactsFromSchema 任务通常在 preBuild 任务之前运行，因此您不需要手动调用它，但它将在构建之前触发。

手动调用脚本

或者，您可以直接调用 Codegen，绕过 Gradle 插件或 CocoaPods 基础设施。 可以使用以下命令完成此操作。

现在您已经配置了 Gradle 插件或 CocoaPods 库，所以要提供的参数看起来会非常熟悉。

生成模式文件

首先，您需要从 JavaScript 源代码中生成一个模式文件。只有在 JavaScript 规范发生更改时才需要执行此操作。生成此模式的脚本作为react-native-codegen包的一部分提供。如果在 React Native 应用程序内运行此脚本，可以直接使用位于node_modules目录下的该包：

node node_modules/react-native-codegen/lib/cli/combine/combine-js-to-schema-cli.js \
  <output_file_schema_json> <javascript_sources_dir>

react-native-codegen的源代码可在 React Native 存储库中找到，位于packages/react-native-codegen目录下。如果需要从源代码构建自己的react-native-codegen包，请在该目录中运行 yarn install 和 yarn build. 在大多数情况下，您不需要这样做。

生成原生代码构件

一旦您拥有用于本地模块或组件的架构文件，您可以使用第二个脚本为库生成实际的原生代码构件。您可以使用前一个脚本生成的相同架构文件。

node node_modules/react-native/scripts/generate-specs-cli.js \
  --platform <ios|android> \
  --schemaPath <generated_schema_json_file> \
  --outputDir <output_dir> \
  [--libraryName library_name] \
  [--javaPackageName java_package_name] \
  [--libraryType all(default)|modules|components]

注意： Codegen 的输出构件位于 build 文件夹中，不应提交到版本控制系统。 它们仅供参考。

示例

以下是调用 Codegen 脚本的基本示例，用于为提供原生模块的库生成本机 iOS 界面代码。此库的 JavaScript 规范源文件位于js/子目录中，而该库的原生代码期望在ios子目录中可用原生接口。

# 生成模式 - 仅在JS规范更改时需要执行
node node_modules/react-native-codegen/lib/cli/combine/combine-js-to-schema-cli.js /tmp/schema.json ./js

# 生成原生代码构件
node node_modules/react-native/scripts/generate-specs-cli.js \
  --platform ios \
  --schemaPath /tmp/schema.json \
  --outputDir ./ios \
  --libraryName MyLibSpecs \
  --libraryType modules

在上面的示例中，代码生成脚本将会生成几个文件：MyLibSpecs.h 和 MyLibSpecs-generated.mm，以及一些 .h 和 .cpp 文件，全部位于 ios 目录下。

V. 关于现有应用的注意事项

本指南提供了迁移基于 React Native 提供的默认应用模板的应用程序的说明。如果您的应用程序与模板有所偏离，或者您正在使用从未基于该模板构建过的应用程序，则以下部分可能会对您有所帮助。

查找桥接代理

本指南假设AppDelegate被配置为桥接代理。如果您不确定哪个是您的桥接代理，请在RCTBridge和RCTCxxBridge中设置断点，运行您的应用，并检查 self.delegate.