入门
本文档的“基础知识”部分接下来将介绍 React Navigation 的最重要方面。它应该足以让你了解如何构建典型的小型移动应用，并为你提供深入研究 React Navigation 更高级部分所需的背景知识。
¥What follows within the Fundamentals section of this documentation is a tour of the most important aspects of React Navigation. It should cover enough for you to know how to build your typical small mobile application, and give you the background that you need to dive deeper into the more advanced parts of React Navigation.
先决条件
¥Pre-requisites
如果你已经熟悉 JavaScript、React 和 React Native，那么你将能够快速上手 React Navigation！如果没有，我们强烈建议你先学习一些基本知识，然后在完成后返回这里。
¥If you're already familiar with JavaScript, React and React Native, then you'll be able to get moving with React Navigation quickly! If not, we highly recommend you to gain some basic knowledge first, then come back here when you're done.
以下是一些可以帮助你的资源：
¥Here are some resources to help you out:
最低要求
¥Minimum requirements
-
react-native>= 0.72.0 -
expo>= 52（如果你使用 Expo Go）¥
expo>= 52 (if you use Expo Go) -
typescript>= 5.0.0（如果你使用 TypeScript）¥
typescript>= 5.0.0 (if you use TypeScript)
入门模板
¥Starter template
如果你正在启动一个新项目，则可以使用 React 导航模板 快速设置带有 静态配置 的新项目：
¥If you're starting a new project, you can use the React Navigation template to quickly set up a new project with Static configuration:
npx create-expo-app@latest --template react-navigation/template
有关如何开始的更多信息，请参阅项目的 README.md。
¥See the project's README.md for more information on how to get started.
如果你使用模板创建了一个新项目，则可以跳过下面的安装步骤并转到 "你好 React 导航"。
¥If you created a new project using the template, you can skip the installation steps below and move on to "Hello React Navigation".
否则，你可以按照以下说明将 React Navigation 安装到现有项目中。
¥Otherwise, you can follow the instructions below to install React Navigation into your existing project.
安装
¥Installation
@react-navigation/native 包包含 React Navigation 的核心功能。
¥The @react-navigation/native package contains the core functionality of React Navigation.
在你的项目目录中，运行：
¥In your project directory, run:
- npm
- Yarn
- pnpm
npm install @react-navigation/native
yarn add @react-navigation/native
pnpm add @react-navigation/native
安装依赖
¥Installing dependencies
我们还需要安装和配置大多数导航器使用的依赖。我们现在要安装的库是 react-native-screens 和 react-native-safe-area-context。
¥Let's also install and configure dependencies used by most navigators. The libraries we will install now are react-native-screens and react-native-safe-area-context.
- Expo
- Community CLI
在你的项目目录中，运行：
¥In your project directory, run:
npx expo install react-native-screens react-native-safe-area-context
这将安装与你的 Expo SDK 版本兼容的库版本。
¥This will install versions of these libraries that are compatible with your Expo SDK version.
在你的项目目录中，运行：
¥In your project directory, run:
- npm
- Yarn
- pnpm
npm install react-native-screens react-native-safe-area-context
yarn add react-native-screens react-native-safe-area-context
pnpm add react-native-screens react-native-safe-area-context
如果你使用的是 Mac 并针对 iOS 进行开发，则需要安装 pod（通过 可可足类）才能完成链接。
¥If you're on a Mac and developing for iOS, you need to install the pods (via Cocoapods) to complete the linking.
npx pod-install ios
在 Android 上配置 react-native-screens
¥Configuring react-native-screens on Android
react-native-screens 需要在 Android 上进行额外配置才能正常工作。
¥react-native-screens requires one additional configuration to properly work on Android.
编辑 android/app/src/main/java/<your package name>/ 下的 MainActivity.kt 或 MainActivity.java 文件，并将高亮显示的代码添加到 MainActivity 类的主体中：
¥Edit MainActivity.kt or MainActivity.java file under android/app/src/main/java/<your package name>/, and add the highlighted code to the body of MainActivity class:
- Kotlin
- Java
import android.os.Bundle
import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory
// ...
class MainActivity: ReactActivity() {
// ...
override fun onCreate(savedInstanceState: Bundle?) {
supportFragmentManager.fragmentFactory = RNScreensFragmentFactory()
super.onCreate(savedInstanceState)
}
// ...
}
import android.os.Bundle;
import com.swmansion.rnscreens.fragment.restoration.RNScreensFragmentFactory;
// ...
public class MainActivity extends ReactActivity {
// ...
@Override
protected void onCreate(Bundle savedInstanceState) {
getSupportFragmentManager().setFragmentFactory(new RNScreensFragmentFactory());
super.onCreate(savedInstanceState);
}
// ...
}
需要进行此更改，以避免与 View 状态在 Activity 重新启动期间未一致持久相关的崩溃。
¥This change is required to avoid crashes related to View state being not persisted consistently across Activity restarts.
在 Android 上禁用预测返回
¥Opting-out of predictive back on Android
React Navigation 目前尚不支持 Android 的预测返回手势。禁用此功能是 React Navigation 与系统返回手势正常工作的必要条件。
¥React Navigation doesn't yet support Android's predictive back gesture. Disabling it is necessary for the system back gesture to work properly with React Navigation.
要选择退出，请在 AndroidManifest.xml 的 <application> 标签（或在活动级别选择退出时使用 <activity> 标签）中，将 android:enableOnBackInvokedCallback 标志设置为 false：
¥To opt out, in AndroidManifest.xml, in the <application> tag (or <activity> tag to opt-out at activity level), set the android:enableOnBackInvokedCallback flag to false:
<application
android:enableOnBackInvokedCallback="false"
>
<!-- ... -->
</application>
设置 React Navigation
¥Setting up React Navigation
安装并配置依赖后，你可以继续设置项目以使用 React Navigation。
¥Once you've installed and configured the dependencies, you can move on to setting up your project to use React Navigation.
使用 React Navigation 时，你可以在应用中配置 navigators。导航器处理应用中屏幕之间的转换并提供 UI，例如标题、标签栏等。
¥When using React Navigation, you configure navigators in your app. Navigators handle the transition between screens in your app and provide UI such as header, tab bar etc.
当你使用导航器（例如堆栈导航器）时，你需要按照该导航器的安装说明来获取任何其他依赖。
¥When you use a navigator (such as stack navigator), you'll need to follow the installation instructions of that navigator for any additional dependencies.
配置导航器有两种主要方法：
¥There are 2 primary ways to configure the navigators:
静态配置
¥Static configuration
静态配置 API 允许你将配置写入对象中，并且配置是静态定义的，尽管配置的某些方面仍然可以动态更改。这减少了样板代码，并简化了 TypeScript 类型和深度链接等操作。
¥The static configuration API lets you write your configuration in an object, and is defined statically, though some aspects of the configuration can still can be changed dynamically. This has reduced boilerplate and simplifies things such as TypeScript types and deep linking.
如果你正在启动一个新项目或不熟悉 React Navigation，这是设置应用的推荐方式。如果你将来需要更多灵活性，则可以随时使用动态配置进行混合搭配。
¥If you're starting a new project or are new to React Navigation, this is the recommended way to set up your app. If you need more flexibility in the future, you can always mix and match with the dynamic configuration.
继续 "你好 React 导航" 开始使用静态 API 编写一些代码。
¥Continue to "Hello React Navigation" to start writing some code with the static API.
动态配置
¥Dynamic configuration
动态配置 API 允许你在 React 组件中编写配置，并可根据 state 或 props 在运行时进行更改。这提供了更大的灵活性，但需要编写更多样板代码，并针对 TypeScript 类型、深度链接等进行配置。
¥The dynamic configuration API lets you write your configuration in React components, and can change at runtime based on state or props. This allows for more flexibility but requires significantly more boilerplate and configuration for Typescript types, deep linking etc.
继续 "你好 React 导航" 开始使用动态 API 编写一些代码。
¥Continue to "Hello React Navigation" to start writing some code with the dynamic API.