React Navigation嵌套栈导航TypeScript类型校验异常求助

核心问题定位 #

你遇到的类型校验异常，本质是顶层栈与子栈的参数类型关联逻辑错误——顶层栈定义子栈路由时，未正确使用NavigatorScreenParams包裹子栈的完整参数列表，导致传参、取值的类型不匹配。

1. 修正路由参数类型定义 #

先明确子栈的完整路由参数，再在顶层栈中通过NavigatorScreenParams关联子栈的参数列表，而非直接绑定单个路由的参数。

正确的类型定义示例 #

import { NavigatorScreenParams } from '@react-navigation/native';

// 定义二级SubStack的所有路由参数
type SubStackParamList = {
  // 子栈首页，接收someParam参数
  SubStackHome: { someParam: string };
  // 子栈嵌套页面，接收nestedParam参数
  SubStackNestedScreen: { nestedParam: number };
};

// 定义顶层Main栈的路由参数
type MainStackParamList = {
  Home: undefined; // 顶层首页无参数
  // 用NavigatorScreenParams包裹子栈的完整参数列表
  SubStack: NavigatorScreenParams<SubStackParamList>;
};

错误写法对比（你可能踩的坑） #

如果直接在顶层栈中指定子栈路由的单个参数，会导致类型不兼容：

// 错误：直接绑定子栈单个路由的参数，而非完整参数列表
type MainStackParamList = {
  SubStack: { someParam: string };
};

2. 子栈组件正确获取参数 #

在子栈的页面组件中，通过RouteProp明确指定当前路由的参数类型，即可正常取值：

import { RouteProp } from '@react-navigation/native';

// 明确当前页面的路由参数类型
type SubStackHomeRouteProp = RouteProp<SubStackParamList, 'SubStackHome'>;

const SubStackHome = ({ route }: { route: SubStackHomeRouteProp }) => {
  // 此处TS不会报错，可正常获取someParam
  const { someParam } = route.params;
  return <Text>{someParam}</Text>;
};

3. 导航传参的正确写法 #

从顶层栈跳转到子栈首页 #

必须按照NavigatorScreenParams的结构传参，同时指定子栈的具体页面：

// 正确写法：参数放在子栈路由的params字段中
navigation.navigate('SubStack', {
  screen: 'SubStackHome',
  params: { someParam: '测试值' },
});

子栈内部跳转嵌套页面 #

直接传参即可，无需嵌套结构：

navigation.navigate('SubStackNestedScreen', { nestedParam: 123 });

4. 导航器的类型注解补充 #

确保导航器也绑定对应的参数类型，避免隐性类型错误：

import { createStackNavigator } from '@react-navigation/stack';

// 二级SubStack导航器，绑定SubStackParamList
const SubStack = createStackNavigator<SubStackParamList>();

function SubStackNavigator() {
  return (
    <SubStack.Navigator>
      <SubStack.Screen name="SubStackHome" component={SubStackHome} />
      <SubStack.Screen name="SubStackNestedScreen" component={SubStackNestedScreen} />
    </SubStack.Navigator>
  );
}

// 顶层Main栈导航器，绑定MainStackParamList
const MainStack = createStackNavigator<MainStackParamList>();

export function MainNavigator() {
  return (
    <MainStack.Navigator>
      <MainStack.Screen name="Home" component={HomeScreen} />
      <MainStack.Screen name="SubStack" component={SubStackNavigator} />
    </MainStack.Navigator>
  );
}

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