当前位置：首页 > news >正文

React Navigation 使用指南

news 来源：原创 2025/4/30 5:30:44

React Navigation 使用指南

React Navigation 介绍

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 的硬件返回键处理、顶部标题栏布局。
内置平滑的页面切换动画（如渐变、滑动）和手势交互，确保用户体验接近原生应用。

React Navigation 初体验

安装依赖
@react-navigation/native：React Native 导航核心
@react-navigation/native-stack：原生级栈导航
@react-navigation/elements：预制导航栏 UI 组件（按钮 / 标题），快速美化导航栏
react-native-screens：把页面渲染成原生视图，让导航动画丝滑
react-native-safe-area-context：防刘海屏 / 挖孔屏遮挡，给内容留安全空间

npm i @react-navigation/elements @react-navigation/native @react-navigation/native-stack react-native-screens react-native-safe-area-context

基本结构
1. 创建页面组件
2. 创建堆栈导航器
3. 配置路由结构
4. 应用入口组件

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",},
});

React Navigation 基本属性

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

Stack.Navigator
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` 方法	在组件内部动态更新当前屏幕的选项（如按钮点击时修改标题）。	方法调用，传入选项对象

React Navigation 跳转

定义调整到路由的类型
指定跳转 navigate
返回上一个页面 goBack

ReactNavigation-路由跳转流程

// In App.js in a new projectimport { 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 的区别

navigate 会复用页面
push 会不断往路由栈中添加页面

      <Text onPress={() => navigation.navigate('Details')}>Details navigate</Text><Text onPress={() => navigation.push('Home')}>Home push</Text>

React Navigation 携带参数接收参数

定义参数类型
传递参数
接收参数

ReactNavigation-参数传递

// In App.js in a new projectimport { 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><TextonPress={() =>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",},
});

React Navigation 嵌套路由

ReactNavigation-嵌套路由

配置顶层路由

<Stack.Navigator initialRouteName="HomeTabs">{/* 注册路由 - 首页 */}<Stack.Screen name="HomeTabs" component={HomeTabs} />{/* 注册路由 - 详情页 */}<Stack.Screen name="Details" component={DetailsScreen} />
</Stack.Navigator>

配置二级路由

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

完整代码

// In App.js in a new projectimport { 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}><TextonPress={() =>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",},
});