跳到主要内容
新架构实战课 实操 + 基建 + 原理全维度包揽,抢先掌握 React Native 新架构精髓 立即查看 >

Appendix

注意

这个文档仍然是实验性的,随着我们的迭代,细节会有变化。欢迎在工作小组内的讨论中分享你的反馈。

此外,它还包含几个手动步骤。请注意新架构尚未稳定下来,最终的开发者体验会继续迭代改善。我们正在努力开发工具、模板和库,以帮助你在新架构上快速入门,而不需要经历整个设置过程。

一、术语

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

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

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

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

string

Nullable Support??string
Android (Java)String
iOSNSString

boolean

Nullable Support??boolean
Android (Java)Boolean
iOSNSNumber

对象字面量

比起普通的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
iOSNSArray (or RCTConvertVecToArray when used inside objects)

Function

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

Promise<*>

Nullable Support??Promise<*>
Android (Java)com.facebook.react.bridge.Promise
iOSRCTPromiseResolve 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
iOSRCTResponseSenderBlock
note

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

III. TypeScript 到原生类型映射

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

string

Nullable Support?string | null
Android (Java)String
iOSNSString

boolean

Nullable Support?boolean | null
Android (Java)Boolean
iOSNSNumber

number

Nullable Support?No
Android (Java)double
iOSNSNumber

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
iOSNSArray (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
iOSRCTPromiseResolve 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
iOSRCTResponseSenderBlock

您可能还会发现参考 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 installyarn 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.hMyLibSpecs-generated.mm,以及一些 .h.cpp 文件,全部位于 ios 目录下。

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

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

查找桥接代理

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