Skip to main content
Version: 7.x

入门

本文档的“基础知识”部分接下来将介绍 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:

  1. React Native

  2. React 的主要概念

    ¥Main Concepts of React

  3. React 钩子

    ¥React Hooks

  4. React 上下文（高级）

    ¥React Context (Advanced)

最低要求​

¥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)

安装​

¥Installation

在你的 React Native 项目中安装所需的包：

¥Install the required packages in your React Native project:

npm install @react-navigation/native

React Navigation 由一些核心实用程序组成，然后导航器使用这些实用程序在你的应用中创建导航结构。现在不要太担心这个，很快就会清楚的！为了预先加载安装工作，我们还需要安装和配置大多数导航器使用的依赖，然后我们可以继续开始编写一些代码。

¥React Navigation is made up of some core utilities and those are then used by navigators to create the navigation structure in your app. Don't worry too much about this for now, it'll become clear soon enough! To frontload the installation work, let's also install and configure dependencies used by most navigators, then we can move forward with starting to write some code.

我们现在要安装的库是 react-native-screens 和 react-native-safe-area-context。如果你已经安装了这些库并且是最新版本，那么你就完成了！否则，请继续阅读。

¥The libraries we will install now are react-native-screens and react-native-safe-area-context. If you already have these libraries installed and at the latest version, you are done here! Otherwise, read on.

将依赖安装到 Expo 托管项目中​

¥Installing dependencies into an Expo managed project

在你的项目目录中，运行：

¥In your project directory, run:

npx expo install react-native-screens react-native-safe-area-context

这将安装这些库的兼容版本。

¥This will install versions of these libraries that are compatible.

你现在可以继续 "你好 React 导航" 开始编写一些代码。

¥You can now continue to "Hello React Navigation" to start writing some code.

将依赖安装到裸 React Native 项目中​

¥Installing dependencies into a bare React Native project

在你的项目目录中，运行：

¥In your project directory, run:

npm install react-native-screens react-native-safe-area-context
注意

安装后，你可能会收到与对等依赖相关的警告。它们通常是由某些软件包中指定的版本范围不正确引起的。只要你的应用构建，你就可以安全地忽略大多数警告。

¥You might get warnings related to peer dependencies after installation. They are usually caused by incorrect version ranges specified in some packages. You can safely ignore most warnings as long as your app builds.

如果你使用的是 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

react-native-screens 软件包需要一个额外的配置步骤才能在 Android 设备上正常工作。编辑位于 android/app/src/main/java/<your package name>/ 下的 MainActivity.kt 或 MainActivity.java 文件。

¥react-native-screens package requires one additional configuration step to properly work on Android devices. Edit MainActivity.kt or MainActivity.java file which is located under android/app/src/main/java/<your package name>/.

将高亮的代码添加到 MainActivity 类的主体中：

¥Add the highlighted code to the body of MainActivity class:

class MainActivity: ReactActivity() {
  // ...
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(null)
  }
  // ...
}

并确保在此文件顶部的包声明下方添加以下导入声明：

¥and make sure to add the following import statement at the top of this file below your package statement:

import android.os.Bundle;

需要进行此更改，以避免与 View 状态在 Activity 重新启动期间未一致持久相关的崩溃。

¥This change is required to avoid crashes related to View state being not persisted consistently across Activity restarts.

信息

当你使用导航器（例如堆栈导航器）时，你需要按照该导航器的安装说明来获取任何其他依赖。如果你收到错误 "无法解析模块"，则需要在项目中安装该模块。

¥When you use a navigator (such as stack navigator), you'll need to follow the installation instructions of that navigator for any additional dependencies. If you're getting an error "Unable to resolve module", you need to install that module in your project.

设置 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.

配置导航器有两种主要方法：

¥There are 2 primary ways to configure the navigators:

静态配置​

¥Static configuration

静态配置 API 减少了样板并简化了 TypeScript 类型和深度链接等内容。如果你正在启动一个新项目或不熟悉 React Navigation，这是设置应用的推荐方式。如果你将来需要更多灵活性，则可以随时使用动态配置进行混合搭配。

¥The static configuration API has reduced boilerplate and simplifies things such as TypeScript types and deep linking. 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

动态配置允许更多灵活性，但需要更多样板和配置（例如深层链接、typescript 等）。

¥The dynamic configuration allows for more flexibility but requires more boilerplate and configuration (e.g. for deep links, typescript etc.).

要开始动态配置，首先，我们需要将你的应用封装在 NavigationContainer 中。通常，你会在输入文件中执行此操作，例如 index.js 或 App.js：

¥To get started with dynamic configuration, first, we need to wrap your app in NavigationContainer. Usually, you'd do this in your entry file, such as index.js or App.js:

import * as React from 'react';
import { NavigationContainer } from '@react-navigation/native';

export default function App() {
  return (
    <NavigationContainer>{/* Rest of your app code */}</NavigationContainer>
  );
}
警告

在典型的 React Native 应用中，NavigationContainer 只能在应用的根目录中使用一次。除非你有特定的用例，否则不应嵌套多个 NavigationContainer。

¥In a typical React Native app, the NavigationContainer should be only used once in your app at the root. You shouldn't nest multiple NavigationContainers unless you have a specific use case for them.

继续 "你好 React 导航" 开始使用动态 API 编写一些代码。

¥Continue to "Hello React Navigation" to start writing some code with the dynamic API.