跨平台原生模块（C++）

使用 C++ 编写模块是 Android 和 iOS 之间共享与平台无关代码的最佳方式。借助纯 C++ 模块，你只需编写一次逻辑，就可以立即在所有平台上复用，而无需编写平台特定代码。

在本指南中，我们将逐步创建一个纯 C++ Turbo Native Module：

创建 JS 规格文件
配置 Codegen 生成脚手架
实现原生逻辑
在 Android 和 iOS 应用中注册模块
在 JS 中测试你的更改

本指南的其余部分假设你已经通过运行以下命令创建了应用：

shell
npx @react-native-community/cli@latest init SampleApp --version 0.86

1. 创建 JS 规格文件

纯 C++ Turbo Native Modules 属于 Turbo Native Modules。它们需要一个规格文件（也称为 spec 文件），这样 Codegen 才能为我们创建脚手架代码。规格文件也是我们在 JS 中访问 Turbo Native Module 的方式。

Spec 文件需要使用带类型的 JS 方言编写。React Native 目前支持 Flow 或 TypeScript。

在应用根目录下创建一个名为 specs 的新文件夹。
创建一个名为 NativeSampleModule.ts 的新文件，内容如下：

注意

所有原生 Turbo Module spec 文件都必须以 Native 作为前缀，否则 Codegen 会忽略它们。

TypeScript
Flow

specs/NativeSampleModule.ts
// @flow
import type {TurboModule} from 'react-native'
import { TurboModuleRegistry } from "react-native";

export interface Spec extends TurboModule {
  +reverseString: (input: string) => string;
}

export default (TurboModuleRegistry.getEnforcing<Spec>(
  "NativeSampleModule"
): Spec);

specs/NativeSampleModule.ts
import {TurboModule, TurboModuleRegistry} from 'react-native';

export interface Spec extends TurboModule {
  readonly reverseString: (input: string) => string;
}

export default TurboModuleRegistry.getEnforcing<Spec>(
  'NativeSampleModule',
);

2. 配置 Codegen

下一步是在你的 package.json 中配置 Codegen。将文件更新为包含以下内容：

package.json
     "start": "react-native start",
     "test": "jest"
   },
   "codegenConfig": {
     "name": "AppSpecs",
     "type": "modules",
     "jsSrcsDir": "specs",
     "android": {
       "javaPackageName": "com.sampleapp.specs"
     }
   },
   "dependencies": {

这段配置告诉 Codegen 去 specs 文件夹中查找 spec 文件。它还指示 Codegen 仅为 modules 生成代码，并将生成的代码命名空间设为 AppSpecs。

3. 编写原生代码

编写 C++ Turbo Native Module 可以让你在 Android 和 iOS 之间共享代码。因此，我们只需要编写一次代码，然后再看看需要对各个平台做哪些调整，以便 C++ 代码能够被拾取。

在与 android 和 ios 文件夹同级的位置创建一个名为 shared 的文件夹。

在 shared 文件夹中，创建一个名为 NativeSampleModule.h 的新文件。

shared/NativeSampleModule.h
#pragma once

#include <AppSpecsJSI.h>

#include <memory>
#include <string>

namespace facebook::react {

class NativeSampleModule : public NativeSampleModuleCxxSpec<NativeSampleModule> {
public:
  NativeSampleModule(std::shared_ptr<CallInvoker> jsInvoker);

  std::string reverseString(jsi::Runtime& rt, std::string input);
};

} // namespace facebook::react

在 shared 文件夹中，创建一个名为 NativeSampleModule.cpp 的新文件。

shared/NativeSampleModule.cpp
#include "NativeSampleModule.h"

namespace facebook::react {

NativeSampleModule::NativeSampleModule(std::shared_ptr<CallInvoker> jsInvoker)
    : NativeSampleModuleCxxSpec(std::move(jsInvoker)) {}

std::string NativeSampleModule::reverseString(jsi::Runtime& rt, std::string input) {
  return std::string(input.rbegin(), input.rend());
}

} // namespace facebook::react

让我们看看刚刚创建的这两个文件：

NativeSampleModule.h 文件是纯 C++ TurboModule 的头文件。include 语句确保我们包含由 Codegen 创建的 spec，其中包含我们需要实现的接口和基类。
该模块位于 facebook::react 命名空间中，以便访问该命名空间中的所有类型。
NativeSampleModule 类就是实际的 Turbo Native Module 类，它继承自 NativeSampleModuleCxxSpec 类；该类包含一些胶水代码和样板代码，使这个类能够作为 Turbo Native Module 工作。
最后，我们有构造函数，它接受一个指向 CallInvoker 的指针，以便在需要时与 JS 通信，以及我们必须实现的函数原型。

NativeSampleModule.cpp 文件是我们的 Turbo Native Module 的实际实现，它实现了构造函数以及我们在 spec 中声明的方法。

4. 在平台中注册模块

接下来的步骤将让我们在平台中注册该模块。这一步会将原生代码暴露给 JS，这样 React Native 应用最终就可以从 JS 层调用原生方法了。

这是我们唯一一次需要编写平台特定代码。

Android

为了确保 Android 应用可以正常构建 C++ Turbo Native Module，我们需要：

创建一个 CMakeLists.txt 以访问我们的 C++ 代码。
修改 build.gradle，指向新创建的 CMakeLists.txt 文件。
在 Android 应用中创建一个 OnLoad.cpp 文件来注册新的 Turbo Native Module。

1. 创建 `CMakeLists.txt` 文件

Android 使用 CMake 进行构建。CMake 需要访问我们在 shared 文件夹中定义的文件，才能构建它们。

创建一个新文件夹 SampleApp/android/app/src/main/jni。jni 文件夹是 Android 的 C++ 侧所在的位置。
创建一个 CMakeLists.txt 文件并添加以下内容：

CMakeLists.txt
cmake_minimum_required(VERSION 3.13)

# 在这里定义库名。
project(appmodules)

# 此文件包含构建 React Native 应用所需的全部内容
include(${REACT_ANDROID_DIR}/cmake-utils/ReactNative-application.cmake)

# 定义附加源代码所在位置。我们需要从 jni、main、src、app、android 文件夹逐级返回
target_sources(${CMAKE_PROJECT_NAME} PRIVATE ../../../../../shared/NativeSampleModule.cpp)

# 定义 CMake 可以找到附加头文件的位置。同样需要从 jni 文件夹逐级返回
target_include_directories(${CMAKE_PROJECT_NAME} PUBLIC ../../../../../shared)

CMake 文件执行以下操作：

定义 appmodules 库，所有应用的 C++ 代码都将包含在这里。
加载 React Native 的基础 CMake 文件。
使用 target_sources 指令添加我们需要构建的模块 C++ 源代码。默认情况下，React Native 已经会用默认源文件填充 appmodules 库，这里我们加入自定义源文件。你可以看到，我们需要从 jni 文件夹一路返回到 shared 文件夹，也就是 C++ Turbo Module 所在的位置。
指定 CMake 可以在哪里找到模块头文件。在这种情况下同样需要从 jni 文件夹逐级返回。

2. 修改 `build.gradle` 以包含自定义 C++ 代码

Gradle 是协调 Android 构建的工具。我们需要告诉它在哪里可以找到用于构建 Turbo Native Module 的 CMake 文件。

打开 SampleApp/android/app/build.gradle 文件。
在现有的 android 块中添加以下代码块：

android/app/build.gradle
    buildTypes {
        debug {
            signingConfig signingConfigs.debug
        }
        release {
            // 注意！在生产环境中，你需要生成自己的 keystore 文件。
            // 参见 https://reactnative.dev/docs/signed-apk-android。
            signingConfig signingConfigs.debug
            minifyEnabled enableProguardInReleaseBuilds
            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"
        }
    }

+   externalNativeBuild {
+       cmake {
+           path "src/main/jni/CMakeLists.txt"
+       }
+   }
}

这个代码块告诉 Gradle 文件去哪里查找 CMake 文件。路径是相对于 build.gradle 文件所在文件夹的，所以我们需要添加到 jni 文件夹中 CMakeLists.txt 文件的路径。

3. 注册新的 Turbo Native Module

最后一步是将新的 C++ Turbo Native Module 注册到运行时中，这样当 JS 请求这个 C++ Turbo Native Module 时，应用就知道去哪里找到它并返回它。

在 SampleApp/android/app/src/main/jni 文件夹中，运行以下命令：

shell
curl -O https://raw.githubusercontent.com/facebook/react-native/v0.86.0/packages/react-native/ReactAndroid/cmake-utils/default-app-setup/OnLoad.cpp

然后按如下方式修改此文件：

android/app/src/main/jni/OnLoad.cpp
#include <DefaultComponentsRegistry.h>
#include <DefaultTurboModuleManagerDelegate.h>
#include <autolinking.h>
#include <fbjni/fbjni.h>
#include <react/renderer/componentregistry/ComponentDescriptorProviderRegistry.h>
#include <rncore.h>

+ // 引入 NativeSampleModule 头文件
+ #include <NativeSampleModule.h>

//...

std::shared_ptr<TurboModule> cxxModuleProvider(
    const std::string& name,
    const std::shared_ptr<CallInvoker>& jsInvoker) {
  // 这里你可以提供来自
  // 你的应用或外部库的 CXX Turbo Modules。可遵循如下方式（以名为 `NativeCxxModuleExample` 的模块为例）：
  //
  // if (name == NativeCxxModuleExample::kModuleName) {
  //   return std::make_shared<NativeCxxModuleExample>(jsInvoker);
  // }

+  // 这段代码会注册该模块，以便当 JS 端请求它时，应用可以返回它
+  if (name == NativeSampleModule::kModuleName) {
+    return std::make_shared<NativeSampleModule>(jsInvoker);
+  }

  // 其余则回退到自动链接的 CXX 模块提供者
  return autolinking_cxxModuleProvider(name, jsInvoker);
}

// 保留文件其余部分

这些步骤会从 React Native 下载原始的 OnLoad.cpp 文件，这样我们就可以安全地覆盖它，在应用中加载 C++ Turbo Native Module。

下载文件后，我们可以对其进行如下修改：

引入指向我们模块的头文件
注册 Turbo Native Module，这样当 JS 需要它时，应用就可以返回它

现在，你可以从项目根目录运行 yarn android 来查看你的应用是否成功构建。

iOS

为了确保 iOS 应用可以正常构建 C++ Turbo Native Module，我们需要：

安装 pods 并运行 Codegen。
将 shared 文件夹添加到 iOS 项目中。
在应用中注册 C++ Turbo Native Module。

1. 安装 Pods 并运行 Codegen。

我们需要运行的第一步，就是每次准备 iOS 应用时都会执行的常规步骤。CocoaPods 是我们用来设置和安装 React Native 依赖的工具，在这个过程中，它也会替我们运行 Codegen。

cd ios
bundle install
bundle exec pod install

2. 将 shared 文件夹添加到 iOS 项目

这一步会把 shared 文件夹添加到项目中，使其在 Xcode 中可见。

打开 CocoaPods 生成的 Xcode Workspace。

cd ios
open SampleApp.xcworkspace

点击左侧的 SampleApp 项目，并选择 Add files to "Sample App"...。

Add Files to Sample App...

选择 shared 文件夹并点击 Add。

Add Files to Sample App...

如果你都做对了，左侧的项目应该会像这样：

Xcode Project

3. 在你的应用中注册 Cxx Turbo Native Module

要在你的应用中注册一个纯 Cxx Turbo Native Module，你需要：

为该原生模块创建一个 ModuleProvider
配置 package.json，将 JS 模块名与 ModuleProvider 类关联起来。

ModuleProvider 是一个 Objective-C++ 文件，它将纯 C++ 模块与 iOS 应用的其余部分连接起来。

3.1 创建 ModuleProvider

在 Xcode 中，选择 SampleApp 项目并按 ⌘ + N 创建一个新文件。
选择 Cocoa Touch Class 模板
添加名称 NativeSampleModuleProvider（保持另一个字段为 Subclass of: NSObject 和 Language: Objective-C）
点击 Next 生成文件。
将 NativeSampleModuleProvider.m 重命名为 NativeSampleModuleProvider.mm。mm 扩展名表示这是一个 Objective-C++ 文件。
按如下内容实现 NativeSampleModuleProvider.h：

NativeSampleModuleProvider.h

#import <Foundation/Foundation.h>
#import <ReactCommon/RCTTurboModule.h>

NS_ASSUME_NONNULL_BEGIN

@interface NativeSampleModuleProvider : NSObject <RCTModuleProvider>

@end

NS_ASSUME_NONNULL_END

这声明了一个符合 RCTModuleProvider 协议的 NativeSampleModuleProvider 对象。

按如下内容实现 NativeSampleModuleProvider.mm：

NativeSampleModuleProvider.mm

#import "NativeSampleModuleProvider.h"
#import <ReactCommon/CallInvoker.h>
#import <ReactCommon/TurboModule.h>
#import "NativeSampleModule.h"

@implementation NativeSampleModuleProvider

- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
    (const facebook::react::ObjCTurboModule::InitParams &)params
{
  return std::make_shared<facebook::react::NativeSampleModule>(params.jsInvoker);
}

@end

这段代码通过在调用 getTurboModule: 方法时创建纯 C++ NativeSampleModule，实现了 RCTModuleProvider 协议。

3.2 更新 package.json

最后一步是更新 package.json，告诉 React Native JS 规格文件中的原生模块名称与原生代码中具体实现之间的对应关系。

将 package.json 修改为如下所示：

package.json
     "start": "react-native start",
     "test": "jest"
   },
   "codegenConfig": {
     "name": "AppSpecs",
     "type": "modules",
     "jsSrcsDir": "specs",
     "android": {
       "javaPackageName": "com.sampleapp.specs"
     },
     "ios": {
        "modulesProvider": {
          "NativeSampleModule":  "NativeSampleModuleProvider"
        }
     }
   },

   "dependencies": {

此时，你需要重新安装 pods，以确保 codegen 再次运行并生成新文件：

# 从 ios 文件夹执行
bundle exec pod install
open SampleApp.xcworkspace

如果你现在从 Xcode 构建应用，应该可以成功构建。

5. 测试你的代码

现在是时候从 JS 中访问我们的 C++ Turbo Native Module 了。为此，我们需要修改 App.tsx 文件，导入 Turbo Native Module，并在代码中调用它。

打开 App.tsx 文件。
将模板中的内容替换为以下代码：

App.tsx
import {type JSX, useState} from 'react';
import {
  Button,
  SafeAreaView,
  StyleSheet,
  Text,
  TextInput,
  View,
} from 'react-native';
import SampleTurboModule from './specs/NativeSampleModule';

function App(): JSX.Element {
  const [value, setValue] = useState('');
  const [reversedValue, setReversedValue] = useState('');

  const onPress = () => {
    const revString = SampleTurboModule.reverseString(value);
    setReversedValue(revString);
  };

  return (
    <SafeAreaView style={styles.container}>
      <View>
        <Text style={styles.title}>
          欢迎来到 C++ Turbo Native Module 示例
        </Text>
        <Text>在这里输入你想要反转的文本</Text>
        <TextInput
          style={styles.textInput}
          placeholder="在这里输入你的文本"
          onChangeText={setValue}
          value={value}
        />
        <Button title="反转" onPress={onPress} />
        <Text>反转后的文本：{reversedValue}</Text>
      </View>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  title: {
    fontSize: 18,
    marginBottom: 20,
  },
  textInput: {
    borderColor: 'black',
    borderWidth: 1,
    borderRadius: 5,
    padding: 10,
    marginTop: 10,
  },
});

export default App;

这个应用中比较有意思的几行是：

import SampleTurboModule from './specs/NativeSampleModule';：这一行将 Turbo Native Module 导入到应用中，
const revString = SampleTurboModule.reverseString(value); 位于 onPress 回调中：这就是你在应用中使用 Turbo Native Module 的方式。

注意

为了这个示例并尽可能保持简短，我们直接在应用中导入了 spec 文件。在这种情况下，最佳实践是创建一个单独的文件来封装这些 spec，并在应用中使用那个文件。这样可以让你为 spec 准备输入，并且在 JS 中对它们拥有更多控制。

恭喜你，你已经编写了你的第一个 C++ Turbo Native Module！

Android	iOS

1. 创建 JS 规格文件​

2. 配置 Codegen​

3. 编写原生代码​

4. 在平台中注册模块​

Android​

1. 创建 CMakeLists.txt 文件​

2. 修改 build.gradle 以包含自定义 C++ 代码​

3. 注册新的 Turbo Native Module​

iOS​

1. 安装 Pods 并运行 Codegen。​

2. 将 shared 文件夹添加到 iOS 项目​

3. 在你的应用中注册 Cxx Turbo Native Module​

3.1 创建 ModuleProvider​

3.2 更新 package.json​

5. 测试你的代码​