如何正确为React Navigation导航器添加类型？解决类型报错

问题描述 #

我为顶级导航器编写了如下代码：

type NavigationParamList = {
  Instances: undefined;
  Default: undefined;
  Settings: undefined;
  Compose: undefined;
};

const AppStack = createNativeStackNavigator<NavigationParamList>();

<NavigationContainer theme={NavTheme}>
      <AppStack.Navigator initialRouteName="Default">
        <AppStack.Screen
          name="Instances"
          component={InstancesScreen}
        />
        {/* 其他Screen省略 */}
      </AppStack.Navigator>
</NavigationContainer>

但调用navigation.navigate('Instances')时，出现如下类型报错：

No overload matches this call.
  Overload 1 of 2, '(...args: never): void', gave the following error.
    Argument of type 'string' is not assignable to parameter of type 'never'.
  Overload 2 of 2, '(options: never): void', gave the following error.
    Argument of type 'string' is not assignable to parameter of type 'never'.

解决方法 #

1. 为组件的navigation指定类型 #

在函数组件中使用useNavigation钩子时，显式传入你的NavigationParamList泛型：

import { useNavigation } from '@react-navigation/native';
import type { NativeStackNavigationProp } from '@react-navigation/native-stack';
// 导入你定义的NavigationParamList
import type { NavigationParamList } from './path/to/your/param-list-file';

// 定义专属的导航类型
type AppNavigationProp = NativeStackNavigationProp<NavigationParamList>;

const InstancesScreen = () => {
  // 传入泛型指定导航类型
  const navigation = useNavigation<AppNavigationProp>();

  // 此时调用navigate不会报错
  const handleNavigate = () => {
    navigation.navigate('Instances');
  };

  return <View>{/* 组件内容 */}</View>;
};

2. 通过组件Props传递类型 #

如果是通过props接收navigation，直接给props添加类型声明：

import type { NativeStackNavigationProp } from '@react-navigation/native-stack';
import type { NavigationParamList } from './path/to/your/param-list-file';

type InstancesScreenProps = {
  navigation: NativeStackNavigationProp<NavigationParamList>;
};

const InstancesScreen = ({ navigation }: InstancesScreenProps) => {
  navigation.navigate('Instances');
  return <View>{/* 组件内容 */}</View>;
};

3. 全局类型声明（可选） #

若想在整个项目中统一导航类型，避免重复指定泛型，可以创建全局类型文件：
在项目根目录创建@types/navigation.d.ts，内容如下：

import type { NavigationParamList } from '../path/to/your/param-list-file';
import type { NativeStackNavigationProp } from '@react-navigation/native-stack';

declare global {
  namespace ReactNavigation {
    interface RootParamList extends NavigationParamList {}
  }
}

之后使用useNavigation时，TypeScript会自动识别全局的RootParamList，无需手动传入泛型。

核心原因 #

报错的本质是TypeScript无法自动推断navigation.navigate的参数类型——默认的navigation对象没有关联你定义的NavigationParamList。通过显式指定泛型，让TypeScript明确允许跳转的路由名称及对应参数类型，就能解决类型不匹配的问题。

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