从 React 导航迁移

了解如何使用 React Navigation 将项目迁移到 Expo Router。

React Navigation 和 Expo Router 都是用于路由和导航的 Expo 框架。Expo Router 是 React Navigation 的封装器，许多概念是相同的。

¥Both React Navigation and Expo Router are Expo frameworks for routing and navigation. Expo Router is a wrapper around React Navigation and many of the concepts are the same.

投入

¥Pitch

除了 React Navigation 的所有优点之外，Expo Router 还支持自动深度链接、类型安全、延迟打包、Web 上的静态渲染 等。

¥Along with all the benefits of React Navigation, Expo Router enables automatic deep linking, type safety, deferred bundling, static rendering on web, and more.

反投入

¥Anti-pitch

如果你的应用使用自定义 getPathFromState 或 getStateFromPath 组件，它可能不太适合 Expo Router。如果你使用这些函数来支持 共享路由，那么你应该没问题，因为 Expo Router 对此有内置支持。

¥If your app uses a custom getPathFromState or getStateFromPath component, it may not be a good fit for Expo Router. If you're using these functions to support shared routes then you should be fine as Expo Router has built-in support for this.

建议

¥Recommendations

我们建议在开始迁移之前对你的代码库进行以下修改：

¥We recommend making the following modifications to your codebase before beginning the migration:

• 将 React 导航屏幕组件拆分为单独的文件。例如，如果你有 <Stack.Screen component={HomeScreen} />，则确保 HomeScreen 类位于其自己的文件中。

  ¥Split React Navigation screen components into individual files. For example, if you have <Stack.Screen component={HomeScreen} />, then ensure the HomeScreen class is in its own file.

• 将项目转换为 TypeScript。这将使你更容易发现迁移过程中可能发生的错误。

  ¥Convert the project to TypeScript. This will make it easier to spot errors that may occur during the migration.

• 将相对导入转换为 输入别名。例如，开始迁移之前的 ../../components/button.tsx 到 @/components/button。这使得在文件系统中移动屏幕变得更容易，而无需更新相对路径。

  ¥Convert relative imports to typed aliases. For example, ../../components/button.tsx to @/components/button before starting the migration. This makes it easier to move screens around the filesystem without having to update the relative paths.

• 从 resetRoot 迁移出去。这用于在运行时对应用进行 "restart" 操作。这通常被认为是不好的做法，你应该重组应用的导航，这样就永远不会发生这种情况。

  ¥Migrate away from resetRoot. This is used to "restart" the app while running. This is generally considered bad practice, and you should restructure your app's navigation so this never needs to happen.

• 将初始路由重命名为 index。Expo Router 认为启动时打开的路由与 / 相匹配，React Navigation 用户通常会使用 "家" 等内容作为初始路由。

  ¥Rename the initial route to index. Expo Router considers the route that is opened on launch to match /, React Navigation users will generally use something such as "Home" for the initial route.

重构搜索参数

¥Refactor search parameters

将屏幕重构为 使用可序列化的顶层查询参数。我们也在 React Navigation 中推荐这一点。

¥Refactor screens to use serializable top-level query parameters. We recommend this in React Navigation as well.

在 Expo Router 中，搜索参数只能序列化顶层值，例如 number、boolean 和 string。React Navigation 没有相同的限制，因此用户有时可以传递无效参数，例如函数、对象、地图等。

¥In Expo Router, search parameters can only serialize top-level values such as number, boolean, and string. React Navigation doesn't have the same restrictions, so users can sometimes pass invalid parameters like Functions, Objects, Maps, and so on.

如果你的代码有类似下面的内容：

¥If your code has something similar to the below:

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

const navigation = useNavigation();

navigation.push('Followers', {
  onPress: profile => {
    navigation.push('User', { profile });
  },
});

考虑进行重组，以便可以从 "followers" 屏幕访问该功能。此时，你可以直接从 "followers" 屏幕访问路由并推送。

¥Consider restructuring so the function can be accessed from the "followers" screen. In this case, you can access the router and push directly from the "followers" screen.

提前加载 UI

¥Eagerly load UI

在 React Native 应用中，在加载资源和字体时从根组件到 return null 是很常见的。这是不好的做法，并且在 Expo Router 中通常不支持。如果你绝对必须推迟渲染，请确保你不要尝试导航到任何屏幕。

¥It's common in React Native apps to return null from the root component while assets and fonts are loading. This is bad practice and generally unsupported in Expo Router. If you absolutely must defer rendering, then ensure you don't attempt to navigate to any screens.

从历史上看，这种模式是存在的，因为如果你使用尚未加载的自定义字体，React Native 会抛出错误。我们在 React Native 0.72 (SDK 49) 中对此上游进行了更改，因此默认行为是在加载自定义字体时交换默认字体。如果你想在字体加载完成之前隐藏各个文本元素，请编写一个封装器 <Text>，它在字体加载之前返回 null。

¥Historically this pattern exists because React Native will throw errors if you use custom fonts that haven't loaded yet. We changed this upstream in React Native 0.72 (SDK 49) so the default behavior is to swap the default font when the custom font loads. If you'd like to hide individual text elements until a font has finished loading, write a wrapper <Text>, which returns null until the font has loaded.

在网络上，从根返回 null 将导致 静态渲染 跳过所有子级，从而导致无法搜索内容。这可以通过在 Chrome 中使用 "查看页面源代码" 或禁用 JavaScript 并重新加载页面来测试。

¥On web, returning null from the root will cause static rendering to skip all of the children, resulting in no searchable content. This can be tested by using "View Page Source" in Chrome, or by disabling JavaScript and reloading the page.

迁移

¥Migration

删除未使用或托管的代码

¥Delete unused or managed code

Expo Router 自动添加 react-native-safe-area-context 支持。

¥Expo Router automatically adds react-native-safe-area-context support.

- import { SafeAreaProvider } from "react-native-safe-area-context";

export default function App() {
  return (
-    <SafeAreaProvider>
      <MyApp />
-    </SafeAreaProvider>
  )
}

Expo Router 不添加 react-native-gesture-handler（从 v3 开始），因此如果你使用手势处理程序或 <Drawer /> 布局，则必须自己添加它。避免在 Web 上使用此包，因为它添加了大量经常不使用的 JavaScript。

¥Expo Router does not add react-native-gesture-handler (as of v3), so you'll have to add this yourself if you are using Gesture Handler or <Drawer /> layout. Avoid using this package on web since it adds a lot of JavaScript that is often unused.

将屏幕复制到应用目录

¥Copy screens to the app directory

在存储库的根目录或根 src 目录中创建一个应用目录。

¥Create an app directory at the root of your repo, or in a root src directory.

通过根据 创建页面指南 文件创建文件来布局应用的结构。短横线和小写字母被认为是路由文件名的最佳实践。

¥Layout the structure of your app by creating files according to the creating pages guide. Kebab-case and lowercase letters are considered best practice for route filenames.

将导航器替换为目录，例如：

¥Replace navigators with directories, for example:

function HomeTabs() {
  return (
    <Tab.Navigator>
      <Tab.Screen name="Home" component={Home} />
      <Tab.Screen name="Feed" component={Feed} />
    </Tab.Navigator>
  );
}

function App() {
  return (
    // NavigationContainer is managed by Expo Router.
    <NavigationContainer
      linking={
        {
          // ...linking configuration
        }
      }
    >
      <Stack.Navigator>
        <Stack.Screen name="Settings" component={Settings} />
        <Stack.Screen name="Profile" component={Profile} />
        <Stack.Screen
          name="Home"
          component={HomeTabs}
          options={{
            title: 'Home Screen',
          }}
        />
      </Stack.Navigator>
    </NavigationContainer>
  );
}

Expo 路由：

¥Expo Router:

• 将 "main" 路由从 Home 重命名为 index，以确保它与 / 路径匹配。

  ¥Rename the "main" route from Home to index to ensure it matches the / path.

• 将名称转换为小写。

  ¥Convert names to lowercase.

• 将所有屏幕移动到应用目录内的适当文件位置。这可能需要一些实验。

  ¥Move all the screens to the appropriate file locations inside the app directory. This may take some experimenting.

import { Stack } from 'expo-router';

export default function RootLayout() {
  return (
    <Stack>
      <Stack.Screen
        name="(home)"
        options={
          {
            title: 'Home Screen',
          }
        }
      />
    </Stack>
  );
}

选项卡导航器将移动到子目录。

¥The tab navigator will be moved to a subdirectory.

import { Tabs } from 'expo-router';

export default function HomeLayout() {
  return <Tabs />;
}

使用 Expo Router 钩子

¥Use Expo Router hooks

React Navigation v6 及更低版本会将 props { navigation, route } 传递到每个屏幕。这种模式将在 React Navigation 中消失，我们从未将其引入到 Expo Router 中。

¥React Navigation v6 and lower will pass the props { navigation, route } to every screen. This pattern is going away in React Navigation, and we never introduced it to the Expo Router.

相反，将 navigation 迁移到 useRouter 钩子。

¥Instead, migrate navigation to the useRouter hook.

+ import { useRouter } from 'expo-router';

export default function Page({
-  navigation
}) {
-  navigation.push('User', { user: 'bacon' });

+  const router = useRouter();
+  router.push('/users/bacon');
}

同样，从 route prop 迁移到 useLocalSearchParams hook。

¥Similarly, migrate from the route prop to the useLocalSearchParams hook.

+ import { useLocalSearchParams } from 'expo-router';

export default function Page({
-  route
}) {
-  const user = route?.params?.user;

+  const { user } = useLocalSearchParams();
}

要访问 navigation.navigate，请从 useNavigation 钩子导入 navigation 属性。

¥To access the navigation.navigate, import the navigation prop from useNavigation hook.

+ import { useNavigation } from 'expo-router';

export default function Page({
+  const navigation = useNavigation();

  return (
    <Button onPress={navigation.navigate('screenName')}>
  )
})

迁移链接组件

¥Migrate the Link component

React Navigation 和 Expo Router 都提供 Link 组件。然而，Expo 的 Link 组件使用 href 而不是 to。

¥React Navigation and Expo Router both provide Link components. However, Expo's Link component uses href instead of to.

// React Navigation
<Link to="Settings" />

// Expo Router
<Link href="/settings" />

React Navigation 用户通常会使用 useLinkProps 钩子创建自定义 Link 组件来控制子组件。这在 Expo Router 中不是必需的，而是使用 asChild 属性。

¥React Navigation users will often create a custom Link component with the useLinkProps hook to control the child component. This isn't necessary in Expo Router, instead, use the asChild prop.

跨导航器共享屏幕

¥Share screens across navigators

React Navigation 应用在多个导航器之间重用一组路由是很常见的。这通常与选项卡一起使用，以确保每个选项卡可以推送任何屏幕。

¥It's common for React Navigation apps to reuse a set of routes across multiple navigators. This is generally used with tabs to ensure each tab can push any screen.

在 Expo Router 中，你可以迁移到 共享路由 或创建多个文件并从中重新导出相同的组件。

¥In Expo Router, you can either migrate to shared routes or create multiple files and re-export the same component from them.

当你使用组或共享路由时，你可以使用完全限定的路由名称（例如 /(home)/settings 而不是 /settings）导航到特定选项卡。

¥When you use groups or shared routes, you can navigate to specific tabs by using the fully qualified route name, for example, /(home)/settings instead of /settings.

迁移屏幕跟踪事件

¥Migrate screen tracking events

你可能根据我们的 React Navigation 屏幕跟踪指南 进行了屏幕跟踪设置，根据 Expo Router 屏幕跟踪指南 进行更新。

¥You may have your screen tracking setup according to our React Navigation screen tracking guide, update it according to the Expo Router screen tracking guide.

使用特定于平台的屏幕组件

¥Use platform-specific components for screens

有关根据平台切换 UI 的信息，请参阅 特定于平台的模块 指南。

¥Refer to the platform-specific modules guide for info on switching UI based on the platform.

更换 NavigationContainer

¥Replace the NavigationContainer

全局 React Navigation <NavigationContainer /> 完全在 Expo Router 中管理。Expo Router 提供的系统可以实现与 NavigationContainer 相同的功能，而无需直接使用它。

¥The global React Navigation <NavigationContainer /> is completely managed in Expo Router. Expo Router provides systems for achieving the same functionality as the NavigationContainer without needing to use it directly.

import { useRouter } from 'expo-router';

function Example() {
  const router = useRouter();

  return (
    <Text
      onPress={() => {
        // Go to the initial route of the application.
        router.replace('/');
      }}>
      Reset App
    </Text>
  );
}

import { ThemeProvider, DarkTheme, DefaultTheme, useTheme } from '@react-navigation/native';
import { Slot } from 'expo-router';

export default function RootLayout() {
  return (
    <ThemeProvider value={DarkTheme}>
      <Slot />
    </ThemeProvider>
  );
}

重写自定义导航器

¥Rewrite custom navigators

如果你的项目有自定义导航器，你可以重写它或将其移植到 Expo Router。

¥If your project has a custom navigator, you can rewrite this or port it to Expo Router.

要进行移植，只需使用 withLayoutContext 函数：

¥To port, simply use the withLayoutContext function:

import { createCustomNavigator } from './my-navigator';

export const CustomNavigator = withLayoutContext(createCustomNavigator().Navigator);

要重写，请使用 Navigator 组件，它封装了 React Navigation 中的 useNavigationBuilder 钩子。

¥To rewrite, use the Navigator component, which wraps the useNavigationBuilder hook from React Navigation.

可以使用 <Navigator /> 组件内部的 Navigator.useContext() 钩子访问 useNavigationBuilder 的返回值。可以使用 <Navigator /> 组件的 props 将属性传递给 useNavigationBuilder，这包括 initialRouteName、screenOptions、router。

¥The return value of useNavigationBuilder can be accessed with the Navigator.useContext() hook from inside the <Navigator /> component. Properties can be passed to useNavigationBuilder using the props of the <Navigator /> component, this includes initialRouteName, screenOptions, router.

<Navigator /> 组件的所有 children 将按原样渲染。

¥All of the children of a <Navigator /> component will be rendered as-is.

• Navigator.useContext：访问自定义导航器的 React Navigation state、navigation、descriptors 和 router。

  ¥Navigator.useContext: Access the React Navigation state, navigation, descriptors, and router for the custom navigator.

• Navigator.Slot：用于渲染当前选定路由的 React 组件。该组件只能在 <Navigator /> 组件内渲染。

  ¥Navigator.Slot: A React component used to render the currently selected route. This component can only be rendered inside a <Navigator /> component.

示例

¥Example

自定义布局具有内部上下文，当使用 <Slot /> 组件而没有 <Navigator /> 组件封装它时，该内部上下文将被忽略。

¥Custom layouts have an internal context that is ignored when using the <Slot /> component without a <Navigator /> component wrapping it.

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

import { Navigator, usePathname, Slot, Link } from 'expo-router';

export default function App() {
  return (
    <Navigator router={TabRouter}>
      <Header />
      <Slot />
    </Navigator>
  );
}

function Header() {;
  const pathname = usePathname();

  return (
    <View>
      <Link href="/">Home</Link>
      <Link
        href="/profile"
        style=

{[pathname === '/profile' && { color: 'blue' }]}

>
        Profile
      </Link>
      <Link href="/settings">Settings</Link>
    </View>
  );
}

使用 Expo Router 的闪屏封装器

¥Use Expo Router's Splash Screen wrapper

Expo Router 封装了 expo-splash-screen 并添加了特殊处理，以确保它在导航安装后以及捕获意外错误时隐藏。只需从导入 expo-splash-screen 迁移到从 expo-router 导入 SplashScreen。

¥Expo Router wraps expo-splash-screen and adds special handling to ensure it's hidden after the navigation mounts, and whenever an unexpected error is caught. Simply migrate from importing expo-splash-screen to importing SplashScreen from expo-router.

导航状态观察

¥Navigation state observation

如果你直接观察导航状态，请迁移到 usePathname、useSegments 和 useGlobalSearchParams 钩子。

¥If you're observing the navigation state directly, migrate to the usePathname, useSegments, and useGlobalSearchParams hooks.

将参数传递给嵌套屏幕

¥Pass params to nested screens

不要使用 嵌套屏幕导航事件，而是使用合格的 href：

¥Instead of using the nested screen navigation events, use a qualified href:

// React Navigation
navigation.navigate('Account', {
  screen: 'Settings',
  params: { user: 'jane' },
});

// Expo Router
router.push({ pathname: '/account/settings', params: { user: 'jane' } });

设置深度链接和服务器导航的初始路由

¥Set initial routes for deep linking and server navigation

在 React Navigation 中，你可以使用链接配置的 initialRouteName 属性。在 Expo Router 中，使用 布局设置。

¥In React Navigation, you can use the initialRouteName property of the linking configuration. In Expo Router, use layout settings.

重置导航状态

¥Reset navigation state

你可以使用 React Navigation 库中的 reset 操作来重置导航状态。它是使用 Expo Router 的 useNavigation 钩子来访问 navigation 属性的。

¥You can use the reset action from the React Navigation library to reset the navigation state. It is dispatched using the useNavigation hook from Expo Router to access the navigation prop.

在下面的示例中，可以从 useNavigation 钩子访问 navigation 属性，从 @react-navigation/native 访问 CommonActions.reset 操作。reset 操作中指定的对象将现有的导航状态替换为新的导航状态。

¥In the below example, the navigation prop is accessible from the useNavigation hook and the CommonActions.reset action from @react-navigation/native. The object specified in the reset action replaces the existing navigation state with the new one.

import { useNavigation } from 'expo-router'
import { CommonActions } from '@react-navigation/native'

export default function Screen() {
  const navigation = useNavigation();

  const handleResetAction = () => {
    navigation.dispatch(CommonActions.reset({
      routes: [{key: "(tabs)", name: "(tabs)"}]
    }))
  }

  return (
    <>
      

{/* ...rest of the code */}


      <Button title='Reset' onPress={handleResetAction} />
    </>
  );
}

迁移 TypeScript 类型

¥Migrate TypeScript types

Expo Router 可以自动生成 静态类型路由，这将确保你只能导航到有效的路由。

¥Expo Router can automatically generate statically typed routes, this will ensure you can only navigate to valid routes.

附加信息

¥Additional information

React 导航主题

¥React Navigation themes

React Navigation 导航器 <Stack>、<Drawer> 和 <Tabs> 使用共享外观提供程序。在 React Navigation 中，你可以使用 <NavigationContainer /> 组件设置整个应用的主题。Expo Router 管理根容器，以便你可以直接使用 ThemeProvider 设置主题。

¥React Navigation navigators <Stack>, <Drawer>, and <Tabs> use a shared appearance provider. In React Navigation, you set the theme for the entire app using the <NavigationContainer /> component. Expo Router manages the root container so that you can set the theme using the ThemeProvider directly.

import { ThemeProvider, DarkTheme, DefaultTheme, useTheme } from '@react-navigation/native';
import { Slot } from 'expo-router';

export default function RootLayout() {
  return (
    <ThemeProvider value={DarkTheme}>
      <Slot />
    </ThemeProvider>
  );
}

你可以在应用的任何层使用此技术来设置特定布局的主题。可以通过 @react-navigation/native 中的 useTheme 钩子访问当前主题。

¥You can use this technique at any layer of the app to set the theme for a specific layout. The current theme can be accessed via useTheme hook from @react-navigation/native.

React 导航元素

¥React Navigation Elements

@react-navigation/elements 库提供了一组可用于构建导航 UI 的 UI 元素和辅助程序。这些组件被设计为可组合和可定制的。你可以重用库中的默认功能或在其之上构建导航器的 UI。

¥The @react-navigation/elements library provides a set of UI elements and helpers that can be used to build a navigation UI. These components are designed to be composable and customizable. You can reuse the default functionality from the library or build your navigator's UI on top of it.

要将其与 Expo Router 一起使用，你需要安装该库：

¥To use it with Expo Router, you need to install the library:

要了解有关该库提供的组件和实用程序的更多信息，请参阅 元素库 文档。

¥To learn more about the components and utilities the library provides, see Elements library documentation.