Skip to main content

开始

以下内容是 React Navigation 的"基础"部分。这些内容足以让你了解如何构建典型的小型移动应用程序，并为你深入了解 React Navigation 的更高级部分提供必要的背景知识。

前置要求​

如果你已经熟悉 JavaScript、React 和 React Native，那么你就能很快上手 React Navigation！如果不熟悉，我们强烈建议你先掌握一些基础知识，然后再回来继续学习。

以下是一些帮助你学习的资源：

  1. React Native
  2. React 核心概念
  3. React Hooks
  4. React Context（进阶）

最低要求​

  • react-native >= 0.72.0
  • expo >= 52（如果你使用 Expo Go）
  • typescript >= 5.0.0（如果你使用 TypeScript）

开始模板​

如果你要开始一个新项目，可以使用 React Navigation 模板快速搭建一个带有静态配置的新项目：

npx create-expo-app@latest --template react-navigation/template

查看项目的 README.md 获取更多关于如何开始的信息。

如果你使用模板创建了新项目，可以跳过下面的安装步骤，直接进入"React Navigation 入门"。

否则，你可以按照以下说明将 React Navigation 安装到现有项目中。

安装​

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

npm install @react-navigation/native

React Navigation 由一些核心工具组成，用来创建应用程序中的导航结构。现在不用太担心这个，很快你就会明白了！为了提前完成安装工作，让我们也安装和配置大多数导航器使用的依赖项，然后我们就可以开始编写代码了。

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

在 Expo 托管项目中安装依赖​

在你的项目目录中运行：

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

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

现在你可以继续"React Navigation 入门"开始编写代码了。

在原生 React Native 项目中安装依赖​

在你的项目目录中运行：

npm install react-native-screens react-native-safe-area-context
note

安装后你可能会收到与对等依赖相关的警告。这些通常是由某些包中指定的版本范围不正确导致的。只要你的应用程序能够构建，大多数警告都可以安全忽略。

如果你使用 Mac 并开发 iOS 应用，你需要安装 pods（通过 Cocoapods）来完成链接。

npx pod-install ios

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

在 MainActivity 类的主体中添加高亮显示的代码：

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

并确保在包声明下面的文件顶部添加以下导入语句：

import android.os.Bundle;

这个更改是必需的，以避免与 Activity 重启时视图状态未能持续一致相关的崩溃。

info

当你使用 navigator（如 stack navigator）时，你需要按照该 navigator 的安装说明安装任何额外的依赖项。如果你收到"Unable to resolve module"错误，则需要在项目中安装该模块。

设置 React Navigation​

安装并配置完依赖项后，你可以继续设置项目以使用 React Navigation。

使用 React Navigation 时，你需要在应用程序中配置navigators。Navigators 处理应用程序中屏幕之间的转换，并提供标题栏、标签栏等 UI。

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

静态配置​

静态配置 API 减少了样板代码，并简化了 TypeScript 类型和深度链接等内容。如果你正在开始一个新项目或者是 React Navigation 新手，这是推荐的方式来设置你的应用。如果将来需要更多灵活性，你始终可以与动态配置混合使用。

继续阅读"React Navigation 入门"开始使用静态 API 编写代码。

动态配置​

动态配置提供更多灵活性，但需要更多样板代码和配置（例如深度链接、typescript 等）。

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

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

export default function App() {
  return (
    <NavigationContainer>{/* 你的应用代码的其余部分 */}</NavigationContainer>
  );
}
warning

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

继续阅读"React Navigation 入门"开始使用动态 API 编写代码。