React Native：如何全局配置React Navigation类型，避免重复定义NavigationProps

问题场景 #

目前在routes.tsx中维护了所有路由的ParamList类型，但每个使用useNavigation()的屏幕组件都需要单独创建对应的导航类型声明（比如GetStartedScreen.tsx中要手动定义GetStartedScreenNavigationProps），希望通过全局配置避免这类重复操作。

现有代码示例 #

routes.tsx

export type AuthStackParamList = {
  Landing: undefined;
  GetStarted: undefined;
  VerifyOtp: { email: string };
  PrivacyPolicy: undefined;
  TermsOfService: undefined;
};

export type AppTabParamList = {
  HomeScreen: undefined;
  FriendsScreen: undefined;
  NotificationsScreen: undefined;
  SettingsScreen: undefined;
};

export type OnboardingStackParamList = {
  UsernameScreen: undefined;
};

export type HomeTabStackParamList = {
  Home: undefined;
};

export type FriendsTabStackParamList = {
  Friends: undefined;
  SearchUsers: undefined;
};

export type SettingsTabStackParamList = {
  Settings: undefined;
  EditName: { id: string; name: string };
  EditUsername: { id: string; username: string };
  DeleteAccount: undefined;
};

AuthStack.tsx

const AuthStack = createNativeStackNavigator<AuthStackParamList>();

export function AuthStackNavigator() {
  return (
    <AuthStack.Navigator
      initialRouteName="Landing"
      }}>
      <AuthStack.Screen
        name="Landing"
        component={LandingScreen}
        options={{ headerShown: false }}
      />
      <AuthStack.Screen
        name="GetStarted"
        component={GetStartedScreen}
        options={{ headerTitle: '' }}
      />
      <AuthStack.Screen
        name="VerifyOtp"
        component={VerifyOTPScreen}
        options={{ headerShown: false, gestureEnabled: false }}
      />
      <AuthStack.Screen
        name="TermsOfService"
        component={TermsOfServiceScreen}
        options={{ headerTitle: 'Terms of Service' }}
      />
      <AuthStack.Screen
        name="PrivacyPolicy"
        component={PrivacyPolicy}
        options={{ headerTitle: 'Privacy Policy' }}
      />
    </AuthStack.Navigator>
  );
}

希望避免的重复操作（GetStartedScreen.tsx）

type GetStartedScreenNavigationProps = NativeStackNavigationProp<
  AuthStackParamList,
  'GetStarted'
>;

const GetStartedScreen = () => {
  const navigation = useNavigation<GetStartedScreenNavigationProps>();

解决方案 #

方案1：全局扩展React Navigation根类型 #

通过全局类型声明，让useNavigation自动识别所有路由类型，无需每次手动指定。

1. 在routes.tsx中添加全局类型声明：

// routes.tsx
import { NativeStackNavigationProp } from '@react-navigation/native-stack';
import { BottomTabNavigationProp } from '@react-navigation/bottom-tabs';

// 保留原有的所有ParamList类型...

// 定义根路由映射（如果是嵌套导航，这里对应各个栈/标签页的入口）
export type RootStackParamList = {
  AuthStack: undefined;
  AppTab: undefined;
  OnboardingStack: undefined;
  // 若需直接跳转至子栈的具体屏幕，可在此添加，例如：
  // VerifyOtp: AuthStackParamList['VerifyOtp'];
};

// 全局扩展React Navigation的默认类型
declare global {
  namespace ReactNavigation {
    interface RootParamList extends RootStackParamList {}
  }
}

2. 在组件中直接使用useNavigation：

// GetStartedScreen.tsx
import { useNavigation } from '@react-navigation/native';

const GetStartedScreen = () => {
  const navigation = useNavigation();
  // 此时navigation的跳转方法会自动校验路由名称和参数类型
  navigation.navigate('VerifyOtp', { email: 'user@example.com' });
};

方案2：预定义各栈的导航类型 #

如果需要更精准的类型（仅包含当前栈的路由），可以在routes.tsx中提前定义好每个栈的导航类型，直接导入使用。

1. 在routes.tsx中添加预定义的导航类型：

// routes.tsx
// 保留原有的所有ParamList类型...

// 预定义各栈的导航类型
export type AuthNavigationProp = NativeStackNavigationProp<AuthStackParamList>;
export type AppTabNavigationProp = BottomTabNavigationProp<AppTabParamList>;
export type SettingsTabNavigationProp = NativeStackNavigationProp<SettingsTabStackParamList>;
// 其他栈的导航类型依此类推

2. 在组件中导入使用：

// GetStartedScreen.tsx
import { useNavigation } from '@react-navigation/native';
import { AuthNavigationProp } from '../routes';

const GetStartedScreen = () => {
  const navigation = useNavigation<AuthNavigationProp>();
};

方案3：封装自定义useNavigation钩子 #

进一步封装钩子，简化组件中的导入和使用：

1. 创建hooks/useAppNavigation.ts：

// hooks/useAppNavigation.ts
import { useNavigation, NavigationProp } from '@react-navigation/native';
import { RootStackParamList } from '../routes';

export const useAppNavigation = () => useNavigation<NavigationProp<RootStackParamList>>();

2. 在组件中使用自定义钩子：

// GetStartedScreen.tsx
import { useAppNavigation } from '../hooks/useAppNavigation';

const GetStartedScreen = () => {
  const navigation = useAppNavigation();
};

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