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 应用，为用户提供接近原生的应用体验。

相关推荐
白瑕3 小时前
[JavaScript]对象关联风格与行为委托模式
javascript
小彭努力中3 小时前
9.Three.js中 ArrayCamera 多视角相机详解+示例代码
开发语言·前端·javascript·vue.js·数码相机·ecmascript·webgl
朝阳393 小时前
Electron Forge【实战】桌面应用 —— 将项目配置保存到本地
前端·javascript·electron
不秃的开发媛4 小时前
前端技术Ajax实战
前端·javascript·ajax
qq_419429134 小时前
uni-app中使用RenderJs 使用原生js
前端·javascript·uni-app
沃野_juededa4 小时前
uniapp自定义选项卡
java·前端·javascript
刺客-Andy5 小时前
React 第三十五节 Router 中useNavigate 的作用及用途详解
前端·javascript·react.js·前端框架
soragui5 小时前
【React】轻松掌握 React 中 useEffect的使用
前端·react.js·前端框架
沙尘暴炒饭5 小时前
解决vue3 路由query传参刷新后数据丢失的问题
开发语言·前端·javascript
热门推荐
01KGG转MP3工具|非KGM文件|解密音频02从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑03西电B测-计算机网络综合实验(含验收问题)04利用STM32实现语音识别功能05Coze扣子平台完整体验和实践（附国内和国际版对比）06DeepSeek各版本说明与优缺点分析07【SpeedAI科研小助手】2分钟极速解决知网维普重复率、AIGC率过高，一键全文降！文件格式不变，公式都保留的！08YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】09我决定放弃搞 Java 了10【VIsion Master】机器视觉软件二次开发（C#版本）学习笔记