高级：自定义 C++ 类型

注意

本指南假设您熟悉纯 C++ Turbo 原生模块指南。本指南将在此基础上进行构建。

C++ Turbo 原生模块支持桥接功能，适用于大多数std::标准类型。您可以在模块中使用大多数这些类型，而无需任何额外的代码。

如果您想在您的应用或库中添加对新类型和自定义类型的支持，则需要提供必要的bridging头文件。

添加新的自定义类型：Int64

C++ Turbo 原生模块尚不支持int64_t数字 - 因为 JavaScript 不支持大于 2^53 的数字。为了表示大于 2^53 的数字，我们可以在 JS 中使用string类型，并在 C++ 中自动将其转换为int64_t。

1. 创建桥接头文件

支持新自定义类型的第一步是定义桥接头文件，该文件负责将类型从 JS 表示形式转换为 C++ 表示形式，以及从 C++ 表示形式到 JS 表示形式。

1. 在shared文件夹中，添加一个名为Int64.h的新文件。
2. 将以下代码添加到该文件中。

Int64.h

#pragma once

#include <react/bridging/Bridging.h>

namespace facebook::react {

template <>
struct Bridging<int64_t> {
  // Converts from the JS representation to the C++ representation
  static int64_t fromJs(jsi::Runtime &rt, const jsi::String &value) {
    try {
      size_t pos;
      auto str = value.utf8(rt);
      auto num = std::stoll(str, &pos);
      if (pos != str.size()) {
        throw std::invalid_argument("Invalid number"); // don't support alphanumeric strings
      }
      return num;
    } catch (const std::logic_error &e) {
      throw jsi::JSError(rt, e.what());
    }
  }

  // Converts from the C++ representation to the JS representation
  static jsi::String toJs(jsi::Runtime &rt, int64_t value) {
    return bridging::toJs(rt, std::to_string(value));
  }
};

}

自定义桥接头文件的主要组件是

• 自定义类型的Bridging结构的显式特化。在本例中，模板指定了int64_t类型。
• 一个fromJs函数，用于将 JS 表示形式转换为 C++ 表示形式。
• 一个toJs函数，用于将 C++ 表示形式转换为 JS 表示形式。

注意

在 iOS 上，请记住将Int64.h文件添加到 Xcode 项目中。

2. 修改 JS Spec

现在，我们可以修改 JS Spec 以添加一个使用新类型的方法。像往常一样，我们可以为我们的 Spec 使用 Flow 或 TypeScript。

1. 打开specs/NativeSampleTurbomodule。
2. 按如下方式修改 Spec。

TypeScript

NativeSampleModule.ts

import {TurboModule, TurboModuleRegistry} from 'react-native';

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

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

Flow

NativeSampleModule.js

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

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

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

在这些文件中，我们定义了需要在 C++ 中实现的函数。

3. 实现原生代码

现在，我们需要实现我们在 JS Spec 中声明的函数。

1. 打开specs/NativeSampleModule.h文件并应用以下更改。

NativeSampleModule.h

#pragma once

#include <AppSpecsJSI.h>
#include <memory>
#include <string>

+ #include "Int64.h"

namespace facebook::react {

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

  std::string reverseString(jsi::Runtime& rt, std::string input);
+ int32_t cubicRoot(jsi::Runtime& rt, int64_t input);
};

} // namespace facebook::react

2. 打开specs/NativeSampleModule.cpp文件并实现新函数。

NativeSampleModule.cpp

#include "NativeSampleModule.h"
+ #include <cmath>

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());
}

+int32_t NativeSampleModule::cubicRoot(jsi::Runtime& rt, int64_t input) {
+    return std::cbrt(input);
+}

} // namespace facebook::react

该实现导入<cmath> C++ 库以执行数学运算，然后使用<cmath>模块中的cbrt原语实现cubicRoot函数。

4. 在您的应用中测试您的代码

现在，我们可以在我们的应用中测试代码。

首先，我们需要更新App.tsx文件以使用 TurboModule 中的新方法。然后，我们可以在 Android 和 iOS 上构建我们的应用。

1. 打开App.tsx代码并应用以下更改。

App.tsx

// ...
+ const [cubicSource, setCubicSource] = React.useState('')
+ const [cubicRoot, setCubicRoot] = React.useState(0)
  return (
    <SafeAreaView style={styles.container}>
      <View>
        <Text style={styles.title}>
          Welcome to C++ Turbo Native Module Example
        </Text>
        <Text>Write down here the text you want to revert</Text>
        <TextInput
          style={styles.textInput}
          placeholder="Write your text here"
          onChangeText={setValue}
          value={value}
        />
        <Button title="Reverse" onPress={onPress} />
        <Text>Reversed text: {reversedValue}</Text>
+        <Text>For which number do you want to compute the Cubic Root?</Text>
+        <TextInput
+          style={styles.textInput}
+          placeholder="Write your text here"
+          onChangeText={setCubicSource}
+          value={cubicSource}
+        />
+        <Button title="Get Cubic Root" onPress={() => setCubicRoot(SampleTurboModule.cubicRoot(cubicSource))} />
+        <Text>The cubic root is: {cubicRoot}</Text>
      </View>
    </SafeAreaView>
  );
}
//...

2. 要在 Android 上测试应用，请从项目的根文件夹运行yarn android。
3. 要在 iOS 上测试应用，请从项目的根文件夹运行yarn ios。

添加新的结构化自定义类型：Address

上述方法可以推广到任何类型的类型。对于结构化类型，React Native 提供了一些辅助函数，使它们更容易在 JS 和 C++ 之间进行桥接。

让我们假设我们想要桥接一个具有以下属性的自定义Address类型。

interface Address {
  street: string;
  num: number;
  isInUS: boolean;
}

1. 在 Spec 中定义类型

第一步，让我们在 JS Spec 中定义新的自定义类型，以便代码生成可以输出所有支持代码。这样，我们就不必手动编写代码。

1. 打开specs/NativeSampleModule文件并添加以下更改。

TypeScript

NativeSampleModule（添加 Address 类型和 validateAddress 函数）

import {TurboModule, TurboModuleRegistry} from 'react-native';

+export type Address = {
+  street: string,
+  num: number,
+  isInUS: boolean,
+};

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

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

Flow

NativeSampleModule（添加 Address 类型和 validateAddress 函数）

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

+export type Address = {
+  street: string,
+  num: number,
+  isInUS: boolean,
+};


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

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

此代码定义了新的Address类型，并为 Turbo 原生模块定义了一个新的validateAddress函数。请注意，validateFunction需要一个Address对象作为参数。

也可以有返回自定义类型的函数。

2. 定义桥接代码

从 Spec 中定义的Address类型，代码生成将生成两种辅助类型：NativeSampleModuleAddress和NativeSampleModuleAddressBridging。

第一种类型是Address的定义。第二种类型包含桥接自定义类型从 JS 到 C++ 和反之亦然的所有基础结构。我们唯一需要添加的额外步骤是定义扩展NativeSampleModuleAddressBridging类型的Bridging结构。

1. 打开shared/NativeSampleModule.h文件。
2. 在文件中添加以下代码。

NativeSampleModule.h（桥接 Address 类型）

#include "Int64.h"
#include <memory>
#include <string>

namespace facebook::react {
+  using Address = NativeSampleModuleAddress<std::string, int32_t, bool>;

+  template <>
+  struct Bridging<Address>
+      : NativeSampleModuleAddressBridging<Address> {};
  // ...
}

此代码为通用类型NativeSampleModuleAddress定义了一个Address类型别名。**泛型的顺序很重要**：第一个模板参数指的是结构体的第一个数据类型，第二个指的是第二个，依此类推。

然后，代码通过扩展代码生成生成的NativeSampleModuleAddressBridging为新的Address类型添加了Bridging特化。

注意

有一种生成这些类型的约定。

• 名称的第一部分始终是模块的类型。在本例中为NativeSampleModule。
• 名称的第二部分始终是 Spec 中定义的 JS 类型的名称。在本例中为Address。

3. 实现原生代码

现在，我们需要在 C++ 中实现validateAddress函数。首先，我们需要将函数声明添加到.h文件中，然后我们可以在.cpp文件中实现它。

1. 打开shared/NativeSampleModule.h文件并添加函数定义。

NativeSampleModule.h（validateAddress 函数原型）

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

+  bool validateAddress(jsi::Runtime &rt, jsi::Object input);
};

} // namespace facebook::react

2. 打开shared/NativeSampleModule.cpp文件并添加函数实现。

NativeSampleModule.cpp（validateAddress 实现）

bool NativeSampleModule::validateAddress(jsi::Runtime &rt, jsi::Object input) {
  std::string street = input.getProperty(rt, "street").asString(rt).utf8(rt);
  int32_t number = input.getProperty(rt, "num").asNumber();

  return !street.empty() && number > 0;
}

在实现中，表示Address的对象是一个jsi::Object。要从该对象中提取值，我们需要使用JSI提供的访问器。

• getProperty()通过名称从对象检索属性。
• asString()将属性转换为jsi::String。
• utf8()将jsi::String转换为std::string。
• asNumber()将属性转换为double。

手动解析对象后，我们可以实现所需的逻辑。

注意

如果您想了解更多关于JSI及其工作原理的信息，请查看 App.JS 2024 上的这个精彩演讲

4. 在应用中测试代码

要在应用中测试代码，我们必须修改App.tsx文件。

1. 打开App.tsx文件。删除App()函数的内容。
2. 将App()函数的主体替换为以下代码。

App.tsx（App 函数主体替换）

const [street, setStreet] = React.useState('');
const [num, setNum] = React.useState('');
const [isValidAddress, setIsValidAddress] = React.useState<
  boolean | null
>(null);

const onPress = () => {
  let houseNum = parseInt(num, 10);
  if (isNaN(houseNum)) {
    houseNum = -1;
  }
  const address = {
    street,
    num: houseNum,
    isInUS: false,
  };
  const result = SampleTurboModule.validateAddress(address);
  setIsValidAddress(result);
};

return (
  <SafeAreaView style={styles.container}>
    <View>
      <Text style={styles.title}>
        Welcome to C Turbo Native Module Example
      </Text>
      <Text>Address:</Text>
      <TextInput
        style={styles.textInput}
        placeholder="Write your address here"
        onChangeText={setStreet}
        value={street}
      />
      <Text>Number:</Text>
      <TextInput
        style={styles.textInput}
        placeholder="Write your address here"
        onChangeText={setNum}
        value={num}
      />
      <Button title="Validate" onPress={onPress} />
      {isValidAddress != null && (
        <Text>
          Your address is {isValidAddress ? 'valid' : 'not valid'}
        </Text>
      )}
    </View>
  </SafeAreaView>
);

恭喜！🎉

您已将第一个类型从 JS 桥接到 C++。