跳到主要内容

Native Modules

您的 React Native 应用代码可能需要与 React Native 或现有库未提供的原生平台 API 进行交互。您可以使用 Turbo Native Module 自行编写集成代码。本指南将向您展示如何编写一个 Turbo Native Module。

基本步骤如下：

  1. 使用最流行的 JavaScript 类型注解语言之一——Flow 或 TypeScript——定义类型化的 JavaScript 规范；
  2. 配置依赖管理系统以运行 Codegen，将规范转换为原生语言接口；
  3. 使用您的规范编写应用代码；以及
  4. 使用生成的接口编写原生平台代码，将您的原生代码编写并接入 React Native 运行时环境。

让我们通过构建一个示例 Turbo Native Module 来逐步了解这些步骤。本指南的其余部分假设您已经使用以下命令创建了应用：

shell
npx @react-native-community/cli@latest init TurboModuleExample --version 0.87

Native Persistent Storage​

本指南将向您展示如何实现 Web Storage API 中的 localStorage。对于可能正在您的项目中编写应用代码的 React 开发者来说，这个 API 很容易理解。

为了让它在移动设备上正常工作，我们需要使用 Android 和 iOS API：

1. 声明类型化规范​

React Native 提供了一个名为 Codegen 的工具，它接受使用 TypeScript 或 Flow 编写的规范，并为 Android 和 iOS 生成特定于平台的代码。规范声明了将在原生代码与 React Native JavaScript 运行时之间来回传递的方法和数据类型。Turbo Native Module 包含您的规范、您编写的原生代码，以及根据您的规范生成的 Codegen 接口。

要创建 specs 文件：

  1. 在应用的根文件夹内，创建一个名为 specs 的新文件夹。
  2. 创建一个名为 NativeLocalStorage.ts 的新文件。
信息

您可以在 附录 文档中查看规范中可以使用的所有类型，以及所生成的原生类型。

信息

如果您想更改模块名称和相关的 specs 文件名称，请确保始终使用“Native”作为前缀（例如 NativeStorage 或 NativeUsersDefault）。

以下是 localStorage 规范的一种实现：

specs/NativeLocalStorage.ts
import type {TurboModule} from 'react-native';
import {TurboModuleRegistry} from 'react-native';

export interface Spec extends TurboModule {
  setItem(value: string, key: string): void;
  getItem(key: string): string | null;
  removeItem(key: string): void;
  clear(): void;
}

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

2. 配置 Codegen 运行​

React Native Codegen 工具会使用该规范为我们生成特定于平台的接口和样板代码。为此，Codegen 需要知道在哪里找到我们的规范，以及要对其执行什么操作。更新您的 package.json，使其包含：

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

Codegen 的所有内容都连接完成后，我们需要准备原生代码，以便接入生成的代码。

Codegen 通过 generateCodegenArtifactsFromSchema Gradle 任务执行：

cd android
./gradlew generateCodegenArtifactsFromSchema

BUILD SUCCESSFUL in 837ms
14 actionable tasks: 3 executed, 11 up-to-date

构建 Android 应用时会自动运行此任务。

3. 使用 Turbo Native Module 编写应用代码​

使用 NativeLocalStorage，下面是修改后的 App.tsx，其中包含我们希望持久化的一些文本、一个输入框，以及一些用于更新此值的按钮。

TurboModuleRegistry 支持两种获取 Turbo Native Module 的模式：

  • get<T>(name: string): T | null：如果 Turbo Native Module 不可用，则返回 null。
  • getEnforcing<T>(name: string): T：如果 Turbo Native Module 不可用，则抛出异常。这假设该模块始终可用。
App.tsx
import {useEffect, useState, type JSX} from 'react';
import {
  SafeAreaView,
  StyleSheet,
  Text,
  TextInput,
  Button,
} from 'react-native';

import NativeLocalStorage from './specs/NativeLocalStorage';

const EMPTY = '<empty>';

function App(): JSX.Element {
  const [value, setValue] = useState<string | null>(null);

  const [editingValue, setEditingValue] = useState<string | null>(
    null,
  );

  useEffect(() => {
    const storedValue = NativeLocalStorage?.getItem('myKey');
    setValue(storedValue ?? '');
  }, []);

  function saveValue() {
    NativeLocalStorage?.setItem(editingValue ?? EMPTY, 'myKey');
    setValue(editingValue);
  }

  function clearAll() {
    NativeLocalStorage?.clear();
    setValue('');
  }

  function deleteValue() {
    NativeLocalStorage?.removeItem('myKey');
    setValue('');
  }

  return (
    <SafeAreaView style={{flex: 1}}>
      <Text style={styles.text}>
        Current stored value is: {value ?? 'No Value'}
      </Text>
      <TextInput
        placeholder="Enter the text you want to store"
        style={styles.textInput}
        onChangeText={setEditingValue}
      />
      <Button title="Save" onPress={saveValue} />
      <Button title="Delete" onPress={deleteValue} />
      <Button title="Clear" onPress={clearAll} />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  text: {
    margin: 10,
    fontSize: 20,
  },
  textInput: {
    margin: 10,
    height: 40,
    borderColor: 'black',
    borderWidth: 1,
    paddingLeft: 5,
    paddingRight: 5,
    borderRadius: 5,
  },
});

export default App;

4. 编写原生平台代码​

一切准备就绪后，我们将开始编写原生平台代码。我们分两部分进行：

备注

本指南将向您展示如何创建一个仅适用于新架构的 Turbo Native Module。如果您需要同时支持新架构和旧架构，请参阅我们的向后兼容指南。

现在是编写一些 Android 平台代码的时候了，以确保应用关闭后 localStorage 仍然存在。

第一步是实现生成的 NativeLocalStorageSpec 接口：

android/app/src/main/java/com/nativelocalstorage/NativeLocalStorageModule.java
package com.nativelocalstorage;

import android.content.Context;
import android.content.SharedPreferences;
import com.nativelocalstorage.NativeLocalStorageSpec;
import com.facebook.react.bridge.ReactApplicationContext;

public class NativeLocalStorageModule extends NativeLocalStorageSpec {

  public static final String NAME = "NativeLocalStorage";

  public NativeLocalStorageModule(ReactApplicationContext reactContext) {
    super(reactContext);
  }

  @Override
  public String getName() {
    return NAME;
  }

  @Override
  public void setItem(String value, String key) {
    SharedPreferences sharedPref = getReactApplicationContext().getSharedPreferences("my_prefs", Context.MODE_PRIVATE);
    SharedPreferences.Editor editor = sharedPref.edit();
    editor.putString(key, value);
    editor.apply();
  }

  @Override
  public String getItem(String key) {
    SharedPreferences sharedPref = getReactApplicationContext().getSharedPreferences("my_prefs", Context.MODE_PRIVATE);
    String username = sharedPref.getString(key, null);
    return username;
  }

  @Override
  public void removeItem(String key) {
    SharedPreferences sharedPref = getReactApplicationContext().getSharedPreferences("my_prefs", Context.MODE_PRIVATE);
    sharedPref.edit().remove(key).apply();
  }

  @Override
  public void clear() {
    SharedPreferences sharedPref = getReactApplicationContext().getSharedPreferences("my_prefs", Context.MODE_PRIVATE);
    sharedPref.edit().clear().apply();
  }
}

接下来需要创建 NativeLocalStoragePackage。它通过将我们的 Module 封装为 Base Native Package，提供一个用于在 React Native 运行时注册该 Module 的对象：

android/app/src/main/java/com/nativelocalstorage/NativeLocalStoragePackage.java
package com.nativelocalstorage;

import com.facebook.react.BaseReactPackage;
import com.facebook.react.bridge.NativeModule;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.module.model.ReactModuleInfo;
import com.facebook.react.module.model.ReactModuleInfoProvider;

import java.util.HashMap;
import java.util.Map;

public class NativeLocalStoragePackage extends BaseReactPackage {

  @Override
  public NativeModule getModule(String name, ReactApplicationContext reactContext) {
    if (name.equals(NativeLocalStorageModule.NAME)) {
      return new NativeLocalStorageModule(reactContext);
    } else {
      return null;
    }
  }

  @Override
  public ReactModuleInfoProvider getReactModuleInfoProvider() {
    return new ReactModuleInfoProvider() {
      @Override
      public Map<String, ReactModuleInfo> getReactModuleInfos() {
        Map<String, ReactModuleInfo> map = new HashMap<>();
        map.put(NativeLocalStorageModule.NAME, new ReactModuleInfo(
          NativeLocalStorageModule.NAME,       // name
          NativeLocalStorageModule.NAME,       // className
          false, // canOverrideExistingModule
          false, // needsEagerInit
          false, // isCXXModule
          true   // isTurboModule
        ));
        return map;
      }
    };
  }
}

最后，需要告诉主应用中的 React Native 如何找到这个 Package。我们将这个过程称为在 React Native 中“注册”该 Package。

在本例中，将其添加为 getPackages 方法返回的内容。

信息

稍后你将了解如何将 Native Modules 作为 npm packages 分发，构建工具会为你自动链接这些 packages

android/app/src/main/java/com/turobmoduleexample/MainApplication.java
package com.inappmodule;

import android.app.Application;
import com.facebook.react.PackageList;
import com.facebook.react.ReactApplication;
import com.facebook.react.ReactHost;
import com.facebook.react.ReactNativeHost;
import com.facebook.react.ReactPackage;
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint;
import com.facebook.react.defaults.DefaultReactHost;
import com.facebook.react.defaults.DefaultReactNativeHost;
import com.facebook.soloader.SoLoader;
import com.nativelocalstorage.NativeLocalStoragePackage;

import java.util.ArrayList;
import java.util.List;

public class MainApplication extends Application implements ReactApplication {

  private final ReactNativeHost reactNativeHost = new DefaultReactNativeHost(this) {
    @Override
    public List<ReactPackage> getPackages() {
      List<ReactPackage> packages = new PackageList(this).getPackages();
      // Packages that cannot be autolinked yet can be added manually here, for example:
      // packages.add(new MyReactNativePackage());
      packages.add(new NativeLocalStoragePackage());
      return packages;
    }

    @Override
    public String getJSMainModuleName() {
      return "index";
    }

    @Override
    public boolean getUseDeveloperSupport() {
      return BuildConfig.DEBUG;
    }

    @Override
    public boolean isNewArchEnabled() {
      return BuildConfig.IS_NEW_ARCHITECTURE_ENABLED;
    }

    @Override
    public boolean isHermesEnabled() {
      return BuildConfig.IS_HERMES_ENABLED;
    }
  };

  @Override
  public ReactHost getReactHost() {
    return DefaultReactHost.getDefaultReactHost(getApplicationContext(), reactNativeHost);
  }

  @Override
  public void onCreate() {
    super.onCreate();
    SoLoader.init(this, false);
    if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
      // If you opted-in for the New Architecture, we load the native entry point for this app.
      DefaultNewArchitectureEntryPoint.load();
    }
  }
}

现在可以在模拟器上构建并运行代码：

npm run android