---

React Navigation 全面介绍与实践

引言

在构建现代移动应用时，屏幕之间的切换与管理是核心功能之一。一个完整的应用往往包含多个页面（或称屏幕），用户需要在这些页面之间进行导航，例如从列表页进入详情页，或者在不同的功能模块之间切换。在 React Native 中，原生应用的多屏幕导航体验是开发者需要重点关注并实现的。

React Native 本身提供了一些基础的组件，但并没有内置一套完整的、开箱即用的导航解决方案。这时，React Navigation 应运而生，并迅速成为 React Native 社区中最流行和事实标准的导航库。

本文将深入探讨 React Navigation，从基本概念、核心组件，到不同类型的导航器、导航方法，再到高级用法和实践技巧，为你提供一份全面且实用的指南，帮助你彻底掌握 React Native 应用的导航。

为什么选择 React Navigation？

在 React Native 的早期，曾经有过其他导航解决方案，比如 Navigator 和 NavigationExperimental (由 React Native 官方维护)。但这些方案存在一些问题，比如性能不足、API 复杂、维护困难等。React Navigation 的出现解决了这些痛点，它带来了以下显著优势：

1. 社区标准与活跃维护： React Navigation 是当前 React Native 社区中使用最广泛、推荐度最高的导航库。它由一个活跃的团队维护，持续更新，功能完善，社区支持资源丰富。
2. 高性能与原生体验： React Navigation 提供了基于原生组件的导航器（例如 @react-navigation/native-stack），能够提供媲美原生应用的流畅度和手势体验。
3. 灵活性与可定制性： 它提供了多种内置的导航器（栈、标签页、抽屉等），可以轻松组合嵌套，满足复杂的导航结构需求。同时，几乎所有的视觉和行为方面都可以进行定制。
4. 简单易用的 API： 相较于早期的官方导航方案，React Navigation 的 API 设计更加直观和易于理解，特别是通过 Hooks (useNavigation, useRoute) 的引入，在函数式组件中处理导航变得更加便捷。
5. 跨平台一致性： 提供在 iOS 和 Android 平台上一致的导航行为和外观（尽管可以通过配置调整平台差异）。
6. 丰富的功能： 支持路由参数传递、屏幕选项配置、头部定制、手势操作、深层链接（Deep Linking）、与状态管理库集成等高级功能。

基于这些优点，React Navigation 已经成为构建 React Native 应用导航的首选方案。

核心概念

在使用 React Navigation 之前，理解几个核心概念至关重要：

1. Navigators (导航器): 导航器是 React Navigation 的核心组件，它们是用来管理屏幕切换和展示的容器。一个导航器内部包含多个屏幕。常见的导航器类型包括：

   • Stack Navigator (栈导航器): 提供一种堆栈式的导航模式，新屏幕会叠加在当前屏幕之上，返回时会移除栈顶屏幕。这是最常用和基础的导航器。
   • Tab Navigator (标签页导航器): 提供底部或顶部的标签栏，允许用户在不同的根屏幕之间快速切换。
   • Drawer Navigator (抽屉导航器): 提供一个从屏幕侧边滑出的菜单（抽屉），用于存放不常访问或全局性的导航链接。
   • Native Stack Navigator: 使用平台原生的导航组件实现栈导航，性能通常优于基于 JavaScript 实现的栈导航。
   • Material Top Tab Navigator: 实现 Material Design 风格的顶部标签页。
   • Material Bottom Tab Navigator: 实现 Material Design 风格的底部标签页。

2. Screens (屏幕): 在 React Navigation 的上下文中，一个“屏幕”通常指的是一个 React 组件，它代表应用中的一个完整界面。这些组件会被配置到导航器中，由导航器负责渲染和管理它们的生命周期及切换。

3. Navigation Actions (导航行为/动作): 这些是触发导航变化的指令，例如导航到某个屏幕 (navigate)、返回 (goBack)、将新屏幕推入栈 (push)、替换当前屏幕 (replace) 等。这些动作通过导航器提供的 navigation 对象来执行。

4. Navigation Props (导航属性): 每个由导航器渲染的屏幕组件都会接收到特殊的 props，最重要的是 navigation 和 route。

   • navigation: 一个对象，提供了执行导航动作的方法 (navigate, goBack, setOptions 等)，以及访问导航器状态和配置的方法。
   • route: 一个对象，包含当前屏幕的路由信息，最重要的属性是 params，用于接收从上一个屏幕传递过来的参数。

5. Navigation State (导航状态): 导航器内部维护了一个表示当前导航结构的 JavaScript 对象，包含当前屏幕、栈历史、参数等信息。虽然通常不需要直接操作状态，但在某些高级场景（如深层链接、与外部状态管理集成）下可能会用到。

设置与基本使用

开始使用 React Navigation 需要安装一些必要的库。核心库 @react-navigation/native 是必须的，它提供了导航的基础结构和 Hooks。此外，还需要根据你使用的导航器类型安装对应的库，以及一些处理手势和安全区域的依赖。

安装依赖

“`bash

安装核心库

npm install @react-navigation/native

安装常用的栈导航器 (推荐使用 native stack)

npm install @react-navigation/native-stack

安装一些依赖，用于处理手势、动画和安全区域

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

对于基于 gesture-handler 的导航器 (如 stack, drawer, bottom-tabs)，还需要安装

npm install react-native-gesture-handler

如果你使用 expo，以上大部分依赖可能已经集成，但仍需确认和安装特定导航器库

expo install @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context react-native-gesture-handler

“`

安装完成后，对于 react-native-screens 和 react-native-gesture-handler，可能需要在入口文件（如 index.js 或 App.js）的顶部导入它们：

“`javascript
// index.js or App.js
import ‘react-native-gesture-handler’; // 确保在应用入口的最顶部导入

import {AppRegistry} from ‘react-native’;
import App from ‘./App’; // 你的主应用组件
import {name as appName} from ‘./app.json’;

AppRegistry.registerComponent(appName, () => App);
“`

对于 react-native-screens，为了在 Android 上启用优化，可能还需要额外的配置，具体请参考其官方文档。

最简应用结构

一个使用 React Navigation 的基本应用结构如下：

“`javascript
// App.js
import * as React from ‘react’;
import { View, Text, Button } from ‘react-native’;
import { NavigationContainer } from ‘@react-navigation/native’;
import { createNativeStackNavigator } from ‘@react-navigation/native-stack’;

// 定义你的屏幕组件
function HomeScreen({ navigation }) { // 屏幕组件接收 navigation prop
return (

Home Screen
navigation.navigate(‘Details’)} // 使用 navigation.navigate 进行导航
/>

);
}

function DetailsScreen({ navigation, route }) { // 屏幕组件接收 navigation 和 route prop
// 可以通过 route.params 访问传递的参数
const { itemId, otherParam } = route.params || {};

return (

Details Screen
{/ 显示传递的参数 /}
itemId: {JSON.stringify(itemId)}
otherParam: {JSON.stringify(otherParam)}

navigation.push(‘Details’, { // 使用 navigation.push 推入新的 Details 屏幕
itemId: Math.floor(Math.random() * 100),
})}
/>
navigation.navigate(‘Home’)} /> {/ 导航回 Home /}
navigation.goBack()} /> {/ 返回上一个屏幕 /}
navigation.popToTop()} /> {/ 返回栈顶 /}

);
}

// 创建一个 Stack Navigator
const Stack = createNativeStackNavigator();

function App() {
return (
// NavigationContainer 必须包裹所有导航器

{/ 配置 Stack Navigator /}
{/ initialRouteName 设置初始屏幕 /}
{/ 定义屏幕 /}




);
}

export default App;
“`

解释：

• NavigationContainer: 这是 React Navigation 的顶级组件，必须包裹整个导航结构。它管理导航树，并包含导航状态。
• createNativeStackNavigator(): 创建一个 Stack Navigator 实例。
• <Stack.Navigator>: 导航器的组件，内部配置了它所管理的屏幕。
• initialRouteName: 指定应用启动时第一个显示的屏幕的 name。
• <Stack.Screen>: 定义一个屏幕，它需要 name（用于导航）和 component（要渲染的组件）。
• options: 配置当前屏幕的各种选项，如头部样式、标题、按钮等。
• navigation.navigate('ScreenName'): 最常用的导航方法，导航到指定的屏幕。如果该屏幕已经在栈中且不是栈顶，会回到该屏幕并移除其上的所有屏幕（默认行为）。如果屏幕不在栈中，则推入新屏幕。
• navigation.push('ScreenName'): 总是将新屏幕推入栈顶，即使该屏幕已经在栈中。适用于同一屏幕的多次进入（如详情页A -> 详情页B -> 详情页C）。
• navigation.goBack(): 返回上一个屏幕。
• navigation.popToTop(): 返回栈中的第一个屏幕（通常是 Home 屏幕）。

不同类型的导航器详解

除了 Stack Navigator，React Navigation 还提供了其他重要的导航器：

1. Tab Navigator (标签页导航器)

标签页导航器常用于应用的根层级，提供在不同主要功能模块之间快速切换的方式。React Navigation 提供了两种常见的 Tab Navigator：底部标签页 (@react-navigation/bottom-tabs) 和顶部标签页 (@react-navigation/material-top-tabs 或 @react-navigation/material-bottom-tabs)。

安装：

“`bash

底部标签页

npm install @react-navigation/bottom-tabs

顶部标签页 (需要 react-native-tab-view 和 react-native-pager-view)

npm install @react-navigation/material-top-tabs react-native-tab-view react-native-pager-view

Material Design 风格的底部标签页 (需要 react-native-paper 和 react-native-vector-icons)

npm install @react-navigation/material-bottom-tabs react-native-paper react-native-vector-icons
“`

使用示例 (底部标签页):

“`javascript
import { createBottomTabNavigator } from ‘@react-navigation/bottom-tabs’;
import Ionicons from ‘react-native-vector-icons/Ionicons’; // 示例图标库

function SettingsScreen() { / … / }
function ProfileScreen() { / … / }

const Tab = createBottomTabNavigator();

function MyTabs() {
return (
({
tabBarIcon: ({ focused, color, size }) => {
let iconName;
if (route.name === ‘Home’) {
iconName = focused ? ‘home’ : ‘home-outline’;
} else if (route.name === ‘Settings’) {
iconName = focused ? ‘settings’ : ‘settings-outline’;
} else if (route.name === ‘Profile’) {
iconName = focused ? ‘person’ : ‘person-outline’;
}
// 返回一个图标组件
return ;
},
tabBarActiveTintColor: ‘tomato’, // 选中标签的颜色
tabBarInactiveTintColor: ‘gray’, // 未选中标签的颜色
headerShown: false, // 通常在 Tab Navigator 内部隐藏头部，由 Stack Navigator 提供
})}
>




);
}

// 在 App.js 中使用 MyTabs 作为根导航器或嵌套在 Stack 中
//
“`

特点：

• tabBarIcon: 一个函数，用于自定义每个标签的图标。
• tabBarLabel: 自定义标签文本。
• tabBarActiveTintColor, tabBarInactiveTintColor: 设置选中/未选中状态的颜色。
• headerShown: 控制是否显示顶部导航头部，通常在 Tab Navigator 的根层级设置为 false，让 Stack Navigator 管理头部。

2. Drawer Navigator (抽屉导航器)

抽屉导航器（侧滑菜单）适用于存放应用的辅助功能或全局设置。

安装：

bash
npm install @react-navigation/drawer

使用示例：

“`javascript
import { createDrawerNavigator } from ‘@react-navigation/drawer’;

function NotificationsScreen() { / … / }

const Drawer = createDrawerNavigator();

function MyDrawer() {
return (




);
}

// 在 App.js 中使用 MyDrawer
//
“`

特点：

• 通过从屏幕侧边滑动或点击头部左侧的汉堡图标来打开/关闭抽屉。
• drawerPosition: 设置抽屉从左侧还是右侧滑出。
• drawerContent: 自定义抽屉内部的渲染内容，可以放置导航链接、用户信息等。

导航动作与参数传递

navigation 对象提供了多种方法来控制导航流程：

• navigation.navigate(name, params): 导航到指定名称的屏幕。如果目标屏幕已经在栈中，会回到该屏幕（如果不是栈顶）。可以传递可选的 params 对象。
• navigation.push(name, params): 总是将新屏幕推入栈顶。适用于需要打开同一个屏幕多次的场景。
• navigation.goBack(): 返回上一个屏幕。
• navigation.pop(count): 返回栈中指定数量的屏幕。pop(1) 等同于 goBack()。
• navigation.popToTop(): 返回栈中的第一个屏幕。
• navigation.replace(name, params): 用新屏幕替换当前屏幕，当前屏幕会被销毁。常用于登录成功后替换登录页为 Home 页。
• navigation.setParams(params): 更新当前屏幕的路由参数，不会引起屏幕切换，但会触发 route.params 的更新。
• navigation.setOptions(options): 动态更新当前屏幕的导航器选项（如头部标题、按钮等）。

传递和接收参数：

在调用 navigate 或 push 时，可以传递一个参数对象作为第二个参数：

javascript
navigation.navigate('Details', {
itemId: 86,
otherParam: 'anything you want here',
});

在目标屏幕组件中，可以通过 route.params 来访问这些参数：

“`javascript
function DetailsScreen({ route }) {
const { itemId, otherParam } = route.params; // 直接解构获取参数
// 或者使用默认值防止参数不存在时出错
const { itemId, otherParam } = route.params || {};

return (

Item ID: {itemId}
Other: {otherParam}

);
}
“`

高级用法与实践

1. 配置屏幕选项 (Options)

options prop 允许你配置屏幕在导航器中的显示方式，例如头部标题、样式、按钮等。

javascript
<Stack.Screen
name="Home"
component={HomeScreen}
options={{
title: 'Awesome app', // 设置头部标题
headerStyle: {
backgroundColor: '#f4511e', // 头部背景色
},
headerTintColor: '#fff', // 头部文字和图标颜色
headerTitleStyle: {
fontWeight: 'bold', // 头部标题字体样式
},
}}
/>

你还可以使用 screenOptions prop 在导航器级别为所有屏幕设置默认选项：

“`javascript
<Stack.Navigator
screenOptions={{
headerStyle: {
backgroundColor: ‘#f4511e’,
},
headerTintColor: ‘#fff’,
headerTitleStyle: {
fontWeight: ‘bold’,
},
}}

{/ … screens … /}

“`

2. 动态设置屏幕选项

有时你需要在屏幕内部根据状态或数据动态改变头部或其他选项，可以使用 navigation.setOptions 或将 options 设置为一个函数：

使用 navigation.setOptions (在屏幕组件内部)：

“`javascript
import { useLayoutEffect } from ‘react’;

function DetailsScreen({ navigation, route }) {
const { name } = route.params;

useLayoutEffect(() => {
// 在组件渲染或参数变化后设置头部标题
navigation.setOptions({ title: ‘User: ‘ + name });
}, [navigation, name]); // 依赖项

// … rest of the component
}
“`

将 options 设置为函数 (在导航器配置中)：

javascript
<Stack.Screen
name="Details"
component={DetailsScreen}
options={({ route }) => ({ // options 是一个函数，接收 { route, navigation } 对象
title: 'User: ' + route.params.name, // 直接根据 route.params 设置标题
headerRight: () => ( // 在头部右侧添加按钮
<Button onPress={() => alert('Pressed!')} title="Info" color="#fff" />
),
})}
/>

3. 嵌套导航器 (Nesting Navigators)

实际应用中，导航结构通常是复杂的，需要将不同类型的导航器组合起来。例如，你可能希望在应用的主体部分使用底部标签页，但在某个标签页内部又有自己的栈导航，或者从标签页导航到全屏的详情页（属于一个外部的栈）。

最常见的模式是将 Tab 或 Drawer Navigator 嵌套在 Stack Navigator 内部：

“`javascript
// 假设 MyTabs 是上面的 Tab Navigator 组件
// MyStack 是 Stack Navigator
const Stack = createNativeStackNavigator();

function App() {
return (


{/ MyTabs 作为 Stack 的一个屏幕 /}

{/ DetailsScreen 也在 Stack 中，可以从 Tab 内部导航到这里 /}

{/ Other full-screen screens /}


);
}
“`

在嵌套导航器之间导航：

在嵌套结构中进行导航可能会稍微复杂一些。例如，在 HomeScreen (它在 MyTabs 内部，而 MyTabs 在 MyStack 内部) 中导航到 DetailsScreen (在 MyStack 的根层级)：

javascript
// 在 HomeScreen (位于 MainTabs 内部) 中
function HomeScreen({ navigation }) {
return (
<View>
<Text>Home Screen (inside Tabs)</Text>
{/* 导航到 Stack 外部的 Details 屏幕 */}
<Button
title="Go to Details"
onPress={() => navigation.navigate('Details', { // 使用 navigate 到外部 Stack 的屏幕
itemId: 101,
})}
/>
{/* 导航到 Tabs 内部的 Profile 屏幕 */}
<Button
title="Go to Profile Tab"
onPress={() => navigation.navigate('Profile')} // 导航到同层级 Tab 的另一个屏幕
/>
</View>
);
}

• 当使用 navigation.navigate('ScreenName') 时，React Navigation 会从当前位置向上查找，直到找到一个能够处理名为 ScreenName 的屏幕的导航器。
• 在上面的例子中，从 HomeScreen (MainTabs 的子屏幕) 调用 navigation.navigate('Details')，MyTabs 无法处理 Details，它会向上冒泡到 MyStack，MyStack 找到了 Details 屏幕并进行导航。
• 调用 navigation.navigate('Profile') 则在 MyTabs 内部处理，切换到 Profile 标签页。

4. 处理认证流程 (Authentication Flow)

一个常见的场景是根据用户登录状态显示不同的导航结构（例如，登录/注册页 vs. 应用主页）。这可以通过在根导航器中根据认证状态有条件地渲染不同的导航器来实现：

“`javascript
// App.js
import React, { useState, useEffect } from ‘react’;
import { NavigationContainer } from ‘@react-navigation/native’;
import AuthNavigator from ‘./navigation/AuthNavigator’; // 包含登录/注册页面的 Stack Navigator
import AppNavigator from ‘./navigation/AppNavigator’; // 包含应用主体的 Tab 或 Stack Navigator

function App() {
const [isLoading, setIsLoading] = useState(true);
const [userToken, setUserToken] = useState(null); // 示例用户认证状态

useEffect(() => {
// 模拟检查本地存储中的用户 token
setTimeout(() => {
// 在实际应用中，这里会从 AsyncStorage 或其他地方读取 token
const token = null; // 或者读取到的 token
setUserToken(token);
setIsLoading(false);
}, 1000);
}, []);

if (isLoading) {
// 显示一个加载指示器或启动屏幕
return ;
}

return (

{userToken == null ? (
// 用户未登录，渲染认证导航器

) : (
// 用户已登录，渲染应用主导航器

)}

);
}
“`

在 AuthNavigator 中，可能包含 LoginScreen, RegisterScreen 等。在 AppNavigator 中，可能包含 Stack, Tab, Drawer 等组合。当用户登录成功后，更新 userToken 状态，React Navigation 会重新渲染，显示 AppNavigator。

5. 从非屏幕组件访问导航

有时你可能需要在屏幕组件之外的地方执行导航，例如 Redux action 中、全局函数中或自定义头部组件中。React Navigation 提供了几种方式：

• 使用 useNavigationContainerRef (推荐在 React Hooks 环境中)：

“`javascript
// App.js (或 Navigation 根文件)
import { NavigationContainer, useNavigationContainerRef } from ‘@react-navigation/native’;
import * as RootNavigation from ‘./RootNavigation’; // 创建一个单独文件导出导航方法

function App() {
const navigationRef = useNavigationContainerRef();

return (
{
// 在导航容器准备好后，将 ref 暴露出去
RootNavigation.setTopLevelNavigator(navigationRef);
}}
>
{/ … your navigators … /}

);
}

// RootNavigation.js (新文件)
import * as React from ‘react’;

export const navigationRef = React.createRef();

export function navigate(name, params) {
navigationRef.current?.navigate(name, params);
}

export function goBack() {
navigationRef.current?.goBack();
}

// 其他导航方法同理…

// 在任何需要导航的地方导入并使用 navigate 或 goBack
// import * as RootNavigation from ‘./RootNavigation’;
// RootNavigation.navigate(‘SomeScreen’);

“`

• 使用 ref (类组件或旧代码): 类似于上面的方法，但使用传统的 ref 对象。

注意： 这种从外部控制导航的方式应谨慎使用，因为它可能打破组件的封装性。优先考虑在屏幕组件内部使用 useNavigation Hook。

性能与优化

• 使用 Native Stack Navigator (@react-navigation/native-stack): 如果主要使用栈导航，优先选择原生栈导航器，它利用平台原生组件，提供更好的性能和手势体验。
• 懒加载屏幕组件: 对于 Tab Navigator 或 Drawer Navigator 中不常用的屏幕，可以考虑使用 React.lazy 和 Suspense 进行懒加载，减少初始 Bundle 大小和启动时间。
• 优化屏幕组件: 确保你的屏幕组件本身是高性能的，避免不必要的渲染和复杂的计算。
• 避免在 options 中执行复杂计算: options 函数会在导航状态变化时频繁执行，其中的代码应该尽量简单高效。

常见问题与故障排除

• “The action ‘NAVIGATE’ with payload {…} was not handled by any navigator.”:
  • 原因：你尝试导航到的屏幕名称 (name) 未在当前导航器或其父级导航器中定义。
  • 解决方法：检查导航器配置中的 <Navigator.Screen name="..."> 是否与 navigation.navigate('...') 中的名称一致。确保目标屏幕位于可以被当前导航器访问到的地方（检查嵌套结构）。
• 手势或动画问题:
  • 原因：可能未正确安装或导入 react-native-gesture-handler。
  • 解决方法：确保 react-native-gesture-handler 已安装并在入口文件顶部导入。
• 安全区域问题 (内容被刘海屏或底部指示条遮挡):
  • 原因：可能未正确使用 react-native-safe-area-context。
  • 解决方法：确保已安装 react-native-safe-area-context 并在根组件或导航容器外部使用 SafeAreaProvider 包裹应用。

总结

React Navigation 是 React Native 应用中实现导航功能的首选库。它提供了多种强大的导航器类型，灵活的配置选项，以及直观的 API，能够满足从简单到复杂的各种导航需求。

通过本文的介绍，你已经了解了 React Navigation 的核心概念、基本设置、不同导航器的用法，以及参数传递、动态配置、嵌套导航、认证流程处理等高级实践。掌握这些知识，你就可以构建出具有流畅导航体验的 React Native 应用。

导航是应用的基础架构，理解并熟练运用 React Navigation 是每一个 React Native 开发者的必备技能。鼓励你动手实践，结合官方文档进一步探索更多定制化和高级功能！