React Native TypeScript Stack Navigator 实现及类型适配方案

问题背景 #

作为完全不懂JS/TS的React Native新手，JavaScript项目里栈导航能正常运行，但切换到TypeScript（.tsx文件）时，调用navigation.navigate会报错。核心原因是TypeScript要求明确的导航类型声明来保证类型安全，不像JS那样允许随意调用。

核心解决方案：定义导航类型 #

解决问题的关键是给导航器定义屏幕路由类型，让TypeScript识别所有可跳转的屏幕名称及对应参数。

核心文件代码实现 #

1. 定义导航类型文件（navigation/types.ts） #

创建类型声明文件，明确栈导航的所有屏幕名称和参数规则：

// navigation/types.ts
export type RootStackParamList = {
  Home: undefined; // Home屏幕无需参数，用undefined标记
  Details: { itemId: number; itemName: string }; // Details屏幕需要两个参数
};

2. 创建栈导航器（navigation/StackNavigator.tsx） #

用上述类型约束栈导航器，确保所有注册屏幕符合类型规则：

// navigation/StackNavigator.tsx
import React from 'react';
import { createStackNavigator } from '@react-navigation/stack';
import { RootStackParamList } from './types';
import HomeScreen from '../screens/HomeScreen';
import DetailsScreen from '../screens/DetailsScreen';

// 用RootStackParamList约束StackNavigator的类型
const Stack = createStackNavigator<RootStackParamList>();

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

export default StackNavigator;

3. 在HomeScreen中调用导航（screens/HomeScreen.tsx） #

通过类型约束导航对象，TypeScript会自动校验跳转参数的合法性：

// screens/HomeScreen.tsx
import React from 'react';
import { View, Button, StyleSheet } from 'react-native';
import { useNavigation } from '@react-navigation/native';
import type { StackNavigationProp } from '@react-navigation/stack';
import { RootStackParamList } from '../navigation/types';

// 定义Home屏幕专属的导航类型
type HomeScreenNavigationProp = StackNavigationProp<
  RootStackParamList,
  'Home'
>;

const HomeScreen = () => {
  // 用自定义类型约束useNavigation返回值
  const navigation = useNavigation<HomeScreenNavigationProp>();

  return (
    <View style={styles.container}>
      <Button
        title="跳转到详情页"
        onPress={() => {
          // 写错屏幕名/参数类型时，TypeScript会直接报错
          navigation.navigate('Details', {
            itemId: 1,
            itemName: '测试商品'
          });
        }}
      />
    </View>
  );
};

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

export default HomeScreen;

4. 在DetailsScreen接收参数（screens/DetailsScreen.tsx） #

用类型约束路由参数，避免访问未定义的参数：

// screens/DetailsScreen.tsx
import React from 'react';
import { View, Text, StyleSheet } from 'react-native';
import type { RouteProp } from '@react-navigation/native';
import { RootStackParamList } from '../navigation/types';

// 定义Details屏幕的路由参数类型
type DetailsScreenRouteProp = RouteProp<RootStackParamList, 'Details'>;

interface Props {
  route: DetailsScreenRouteProp;
}

const DetailsScreen = ({ route }: Props) => {
  // TypeScript会自动提示参数，确保访问安全
  const { itemId, itemName } = route.params;

  return (
    <View style={styles.container}>
      <Text>商品ID: {itemId}</Text>
      <Text>商品名称: {itemName}</Text>
    </View>
  );
};

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

export default DetailsScreen;

5. App入口文件（App.tsx） #

将导航器集成到应用入口：

// App.tsx
import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import StackNavigator from './navigation/StackNavigator';

const App = () => {
  return (
    <NavigationContainer>
      <StackNavigator />
    </NavigationContainer>
  );
};

export default App;

关键解析 #

1. RootStackParamList：核心类型定义，列出所有栈屏幕名称及参数规则，是TypeScript校验导航合法性的依据。
2. StackNavigationProp：约束useNavigation返回的导航对象，确保只能调用合法的屏幕名称和参数。
3. RouteProp：约束route对象，确保安全访问对应屏幕的参数，避免运行时未定义错误。

实现后，TypeScript会在写错屏幕名、参数类型或缺失参数时即时报错，同时提供友好的代码提示，既解决了导航调用问题，也实现了类型安全。

内容的提问来源于stack exchange，提问作者Ali Kartal