Skip to main content

与现有应用集成

当你从头开始开发新的移动应用时，React Native 非常有用。但是，它也适用于向现有原生应用添加单个视图或用户流。只需几个步骤，你就可以添加新的基于 React Native 的功能、屏幕、视图等。

¥React Native is great when you are starting a new mobile app from scratch. However, it also works well for adding a single view or user flow to existing native applications. With a few steps, you can add new React Native based features, screens, views, etc.

具体步骤会有所不同，具体取决于你的目标平台。

¥The specific steps are different depending on what platform you're targeting.

关键概念​

¥Key Concepts

将 React Native 组件集成到 Android 应用中的关键是：

¥The keys to integrating React Native components into your Android application are to:

  1. 设置正确的目录结构。

    ¥Set up the correct directory structure.

  2. 安装必要的 NPM 依赖。

    ¥Install the necessary NPM dependencies.

  3. 将 React Native 添加到你的 Gradle 配置中。

    ¥Adding React Native to your Gradle configuration.

  4. 为你的第一个 React Native 屏幕编写 TypeScript 代码。

    ¥Writing the TypeScript code for your first React Native screen.

  5. 使用 ReactActivity 将 React Native 与你的 Android 代码集成。

    ¥Integrate React Native with your Android code using a ReactActivity.

  6. 通过运行打包程序并查看你的应用的运行情况来测试你的集成。

    ¥Testing your integration by running the bundler and seeing your app in action.

使用社区模板​

¥Using the Community Template

在你遵循本指南时，我们建议你使用 React Native 社区模板 作为参考。模板包含一个最小的 Android 应用，将帮助你了解如何将 React Native 集成到现有的 Android 应用中。

¥While you follow this guide, we suggest you to use the React Native Community Template as reference. The template contains a minimal Android app and will help you understanding how to integrate React Native into an existing Android app.

先决条件​

¥Prerequisites

按照 设置你的开发环境 上的指南并使用 无需框架的 React Native 配置你的开发环境以构建适用于 Android 的 React Native 应用。本指南还假设你熟悉 Android 开发的基础知识，例如创建活动和编辑 AndroidManifest.xml 文件。

¥Follow the guide on setting up your development environment and using React Native without a framework to configure your development environment for building React Native apps for Android. This guide also assumes you're familiar with the basics of Android development such as creating Activities and editing the AndroidManifest.xml file.

1. 设置目录结构​

¥ Set up directory structure

为了确保流畅的体验，请为集成的 React Native 项目创建一个新文件夹，然后将现有的 Android 项目移动到 /android 子文件夹。

¥To ensure a smooth experience, create a new folder for your integrated React Native project, then move your existing Android project to the /android subfolder.

2. 安装 NPM 依赖​

¥ Install NPM dependencies

转到根目录并运行以下命令：

¥Go to the root directory and run the following command:

curl -O https://raw.githubusercontent.com/react-native-community/template/refs/heads/0.75-stable/template/package.json

这会将 package.json 来自社区模板的文件 复制到你的项目中。

¥This will copy the package.json file from the Community template to your project.

接下来，通过运行安装 NPM 包：

¥Next, install the NPM packages by running:

npm install

安装过程创建了一个新的 node_modules 文件夹。此文件夹存储构建项目所需的所有 JavaScript 依赖。

¥Installation process has created a new node_modules folder. This folder stores all the JavaScript dependencies required to build your project.

将 node_modules/ 添加到你的 .gitignore 文件（此处为 社区默认）。

¥Add node_modules/ to your .gitignore file (here the Community default one).

3. 将 React Native 添加到你的应用​

¥ Adding React Native to your app

配置 Gradle​

¥Configuring Gradle

React Native 使用 React Native Gradle 插件来配置依赖和项目设置。

¥React Native uses the React Native Gradle Plugin to configure your dependencies and project setup.

首先，让我们编辑你的 settings.gradle 文件，添加这些行（如 社区模板 所建议的）：

¥First, let's edit your settings.gradle file by adding those lines (as suggested from the Community template):

// Configures the React Native Gradle Settings plugin used for autolinking
pluginManagement { includeBuild("../node_modules/@react-native/gradle-plugin") }
plugins { id("com.facebook.react.settings") }
extensions.configure(com.facebook.react.ReactSettingsExtension){ ex -> ex.autolinkLibrariesFromCommand() }
// If using .gradle.kts files:
// extensions.configure<com.facebook.react.ReactSettingsExtension> { autolinkLibrariesFromCommand() }
includeBuild("../node_modules/@react-native/gradle-plugin")

// Include your existing Gradle modules here.
// include(":app")

然后你需要打开你的顶层 build.gradle 并包含此行（如 社区模板 所建议的）：

¥Then you need to open your top level build.gradle and include this line (as suggested from the Community template):

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath("com.android.tools.build:gradle:7.3.1")
+       classpath("com.facebook.react:react-native-gradle-plugin")
    }
}

这确保 React Native Gradle 插件 (RNGP) 在你的项目中可用。最后，在应用的 build.gradle 文件中添加这些行（它通常是 app 文件夹中的另一个 build.gradle 文件 - 你可以使用 社区模板文件作为参考）：

¥This makes sure the React Native Gradle Plugin (RNGP) is available inside your project. Finally, add those lines inside your Applications's build.gradle file (it's a different build.gradle file usually inside your app folder - you can use the Community template file as reference):

apply plugin: "com.android.application"
+apply plugin: "com.facebook.react"

repositories {
    mavenCentral()
}

dependencies {
    // Other dependencies here
+   // Note: we intentionally don't specify the version number here as RNGP will take care of it.
+   // If you don't use the RNGP, you'll have to specify version manually.
+   implementation("com.facebook.react:react-android")
+   implementation("com.facebook.react:hermes-android")
}

+react {
+   // Needed to enable Autolinking - https://github.com/react-native-community/cli/blob/master/docs/autolinking.md
+   autolinkLibrariesWithApp()
+}

最后，打开应用 gradle.properties 文件并添加以下行（此处为 社区模板文件作为参考）：

¥Finally, open your application gradle.properties files and add the following line (here the Community template file as reference):

+reactNativeArchitectures=armeabi-v7a,arm64-v8a,x86,x86_64
+newArchEnabled=true
+hermesEnabled=true

配置你的清单​

¥Configuring your manifest

首先，确保你的 AndroidManifest.xml 具有 Internet 权限：

¥First, make sure you have the Internet permission in your AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

+   <uses-permission android:name="android.permission.INTERNET" />

    <application
      android:name=".MainApplication">
    </application>
</manifest>

然后你需要在你的调试 AndroidManifest.xml 中启用 明文流量:

¥Then you need to enable cleartext traffic in your debug AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
+       android:usesCleartextTraffic="true"
+       tools:targetApi="28"
    />
</manifest>

与往常一样，这里是社区模板中的 AndroidManifest.xml 文件，供参考：main 和 debug

¥As usual, here the AndroidManifest.xml file from the Community template to use as a reference: main and debug

这是必需的，因为你的应用将通过 HTTP 与你的本地打包器 Metro 进行通信。

¥This is needed as your application will communicate with your local bundler, [Metro][https://metrobundler.dev/], via HTTP.

确保仅将其添加到你的调试清单中。

¥Make sure you add this only to your debug manifest.

4. 编写 TypeScript 代码​

¥ Writing the TypeScript Code

现在我们将实际修改原生 Android 应用以集成 React Native。

¥Now we will actually modify the native Android application to integrate React Native.

我们将编写的第一段代码是新屏幕的实际 React Native 代码，它将集成到我们的应用中。

¥The first bit of code we will write is the actual React Native code for the new screen that will be integrated into our application.

创建 index.js 文件​

¥Create a index.js file

首先，在 React Native 项目的根目录中创建一个空的 index.js 文件。

¥First, create an empty index.js file in the root of your React Native project.

index.js 是 React Native 应用的起点，并且始终是必需的。它可以是一个小文件，或者是 React Native 组件或应用中的其他文件，也可以包含它所需的所有代码。

¥index.js is the starting point for React Native applications, and it is always required. It can be a small file that imports other file that are part of your React Native component or application, or it can contain all the code that is needed for it.

我们的 index.js 应该如下所示（这里是 社区模板文件作为参考）：

¥Our index.js should look as follows (here the Community template file as reference):

import {AppRegistry} from 'react-native';
import App from './App';

AppRegistry.registerComponent('HelloWorld', () => App);

创建 App.tsx 文件​

¥Create a App.tsx file

让我们创建一个 App.tsx 文件。这是一个可以有 JSX 表达式的 TypeScript 文件。它包含我们将集成到 Android 应用 (link) 中的根 React Native 组件：

¥Let's create an App.tsx file. This is a TypeScript file that can have JSX expressions. It contains the root React Native component that we will integrate into our Android application (link):

import React from 'react';
import {
  SafeAreaView,
  ScrollView,
  StatusBar,
  StyleSheet,
  Text,
  useColorScheme,
  View,
} from 'react-native';

import {
  Colors,
  DebugInstructions,
  Header,
  ReloadInstructions,
} from 'react-native/Libraries/NewAppScreen';

function App(): React.JSX.Element {
  const isDarkMode = useColorScheme() === 'dark';

  const backgroundStyle = {
    backgroundColor: isDarkMode ? Colors.darker : Colors.lighter,
  };

  return (
    <SafeAreaView style={backgroundStyle}>
      <StatusBar
        barStyle={isDarkMode ? 'light-content' : 'dark-content'}
        backgroundColor={backgroundStyle.backgroundColor}
      />
      <ScrollView
        contentInsetAdjustmentBehavior="automatic"
        style={backgroundStyle}>
        <Header />
        <View
          style={{
            backgroundColor: isDarkMode
              ? Colors.black
              : Colors.white,
            padding: 24,
          }}>
          <Text style={styles.title}>Step One</Text>
          <Text>
            Edit <Text style={styles.bold}>App.tsx</Text> to
            change this screen and see your edits.
          </Text>
          <Text style={styles.title}>See your changes</Text>
          <ReloadInstructions />
          <Text style={styles.title}>Debug</Text>
          <DebugInstructions />
        </View>
      </ScrollView>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  title: {
    fontSize: 24,
    fontWeight: '600',
  },
  bold: {
    fontWeight: '700',
  },
});

export default App;

这里是 社区模板文件作为参考

¥Here the Community template file as reference

5. 与你的 Android 代码集成​

¥ Integrating with your Android code

我们现在需要添加一些原生代码以启动 React Native 运行时并告诉它渲染我们的 React 组件。

¥We now need to add some native code in order to start the React Native runtime and tell it to render our React components.

更新你的应用类​

¥Updating your Application class

首先，我们需要更新你的 Application 类以正确初始化 React Native，如下所示：

¥First, we need to update your Application class to properly initialize React Native as follows:

package <your-package-here>;

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.facebook.react.soloader.OpenSourceMergedSoMapping
+import java.util.List;

-class MainApplication extends Application {
+class MainApplication extends Application implements ReactApplication {
+ @Override
+ public ReactNativeHost getReactNativeHost() {
+   return new DefaultReactNativeHost(this) {
+     @Override
+     protected List<ReactPackage> getPackages() { return new PackageList(this).getPackages(); }
+     @Override
+     protected String getJSMainModuleName() { return "index"; }
+     @Override
+     public boolean getUseDeveloperSupport() { return BuildConfig.DEBUG; }
+     @Override
+     protected boolean isNewArchEnabled() { return BuildConfig.IS_NEW_ARCHITECTURE_ENABLED; }
+     @Override
+     protected Boolean isHermesEnabled() { return BuildConfig.IS_HERMES_ENABLED; }
+   };
+ }

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

  @Override
  public void onCreate() {
    super.onCreate();
+   SoLoader.init(this, OpenSourceMergedSoMapping);
+   if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
+     DefaultNewArchitectureEntryPoint.load();
+   }
  }
}

与往常一样，这里是 MainApplication.kt 社区模板文件作为参考

¥As usual, here the MainApplication.kt Community template file as reference

创建 ReactActivity​

¥Creating a ReactActivity

最后，我们需要创建一个新的 Activity，它将扩展 ReactActivity 并托管 React Native 代码。此活动将负责启动 React Native 运行时并渲染 React 组件。

¥Finally, we need to create a new Activity that will extend ReactActivity and host the React Native code. This activity will be responsible for starting the React Native runtime and rendering the React component.

// package <your-package-here>;

import com.facebook.react.ReactActivity;
import com.facebook.react.ReactActivityDelegate;
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint;
import com.facebook.react.defaults.DefaultReactActivityDelegate;

public class MyReactActivity extends ReactActivity {

    @Override
    protected String getMainComponentName() {
        return "HelloWorld";
    }

    @Override
    protected ReactActivityDelegate createReactActivityDelegate() {
        return new DefaultReactActivityDelegate(this, getMainComponentName(), DefaultNewArchitectureEntryPoint.getFabricEnabled());
    }
}

与往常一样，这里是 MainActivity.kt 社区模板文件作为参考

¥As usual, here the MainActivity.kt Community template file as reference

每当你创建新活动时，都需要将其添加到你的 AndroidManifest.xml 文件中。你还需要将 MyReactActivity 的主题设置为 Theme.AppCompat.Light.NoActionBar（或任何非 ActionBar 主题），否则你的应用将在 React Native 屏幕顶部渲染 ActionBar：

¥Whenever you create a new Activity, you need to add it to your AndroidManifest.xml file. You also need set the theme of MyReactActivity to Theme.AppCompat.Light.NoActionBar (or to any non-ActionBar theme) as otherwise your application will render an ActionBar on top of your React Native screen:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET" />

    <application
      android:name=".MainApplication">

+     <activity
+       android:name=".MyReactActivity"
+       android:label="@string/app_name"
+       android:theme="@style/Theme.AppCompat.Light.NoActionBar">
+     </activity>
    </application>
</manifest>

现在你的 Activity 已准备好运行一些 JavaScript 代码。

¥Now your activity is ready to run some JavaScript code.

6. 测试你的集成​

¥ Test your integration

你已完成将 React Native 与你的应用集成的所有基本步骤。现在我们将启动 Metro 打包器 将你的 TypeScript 应用代码构建成一个包。Metro 的 HTTP 服务器将你开发环境中的 localhost 中的打包包共享到模拟器或设备。这允许 热重载。

¥You have completed all the basic steps to integrate React Native with your application. Now we will start the Metro bundler to build your TypeScript application code into a bundle. Metro's HTTP server shares the bundle from localhost on your developer environment to a simulator or device. This allows for hot reloading.

首先，你需要在项目的根目录中创建一个 metro.config.js 文件，如下所示：

¥First, you need to create a metro.config.js file in the root of your project as follows:

const {getDefaultConfig} = require('@react-native/metro-config');
module.exports = getDefaultConfig(__dirname);

你可以从社区模板文件中检出 metro.config.js 文件 作为参考。

¥You can checkout the metro.config.js file from the Community template file as reference.

一旦配置文件到位，你就可以运行打包器。在项目的根目录中运行以下命令：

¥Once you have the config file in place, you can run the bundler. Run the following command in the root directory of your project:

npm start

现在正常构建并运行你的 Android 应用。

¥Now build and run your Android app as normal.

一旦你到达应用内部的 React 驱动活动，它应该从开发服务器加载 JavaScript 代码并显示：

¥Once you reach your React-powered Activity inside the app, it should load the JavaScript code from the development server and display:

在 Android Studio 中创建发布版本​

¥Creating a release build in Android Studio

你也可以使用 Android Studio 创建你的发布版本！它就像为你之前存在的原生 Android 应用创建发布版本一样快。

¥You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app.

React Native Gradle 插件将负责将 JS 代码打包在你的 APK/App Bundle 中。

¥The React Native Gradle Plugin will take care of bundling the JS code inside your APK/App Bundle.

如果你不使用 Android Studio，你可以使用以下方式创建发布版本：

¥If you're not using Android Studio, you can create a release build with:

cd android
# For a Release APK
./gradlew :app:assembleRelease
# For a Release AAB
./gradlew :app:bundleRelease

怎么办？​

¥Now what?

此时，你可以像往常一样继续开发你的应用。请参阅我们的 debugging 和 deployment 文档，了解有关使用 React Native 的更多信息。

¥At this point you can continue developing your app as usual. Refer to our debugging and deployment docs to learn more about working with React Native.