React Navigation v6+TypeScript：多参数导航器类型定义报错解决

问题原因 #

1. 你的AppNavigatorParamList中Wizard的参数是三种类型的联合：带pageId的对象、NavigatorScreenParams、undefined。TypeScript无法通过useRoute()直接确定当前参数的具体类型，而NavigatorScreenParams和undefined类型都没有pageId属性，因此触发报错。
2. 同时，WizardNavigatorParamList的初始路由未定义接收pageId的参数，导致参数传递逻辑和类型系统不匹配。

解决方法 #

方法一：修正路由参数关联（推荐） #

调整嵌套导航器的参数定义，让初始路由支持接收pageId，同时简化根导航器的参数类型：

// 嵌套导航器参数列表：让初始路由支持可选的pageId
export type WizardNavigatorParamList = {
  WizardOne: { pageId?: number };
  WizardTwo: undefined;
};

// 根导航器参数列表
export type AppNavigatorParamList = {
  // ...其他路由定义
  Wizard: 
    | { pageId?: number } // 直接进入导航器时的参数（会传递给初始路由）
    | NavigatorScreenParams<WizardNavigatorParamList>; // 跳转子页面时的参数
};

调用示例：

// 无参数进入初始页面
navigation.navigate('Wizard');
// 带pageId进入初始页面
navigation.navigate('Wizard', { pageId: 123 });
// 跳转到指定子页面
navigation.navigate('Wizard', { screen: 'WizardOne' });
// 跳转到指定子页面并传参
navigation.navigate('Wizard', { screen: 'WizardOne', params: { pageId: 123 } });

在WizardOne组件中安全获取参数：

import { useRoute } from '@react-navigation/native';
import type { RouteProp } from '@react-navigation/native';
import type { WizardNavigatorParamList } from './your-types-path';

const route = useRoute<RouteProp<WizardNavigatorParamList, 'WizardOne'>>();
const pageId = route.params?.pageId; // TypeScript 无报错

方法二：使用类型守卫收窄参数 #

如果不想修改嵌套导航器的参数定义，可在组件中通过类型守卫明确参数类型：

import { useRoute } from '@react-navigation/native';
import type { RouteProp } from '@react-navigation/native';
import type { AppNavigatorParamList } from './your-types-path';

const route = useRoute<RouteProp<AppNavigatorParamList, 'Wizard'>>();
const params = route.params;

// 自定义类型守卫：判断参数是否包含合法的pageId
function hasValidPageId(params: unknown): params is { pageId: number } {
  return typeof params === 'object' && params !== null && 'pageId' in params && typeof (params as any).pageId === 'number';
}

if (hasValidPageId(params)) {
  console.log(params.pageId); // TypeScript 此时会识别参数类型，无报错
}

方法三：添加区分字段的联合类型 #

给不同参数场景添加区分字段，让TypeScript自动识别类型：

export type AppNavigatorParamList = {
  // ...其他路由定义
  Wizard:
    | {
        type: 'root';
        pageId: number;
      }
    | NavigatorScreenParams<WizardNavigatorParamList>
    | undefined;
};

export type WizardNavigatorParamList = {
  WizardOne: undefined;
  WizardTwo: undefined;
};

调用示例：

// 带pageId进入根页面
navigation.navigate('Wizard', { type: 'root', pageId: 123 });
// 跳转子页面
navigation.navigate('Wizard', { screen: 'WizardOne' });
// 无参数进入根页面
navigation.navigate('Wizard');

组件中获取参数：

const route = useRoute<RouteProp<AppNavigatorParamList, 'Wizard'>>();
const params = route.params;

if (params?.type === 'root') {
  console.log(params.pageId); // TypeScript 无报错
}

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