React Navigation 使用指南

爱笑的眼睛112025-04-30 21:38

React Navigation 是 React Native 中推荐的路由管理方案。

1. 开箱即用，快速上手（Easy to Use）
  • 提供 内置导航器（Built-in Navigators），如栈导航（Stack Navigator）、标签导航（Tab Navigator）、抽屉导航（Drawer Navigator）等，无需从零搭建导航逻辑，大幅降低开发成本。
  • 支持快速配置基础导航功能（如页面跳转、返回、参数传递），适合新手快速入门和项目快速迭代。
2. 跨平台适配，原生体验（Components for iOS & Android）

  • 自动适配 iOS 和 Android 平台的视觉规范与交互逻辑，例如：

    • iOS 的滑动返回手势、底部标签栏样式；
    • Android 的硬件返回键处理、顶部标题栏布局。

  • 内置平滑的页面切换动画（如渐变、滑动）和手势交互，确保用户体验接近原生应用。

  1. 安装依赖

  2. @react-navigation/native：React Native 导航核心

  3. @react-navigation/native-stack：原生级栈导航

  4. @react-navigation/elements：预制导航栏 UI 组件（按钮 / 标题），快速美化导航栏

  5. react-native-screens：把页面渲染成原生视图，让导航动画丝滑

  6. react-native-safe-area-context：防刘海屏 / 挖孔屏遮挡，给内容留安全空间

tsx 复制代码 
npm i @react-navigation/elements @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context

  1. 基本结构

    1. 创建页面组件
    2. 创建堆栈导航器
    3. 配置路由结构
    4. 应用入口组件
tsx 复制代码 
import { View, Text, StyleSheet } from "react-native";
import { NavigationContainer } from "@react-navigation/native";
import { createNativeStackNavigator } from "@react-navigation/native-stack";

// 1. 创建页面组件
// 首页组件
function HomeScreen() {
  return (
    <View style={styles.container}>
      <Text>Home Scre1en</Text>
    </View>
  );
}

// 详情页组件
function DetailsScreen() {
  return (
    <View style={styles.container}>
      <Text>HomeDetailsScreen Scre1en</Text>
    </View>
  );
}

// 2. 创建堆栈导航器
const Stack = createNativeStackNavigator();

// 3. 配置路由结构
function RootStack() {
  return (
    <Stack.Navigator initialRouteName="Home">
      {/* 注册路由 - 首页 */}
      <Stack.Screen name="Home" component={HomeScreen} />
      {/* 注册路由 - 详情页 */}
      <Stack.Screen name="Details" component={DetailsScreen} />
    </Stack.Navigator>
  );
}

// 4. 应用入口组件
export default function App() {
  return (
    // 包裹在NavigationContainer中以启用导航功能
    <NavigationContainer>
      <RootStack />
    </NavigationContainer>
  );
}

// 5. 定义样式
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    justifyContent: "center",
  },
});

我们要配置属性的位置主要在两个地方

  1. Stack.Navigator
  2. Stack.Screen

Stack.Navigator

配置名称 功能描述 类型
ID 导航器的可选唯一标识符，用于在子导航器中通过 navigation.getParent() 引用当前导航器。 字符串（可选）
initialRouteName 导航器首次加载时渲染的路由名称。 字符串（可选，默认值取决于导航器类型）
layout 导航器的布局包装器，用于在导航器外层添加额外 UI（如面包屑、全局容器等），可访问导航器状态、描述符和导航方法。 函数，参数为 { children, state, descriptors, navigation }，返回 React 元素
screenOptions 导航器中所有屏幕的默认配置选项，可统一设置屏幕级属性（如标题、动画等）。 对象 或 函数（返回对象，参数为 { route, navigation, screen }）
screenListeners 注册屏幕级事件监听器（如屏幕聚焦、模糊事件）。 对象，键为事件名（如 focus、blur），值为回调函数
screenLayout 每个屏幕的布局包装器，用于为所有屏幕添加公共包裹组件（如错误边界、加载状态等）。 函数，参数为 { children }，返回 React 元素

Stack.Screen

配置方式 功能描述 类型
Screen 组件的 options 为单个屏幕配置专属选项（如标题、导航栏按钮等），优先级最高。 对象 或 函数（返回对象）
Group 组件的 screenOptions 为分组内的所有屏幕配置共享选项，适用于批量设置同类屏幕的公共选项（如模态窗口样式）。 对象 或 函数（返回对象）
导航器的 screenOptions 为导航器内的所有屏幕配置全局默认选项（如统一的导航栏背景色、标签栏图标样式）。 对象 或 函数（返回对象）
navigation.setOptions 方法 在组件内部动态更新当前屏幕的选项（如按钮点击时修改标题）。 方法调用，传入选项对象
  1. 定义调整到路由的类型
  2. 指定跳转 navigate
  3. 返回上一个页面 goBack
tsx 复制代码 
// In App.js in a new project

import { View, Text, StyleSheet } from "react-native";
import { NavigationContainer, useNavigation } from "@react-navigation/native";
import { createNativeStackNavigator } from "@react-navigation/native-stack";
import type { NativeStackNavigationProp } from "@react-navigation/native-stack";

// 1 定义导航类型
type RootStackParamList = {
  Home: undefined;
  Details: undefined;
};
type HomeScreenNavigationProp = NativeStackNavigationProp<RootStackParamList>;

function HomeScreen() {
  const navigation = useNavigation<HomeScreenNavigationProp>();
  return (
    <View style={styles.container}>
      {/* 2 跳转 */}
      <Text onPress={() => navigation.navigate("Details")}>Home Scre1en</Text>
    </View>
  );
}
function DetailsScreen() {
  const navigation = useNavigation<HomeScreenNavigationProp>();
  return (
    <View style={styles.container}>
      {/* 3 返回 */}
      <Text onPress={() => navigation.goBack()}>HomeDetailsScreen Scre1en</Text>
    </View>
  );
}

const Stack = createNativeStackNavigator();

function RootStack() {
  return (
    <Stack.Navigator initialRouteName="Home">
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen name="Details" component={DetailsScreen} />
    </Stack.Navigator>
  );
}

export default function App() {
  return (
    <NavigationContainer>
      <RootStack />
    </NavigationContainer>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    justifyContent: "center",
  },
});

navigate 和 push 的区别

  1. navigate 会复用页面
  2. push 会不断往路由栈中添加页面
tsx 复制代码 
      <Text onPress={() => navigation.navigate('Details')}>
        Details navigate
      </Text>
      <Text onPress={() => navigation.push('Home')}>Home push</Text>
  1. 定义参数类型
  2. 传递参数
  3. 接收参数
tsx 复制代码 
// In App.js in a new project

import { View, Text, StyleSheet } from "react-native";
import {
  NavigationContainer,
  useNavigation,
  useRoute,
} from "@react-navigation/native";
import { createNativeStackNavigator } from "@react-navigation/native-stack";
import type { NativeStackNavigationProp } from "@react-navigation/native-stack";
import type { RouteProp } from "@react-navigation/native";

interface NewType {
  itemId: number;
  otherParam: string;
}

// 定义导航类型
type RootStackParamList = {
  Home: undefined;
  // 定义参参数类型
  Details: NewType;
};
type HomeScreenNavigationProp = NativeStackNavigationProp<RootStackParamList>;
type DetailsScreenRouteProp = RouteProp<RootStackParamList, "Details">;

function HomeScreen() {
  const navigation = useNavigation<HomeScreenNavigationProp>();
  return (
    <View style={styles.container}>
      {/* 跳转 */}
      <Text onPress={() => navigation.navigate("Home")}>Home Scre1en</Text>
      <Text
        onPress={() =>
          navigation.navigate(
            "Details",
            // 1 传递参数
            {
              itemId: 86,
              otherParam: "anything you want here",
            }
          )
        }
      >
        Details navigate
      </Text>
    </View>
  );
}

function DetailsScreen() {
  const navigation = useNavigation<HomeScreenNavigationProp>();
  // 2 接收参数
  const route = useRoute<DetailsScreenRouteProp>();
  const { itemId, otherParam } = route.params;

  return (
    <View style={styles.container}>
      {/* 返回 */}
      <Text onPress={() => navigation.goBack()}>HomeDetailsScreen Scre1en</Text>
      <Text>itemId: {JSON.stringify(itemId)}</Text>
      <Text>otherParam: {JSON.stringify(otherParam)}</Text>
    </View>
  );
}
// 2. 创建堆栈导航器
const Stack = createNativeStackNavigator();

// 3. 配置路由结构
function RootStack() {
  return (
    <Stack.Navigator initialRouteName="Home">
      {/* 注册路由 - 首页 */}
      <Stack.Screen name="Home" component={HomeScreen} />
      {/* 注册路由 - 详情页 */}
      <Stack.Screen name="Details" component={DetailsScreen} />
    </Stack.Navigator>
  );
}

// 4. 应用入口组件
export default function App() {
  return (
    // 包裹在NavigationContainer中以启用导航功能
    <NavigationContainer>
      <RootStack />
    </NavigationContainer>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#fff",
    alignItems: "center",
    justifyContent: "center",
  },
});
  1. 配置顶层路由
tsx 复制代码 
<Stack.Navigator initialRouteName="HomeTabs">
  {/* 注册路由 - 首页 */}
  <Stack.Screen name="HomeTabs" component={HomeTabs} />
  {/* 注册路由 - 详情页 */}
  <Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>
  1. 配置二级路由
tsx 复制代码 
function HomeTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen name="HomeScreen" component={HomeScreen} />
      <Tab.Screen name="Messages" component={MessagesScreen} />
    </Tab.Navigator>
  );
}

完整代码

tsx 复制代码 
// In App.js in a new project

import { View, Text, StyleSheet } from "react-native";
import {
  NavigationContainer,
  useNavigation,
  useRoute,
} from "@react-navigation/native";
import { createNativeStackNavigator } from "@react-navigation/native-stack";
import { createBottomTabNavigator } from "@react-navigation/bottom-tabs";
import type { NativeStackNavigationProp } from "@react-navigation/native-stack";
import type { RouteProp } from "@react-navigation/native";

interface NewType {
  itemId: number;
  otherParam: string;
}

// 定义导航类型
type RootStackParamList = {
  Home: undefined;
  // 定义参参数类型
  Details: NewType;
};
type HomeScreenNavigationProp = NativeStackNavigationProp<RootStackParamList>;
type DetailsScreenRouteProp = RouteProp<RootStackParamList, "Details">;

// Create Tab navigator
const Tab = createBottomTabNavigator();

function MessagesScreen() {
  return (
    <View style={styles.container}>
      <Text>Messages Screen</Text>
    </View>
  );
}

function HomeScreen() {
  const navigation = useNavigation<HomeScreenNavigationProp>();
  return (
    <View style={styles.container}>
      <Text
        onPress={() =>
          navigation.navigate("Details", {
            itemId: 86,
            otherParam: "anything you want here",
          })
        }
      >
        Go to Details
      </Text>
    </View>
  );
}

function HomeTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen name="HomeScreen" component={HomeScreen} />
      <Tab.Screen name="Messages" component={MessagesScreen} />
    </Tab.Navigator>
  );
}

function DetailsScreen() {
  const navigation = useNavigation<HomeScreenNavigationProp>();
  const route = useRoute<DetailsScreenRouteProp>();
  const { itemId, otherParam } = route.params;
  console.log(route);

  return (
    <View style={styles.container}>
      {/* 返回 */}
      <Text onPress={() => navigation.goBack()}>HomeDetailsScreen Scre1en</Text>
      <Text>itemId: {JSON.stringify(itemId)}</Text>
      <Text>otherParam: {JSON.stringify(otherParam)}</Text>
    </View>
  );
}
// 2. 创建堆栈导航器
const Stack = createNativeStackNavigator();

// 3. 配置路由结构
function RootStack() {
  return (
    <Stack.Navigator initialRouteName="HomeTabs">
      {/* 注册路由 - 首页 */}
      <Stack.Screen name="HomeTabs" component={HomeTabs} />
      {/* 注册路由 - 详情页 */}
      <Stack.Screen name="Details" component={DetailsScreen} />
    </Stack.Navigator>
  );
}

// 4. 应用入口组件
export default function App() {
  return (
    // 包裹在NavigationContainer中以启用导航功能
    <NavigationContainer>
      <RootStack />
    </NavigationContainer>
  );
}
const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#fff",
    alignItems: "center",
    justifyContent: "center",
  },
});

React Navigation 作为 React Native 官方推荐的路由管理方案，为开发者提供了丰富且灵活的导航解决方案。通过本文的学习，我们掌握了以下关键知识点：

核心概念

  • NavigationContainer：所有导航结构的根容器，管理导航状态

  • Stack.Navigator：实现页面堆栈式切换，支持前进后退

  • Tab.Navigator：实现标签页式切换，常用于底部菜单

主要特性

  • 简单易用：提供直观的 API，快速配置导航结构

  • 类型支持：通过 TypeScript 定义可以获得完整的类型提示和检查

  • 参数传递：页面间可以方便地传递和接收参数

  • 嵌套导航：支持多层次导航结构，如标签页内嵌套堆栈导航

实用技巧

  • 导航方法：navigate 和 push 的区别，前者会复用已存在的页面，后者总是创建新页面

  • 路由参数：通过 route.params 接收传递的参数

  • 导航配置：通过 screenOptions 和 options 自定义导航外观和行为

React Navigation 不仅提供了基础的导航功能，还能适配不同平台的视觉和交互特性，让应用拥有更自然的用户体验。随着项目复杂度增加，可以利用嵌套导航和路由参数传递等高级特性构建复杂的应用界面和交互流程。

通过合理设计导航结构和使用适当的导航器组合，开发者可以创建直观、流畅且易于维护的 React Native 应用，为用户提供接近原生的应用体验。

相关推荐
萌萌哒草头将军7 小时前
🚀🚀🚀React Router 现在支持 SRC 了！！！
javascript·react.js·preact
薛定谔的算法8 小时前
# 从0到1构建React项目：一个仓库展示应用的架构实践
前端·react.js
一嘴一个橘子10 小时前
react 路由 react-router-dom
react.js
薛定谔的算法10 小时前
# 前端路由进化史：从白屏到丝滑体验的技术突围
前端·react.js·前端框架
Adolf_199312 小时前
React 中 props 的最常用用法精选+useContext
前端·javascript·react.js
前端小趴菜0512 小时前
react - 根据路由生成菜单
前端·javascript·react.js
喝拿铁写前端12 小时前
`reduce` 究竟要不要用？到底什么时候才“值得”用？
前端·javascript·面试
空の鱼12 小时前
js与vue基础学习
javascript·vue.js·学习
極光未晚12 小时前
React Hooks 中的时空穿梭：模拟 ComponentDidMount 的奇妙冒险
前端·react.js·源码
1024小神13 小时前
Cocos游戏中UI跟随模型移动，例如人物头上的血条、昵称条等
前端·javascript
热门推荐
01Cursor Claude 模型无法使用的解决方法02全球最强模型Grok4，国内已可免费使用！（附教程）03KGG转MP3工具|非KGM文件|解密音频04Cursor如何配置代理05【无标题】06集群聊天服务器---MySQL数据库的建立07突破限制：使用 Claude Code Proxy 让 Claude Code 自由连接任意模型08绿色建筑新态势：楼宇自控助力能效提升，推动成本优化新路径09Coze扣子平台完整体验和实践（附国内和国际版对比）10（5千字总结）国内如何安装和使用 Claude Code 的保姆级教程 - 支持Mac和Windows用户