跳至主要内容
版本：6.x

从 5.x 升级

React Navigation 6 保持与 React Navigation 5 相同的 API，但有一些重大更改，使 API 更一致、更灵活且更易于理解。

本指南列出了升级时需要牢记的所有更改和新功能。

最低要求​

React Navigation 6 需要以下库的更新版本

  • react-native-safe-area-context >= 3.0.0
  • react-native-screens >= 2.15.0
  • react-native-tab-view >= 3.0.0
  • react-native >= 0.63.0
  • expo >= 41 (如果您使用 Expo)
  • typescript >= 4.1.0 (如果您使用 TypeScript)

要将 react-native-safe-area-context 和 react-native-screens 升级到最新支持的版本，请执行以下操作

警告

如果您的 react-native 版本为 0.63.4 或更低，请不要使用 react-native-safe-area-context 的 4.x 版本，而应使用 3.4.1 或更低版本。 更多信息请点击这里

对于 Expo 管理的项目

npx expo install react-native-safe-area-context react-native-screens

对于裸 React Native 项目

npm install react-native-safe-area-context react-native-screens

请注意，react-native-screens 的最新版本现在默认启用。因此，如果您出于某些原因无法启用它，则需要手动禁用它。

重大更改和弃用表​

升级指南包括所有软件包的新功能以及重大更改。下表是为了方便您快速找到所有重大更改和弃用的列表。

重大更改​

如果您使用相关 API，以下重大更改可能会破坏您的应用程序。因此，您可能需要在升级时更改代码。

弃用​

如果您使用相关 API，以下更改将显示弃用警告，但您的代码将继续工作，并可能在稍后更新。

关于混合使用 React Navigation 5 和 React Navigation 6 包的说明​

为了简化升级过程，可以混合使用 6.x.x 和 5.x.x 版本范围内的包。但是，您需要牢记以下几点

  • 如果您使用的是 @react-navigation/[email protected] 和 6.x.x 版本的导航器

    • 您需要安装最新版本的 5.x.x 版本的 @react-navigation/native 包，其中包含一些回溯的 API。
    • 您无需担心“常规更改”部分中的任何重大更改。这些更改仅在您升级 @react-navigation/native 包时适用。

  • 如果您使用的是 @react-navigation/[email protected] 和 5.x.x 版本的任何导航器

    • 请务必注意“常规更改”部分中的重大更改。其他所有内容都应按预期工作。

在这两种情况下，如果您使用 TypeScript，在混合使用 5.x.x 和 6.x.x 时，可能会遇到类型错误，因为类型发生了变化。我们建议您忽略这些错误，直到您可以升级您的包。

常规更改​

以下更改位于核心库中。升级 @react-navigation/native 包时，您需要解决这些更改。

要安装 6.x 版本的 @react-navigation/native，请运行

npm install @react-navigation/native

导航时参数现在被覆盖而不是合并​

这可能是最大的变化之一。在导航到现有屏幕时，自 React Navigation 的第一个版本以来，我们一直将新参数与现有参数合并。

例如，假设有一个名为 Post 的现有屏幕，其参数如下

{
  postTitle: 'An amazing post',
  postBody: 'Amazing content for amazing post'
}

然后，您使用 navigation.navigate('Post', { postTitle: 'An okay post' }) 导航到它，它将具有以下参数

{
  postTitle: 'An okay post',
  postBody: 'Amazing content for amazing post'
}

虽然这种合并行为在某些情况下可能有用，但在其他情况下可能会出现问题。我们也收到了很多用户关于这种行为感到困惑的错误报告。

因此，我们正在更改 React Navigation 6 中的默认行为，以便参数不再默认合并，并且新参数会覆盖所有现有参数。

虽然默认值已更改，但如果您需要，仍然可以合并参数。要获得之前的行为，您可以将一个对象传递给 `navigate`，其中 `merge: true`，它将合并参数。

navigation.navigate({
  name: 'Post',
  params: { postTitle: 'An okay post' },
  merge: true,
});

您应该使用 `merge: true` 的一个常见场景是，如果您有一个自定义选项卡栏，因为当您通过点击选项卡栏更改选项卡时，不希望参数被覆盖。

从 `dangerouslyGetParent` 和 `dangerouslyGetState` 中删除了 `dangerously`​

`navigation` 属性上的 `dangerouslyGetParent` 和 `dangerouslyGetState` 方法在许多情况下很有用，有时甚至必不可少。因此，我们删除了 `dangerously` 前缀，以明确表明它可以安全使用。现在您可以使用 navigation.getParent 和 navigation.getState()。

`route` 属性上不再有 `state` 属性​

传递给组件的 `route` 属性通常包含一个 `state` 属性，该属性保存子导航器的状态。虽然它不打算公开，并且我们在文档中建议不要使用它，但我们看到很多人使用了这个属性。

使用该属性存在问题，因为它不能保证在子导航器中进行导航之前存在。这会导致应用程序中出现细微的错误，您可能在开发过程中不会注意到。因此，我们从 React Navigation 5 开始警告使用此属性，并在 React Navigation 6 中完全删除了此属性，以防止其使用。

如果您需要根据子导航器中哪个屏幕处于焦点来进行一些配置，您仍然可以使用 getFocusedRouteNameFromRoute 实用程序。

`route` 属性上新增了 `path` 属性​

当从深层链接打开时，`route` 属性现在将包含一个 `path` 属性。您可以使用此属性进一步自定义屏幕的内容，例如在 `WebView` 中加载页面。有关更多详细信息，请参阅 处理未匹配的路由或 404。

链接配置现在更加严格​

React Navigation 5 的旧版本对链接有略微不同的配置格式。旧的配置允许对象中存在键值对，无论导航器嵌套如何。

const config = {
  Home: 'home',
  Feed: 'feed',
  Profile: 'profile',
  Settings: 'settings',
};

假设你的 Feed 和 Profile 屏幕嵌套在 Home 中。即使你没有使用上述配置进行这样的嵌套，只要 URL 是 /home/profile，它就可以正常工作。此外，它还会将路径段和路由名称视为相同，这意味着你可以深度链接到配置中未指定的屏幕。例如，如果你在 Home 中有一个 Albums 屏幕，深度链接 /home/Albums 将导航到该屏幕。虽然这在某些情况下可能是可取的，但无法阻止访问特定屏幕。这种方法也使得拥有类似 404 屏幕的机制变得不可能，因为任何路由名称都是有效的路径。

React Navigation 5 的较新版本支持不同的配置格式，这方面更加严格。

  • 配置的形状必须与导航结构中的嵌套形状匹配。
  • 只有在配置中定义的屏幕才能进行深度链接。

因此，你需要将上述配置重构为以下格式。

const config = {
  screens: {
    Home: {
      path: 'home',
      screens: {
        Feed: 'feed',
        Profile: 'profile',
      },
    },
    Settings: 'settings',
  },
};

这里，配置对象中有一个新的 screens 属性，并且 Feed 和 Profile 配置现在嵌套在 Home 下，以匹配导航结构。

虽然旧格式在 React Navigation 5 中仍然有效，但 React Navigation 6 完全放弃了对旧格式的支持，转而支持新的更严格的格式。

删除了 useLinking 钩子​

useLinking 钩子是 React Navigation 5 中深度链接的初始实现。后来，我们迁移到 linking 属性，以简化深度链接的处理。该钩子仍然被导出，以避免破坏使用它的现有应用程序。

在 6.x 中，我们最终删除了该钩子，转而使用 linking 属性。如果你仍然使用 useLinking 钩子，迁移应该非常简单，你只需要将配置传递给 linking 属性即可。

有关配置深度链接的更多详细信息，请参阅 配置链接。

之前，Link 组件只能接受路径字符串。现在你可以传递一个对象，该对象指定要导航到的屏幕名称以及要传递的任何参数。

<Link
  to={{
    screen: 'Profile',
    params: { id: 'jane' },
  }}
>
  Go to Jane's profile
</Link>

有关更多详细信息，请参阅 useLinkProps 文档。

新的 Group 组件​

新的 Group 组件可用于将类似的屏幕分组在一起。您可以使用它将一些通用选项传递给多个屏幕。

例如，您可以将其用于多个常规屏幕和多个模态屏幕，而无需创建 2 个导航器。

<Stack.Navigator>
  <Stack.Group
    screenOptions={{ headerStyle: { backgroundColor: 'papayawhip' } }}
  >
    <Stack.Screen name="Home" component={HomeScreen} />
    <Stack.Screen name="Profile" component={ProfileScreen} />
  </Stack.Group>
  <Stack.Group screenOptions={{ presentation: 'modal' }}>
    <Stack.Screen name="Search" component={SearchScreen} />
    <Stack.Screen name="Share" component={ShareScreen} />
  </Stack.Group>
</Stack.Navigator>

有关更多详细信息，请参阅 Group 文档。

导航器的新 screenListeners 属性，类似于 screenOptions​

现在可以使用 screenListeners 属性为导航器中的所有屏幕添加监听器。这对于监听诸如所有屏幕的 tabPress、导航器级别的 state 更改等内容很有用。

有关更多详细信息，请参阅 导航事件 文档。

用于创建容器 ref 的新钩子和助手​

新的 useNavigationContainerRef 钩子和 createNavigationContainerRef 助手可用于简化向 NavigationContainer 添加 ref 的操作。

有关更多详细信息和示例，请参阅 NavigationContainer 和 在没有 navigation 属性的情况下导航 文档。

之前，useNavigation、Link、useLinkProps 等只能在屏幕内部使用。但现在可以在 NavigationContainer 的任何子组件中使用它们。

backBehavior 的默认值为标签和抽屉的 firstRoute​

在应用程序中，按下后退按钮后返回到第一个路由似乎更为常见。为了匹配这种行为，标签导航器（如底部标签、Material 顶部标签、Material 底部标签等）以及抽屉导航器现在使用 firstRoute 作为 backBehavior 属性。为了保留旧的行为，您可以将 backBehavior="history" 属性传递给导航器。

如果您使用 TabRouter 或 DrawerRouter 创建了自己的自定义导航器，除非您指定了 backbehavior，否则它也会受到此更改的影响。

TypeScript 的更严格类型​

类型定义现在更加严格，这可以通过最小化不安全的类型来更容易地尽早捕获错误。例如，如果您没有指定类型，useNavigation 现在会显示类型错误。

您可以通过 对其进行注释 来处理此问题，或者更简单的方法是 为根导航器指定一个类型，该类型将用于所有 useNavigation 的使用。

使用 TypeScript 时能够为根导航器指定类型​

以前，我们需要为 useNavigation、Link 等在每个使用它们的地方指定类型。但现在可以在一个地方指定根导航器的类型，该类型默认情况下将在所有地方使用。

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

有关更多详细信息，请参阅 TypeScript 文档。

TypeScript 的新 CompositeScreenProps 类型​

我们现在有一个类似于 CompositeNavigationProps 的 CompositeScreenProps 助手，用于与 TypeScript 一起使用。有关更多详细信息，请参阅 组合导航属性。

堆栈导航器​

以下更改位于 @react-navigation/stack 包中。

要安装 6.x 版本的 @react-navigation/stack，请运行

npm install @react-navigation/stack

keyboardHandlingEnabled 已移至选项​

以前，keyboardHandlingEnabled 是导航器上的一个属性，但现在需要在屏幕的 options 中指定它。为了保持以前的行为，您可以在 screenOptions 中指定它。

<Stack.Navigator screenOptions={{ keyboardHandlingEnabled: false }}>
  <Stack.Screen name="Home" component={Home} />
  <Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>

mode="modal" 已被 presentation: 'modal' 取代​

现在有一个新的 presentation 选项，允许您自定义屏幕是模态还是非模态，具体取决于每个屏幕。

此外，为了与 iOS 的默认行为保持一致，现在 presentation: 'modal' 会显示 iOS 13 中引入的新型模态呈现样式。它还会自动调整标题中的状态栏高度，以前您需要手动进行此操作。此外，当屏幕动画时，状态栏内容的颜色会自动管理。

以前，Android 并没有为模态提供任何特殊的动画。但现在有一个从底部滑入的动画，而不是默认动画。

如果您不想使用新的动画，可以使用 与动画相关的选项 更改为您的喜好。要使用 React Navigation 5 中的 iOS 模态动画，请使用 TransitionPresets.ModalSlideFromBottomIOS。

此外，一个新的 presentation: 'transparentModal' 选项，使构建透明模态变得更容易。有关更多详细信息，请参阅 透明模态 文档。

更好地支持在单个堆栈中混合不同类型的动画​

以前，有时需要嵌套 2 个不同的堆栈导航器才能实现某些动画，例如：当我们想要使用模态呈现样式和常规样式时。

现在可以在同一个堆栈中混合常规屏幕和模态屏幕，因为这些选项不再需要应用于整个屏幕。

headerMode="none" 已被 headerShown: false 取代​

以前，您可以传递 headerMode="none" 属性来隐藏堆栈导航器中的标题。但是，还有一个 headerShown 选项，可用于隐藏或显示标题，并且它支持按屏幕配置。

因此，我们不再使用 2 种方法来完成非常相似的事情，而是用 headerShown: false 取代了 headerMode="none"。要获得旧的行为，请在 screenOptions 中指定 headerShown: false

<Stack.Navigator screenOptions={{ headerShown: false }}>
  <Stack.Screen name="Home" component={Home} />
  <Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>

headerMode 已移至选项​

之前，headerMode 是导航器上的一个道具，但现在需要在屏幕的 options 中指定。为了保持之前的行为，您可以在 screenOptions 中指定它。

<Stack.Navigator screenOptions={{ headerMode: 'screen' }}>
  <Stack.Screen name="Home" component={Home} />
  <Stack.Screen name="Profile" component={Profile} />
</Stack.Navigator>

headerMode 选项支持 2 个值：screen 和 float。

iOS 上模态中的标题现在更高​

标题现在在模态中高 56dp，以匹配原生 iOS 样式。如果您正在使用 useHeaderHeight 钩子来获取标题的高度，那么您无需更改任何代码。

隐藏标题的标题高度现在被忽略​

之前，如果标题在堆栈导航器中隐藏，则 useHeaderHeight 钩子返回 0。现在它返回最近可见标题的高度。

自定义标题现在默认使用 'headerMode: screen'​

之前，在使用自定义标题时，需要手动指定 headerMode='screen' 或自定义动画。尽管文档中提到了这一点，但它还是让很多人感到困惑。

但现在指定自定义标题会自动将 headerMode 设置为 screen，因此不需要任何其他操作。现在可以做到这一点，因为 headerMode 不再是导航器的道具，因此可以在指定自定义标题的每个屏幕上进行配置。

传递给自定义标题的道具已简化​

之前，堆栈标题接受场景和上一个场景，其中包含 descriptor、navigation 道具、progress 等。道具现在已简化为以下内容。有关列表，请参阅 标题文档。

如果您有自定义标题，您可能需要调整它以使用新的道具。

标题现在使用 flexbox​

标题元素以前使用绝对定位渲染，这在某些情况下效果不佳。我们现在对标题元素使用 flexbox，这应该会更好。

这可能不会对您造成任何改变，但如果您有依赖于绝对定位的代码，您可能需要更改它。

gestureResponseDistance 选项现在是一个数字，而不是一个对象​

以前，gestureResponseDistance 选项接受一个包含 horizontal 和 vertical 属性的对象。现在它接受一个数字，该数字将根据 gestureDirection 选项用作水平或垂直值。

iPad 上触控板上的双指后退手势现在已受支持​

在 iPad 上，可以使用两根手指在原生应用中执行后退手势。现在在堆栈导航器中也可以使用它。

修复未启用 react-native-screens 时 Web 上的辅助功能​

以前，即使禁用 react-native-screens，未聚焦的屏幕在 Web 上仍然可以访问。现在不再是这种情况。请注意，这仅在未启用动画时有效（这是 Web 上的默认设置）。否则，如果您禁用了它，则需要启用 react-native-screens 才能使其正常工作。

一些导出现在已移至元素库​

以下导出现在位于元素库中，因为它们不再特定于堆栈导航器

  • 资产
  • HeaderTitle
  • HeaderBackButton
  • HeaderBackground
  • HeaderHeightContext
  • useHeaderHeight

有关安装元素库的更多详细信息，请参阅下方。

原生堆栈导航器​

@react-navigation/native-stack 包已回归。我们对 API 做了一些更改，以便在 @react-navigation/stack 和 @react-navigation/native-stack 之间更轻松地移动。如果您之前使用的是 react-native-screens/native-stack，那么您需要对代码进行一些更改。

要安装 6.x 版本的 @react-navigation/native-stack，请运行

npm install @react-navigation/native-stack

来自 react-native-screens/native-stack 的重大更改​

如果您是从 react-native-screens/native-stack 中导入 createNativeStackNavigator，那么在迁移到 @react-navigation/native-stack 包时，您需要牢记以下更改

原生堆栈的选项​

  • backButtonInCustomView 选项已删除，现在在必要时自动设置
  • headerCenter 选项已删除，headerLeft、headerRight 和 headerTitle 选项现在的工作方式与堆栈导航器 中一样
  • headerHideBackButton 已更改为 headerBackVisible
  • headerHideShadow 已更改为 headerShadowVisible
  • headerLargeTitleHideShadow 已更改为 headerLargeTitleShadowVisible
  • headerTranslucent 已更改为 headerTransparent
  • headerBlurEffect 现在是一个单独的选项，不再是 headerStyle 中的属性
  • headerTopInsetEnabled 选项已删除，现在在必要时自动设置
  • disableBackButtonMenu 已更改为 headerBackButtonMenuEnabled
  • backButtonImage 已重命名为 headerBackImageSource
  • searchBar 已重命名为 headerSearchBarOptions
  • replaceAnimation 已重命名为 animationTypeForReplace
  • stackAnimation 已重命名为 animation
  • stackPresentation 已重命名为 presentation - push 值现在称为 card
  • direction 选项已移除，现在会根据 I18nManager.isRTL 自动设置

事件​

appear 和 disappear 事件已被移除，取而代之的是 transitionStart 和 transitionEnd 事件，其中 e.data.closing 指示屏幕是正在打开还是关闭。

原生堆栈现在可以在 Web 上使用​

以前，native-stack 只能在 Android 和 iOS 上使用。但我们也添加了基本的 Web 支持，这样你就可以编写跨平台应用程序，而无需更改代码。

底部标签导航器​

以下更改位于 @react-navigation/bottom-tabs 包中。

要安装 6.x 版本的 @react-navigation/bottom-tabs，请运行

npm install @react-navigation/bottom-tabs

标签屏幕默认显示标题​

标签屏幕现在默认显示标题，类似于堆栈导航器中的屏幕。这避免了在每个屏幕中嵌套堆栈导航器只是为了获得标题的需要。请参阅 其选项 以查看所有与标题相关的选项。

要保留之前的行为，你可以在 screenOptions 中使用 headerShown: false。

标签栏现在在没有传递图标时显示问号，而不是空白区域​

以前，底部标签中的标签栏在没有指定图标时会显示空白区域。现在它显示一个问号，以更明显地表明图标丢失了。

tabBarOptions 属性已被移除，取而代之的是更灵活的底部标签 options​

tabBarOptions 属性已被移除，其中的选项已移至屏幕的 options 中。这使得它们可以在每个屏幕的基础上进行配置。

以下是选项及其新名称的列表：

  • keyboardHidesTabBar -> tabBarHideOnKeyboard
  • activeTintColor -> tabBarActiveTintColor
  • inactiveTintColor -> tabBarInactiveTintColor
  • activeBackgroundColor -> tabBarActiveBackgroundColor
  • inactiveBackgroundColor -> tabBarInactiveBackgroundColor
  • allowFontScaling -> tabBarAllowFontScaling
  • showLabel -> tabBarShowLabel
  • labelPosition -> tabBarLabelPosition
  • labelStyle -> tabBarLabelStyle
  • iconStyle -> tabBarIconStyle
  • tabStyle -> tabBarItemStyle
  • style -> tabBarStyle

adaptive 选项已被移除，因为您现在可以通过指定 tabBarLabelPosition 来禁用自动标签定位。

旧选项仍然可以使用，但会发出弃用警告。要避免弃用警告，请将这些选项移至 screenOptions。

tabBarVisible 选项不再存在​

由于标签栏现在支持 tabBarStyle 选项，我们已移除 tabBarVisible 选项。您可以通过在 options 中指定 tabBarStyle: { display: 'none' } 来实现相同的效果。

lazy 属性已移至 lazy 选项，以便对底部标签进行每个屏幕的配置​

lazy 属性现在可以针对每个屏幕进行配置，而不是针对整个导航器。因此，它已从属性移至 options。要保持之前的行为，您可以在 screenOptions 中指定它，以将其应用于所有屏幕。

新的 tabBarBackground 选项用于指定自定义背景​

新的 tabBarBackground 选项可用于向选项卡栏添加自定义背景，例如图像、渐变、模糊视图等，而无需手动包装 TabBar。

有关更多详细信息，请参阅有关 tabBarBackground 的文档。

Material Top Tab Navigator​

以下更改位于 @react-navigation/material-top-tabs 包中。

要安装 6.x 版本的 @react-navigation/material-top-tabs，请运行

npm install @react-navigation/material-top-tabs react-native-tab-view

要将 react-native-pager-view 升级到最新支持的版本，请执行以下操作

对于 Expo 管理的项目

npx expo install react-native-pager-view

对于裸 React Native 项目

npm install react-native-pager-view

Material Top Tabs 现在使用 ViewPager 而不是 Reanimated 和 Gesture Handler​

react-native-tab-view 依赖项已升级到最新版本 (3.x)，现在使用 react-native-pager-view 而不是 Reanimated 和 Gesture Handler。这将提供原生 UX 并提高性能。

有关更多详细信息，请参阅 react-native-tab-view 的发行说明。

tabBarOptions 属性已删除，取而代之的是更灵活的 options，用于材料顶部选项卡​

与底部选项卡类似，tabBarOptions 属性已删除，其中的选项已移至屏幕的 options 中。

以下是选项及其新名称的列表：

  • activeTintColor -> tabBarActiveTintColor
  • inactiveTintColor -> tabBarInactiveTintColor
  • pressColor -> tabBarPressColor
  • pressOpacity -> tabBarPressOpacity
  • showLabel -> tabBarShowLabel
  • showIcon -> tabBarShowIcon
  • allowFontScaling -> tabBarAllowFontScaling
  • bounces -> tabBarBounces
  • scrollEnabled ->tabBarScrollEnabled
  • iconStyle -> tabBarIconStyle
  • labelStyle -> tabBarLabelStyle
  • tabStyle -> tabBarItemStyle
  • indicatorStyle -> tabBarIndicatorStyle
  • indicatorContainerStyle -> tabBarIndicatorContainerStyle
  • contentContainerStyle -> tabBarContentContainerStyle
  • style -> tabBarStyle

旧选项仍然可以使用，但会发出弃用警告。要避免弃用警告，请将这些选项移至 screenOptions。

lazy 属性已移至 lazy 选项，用于材料顶部选项卡的每个屏幕配置​

与底部选项卡类似，lazy 属性现在已移至材料顶部选项卡的 options 中。

lazyPlaceholder 属性已移至 lazyPlaceholder 选项，用于为 Material 顶部标签进行每屏配置​

lazyPlaceholder 属性现在已移至 Material 顶部标签的 options 中，因此您可以在每个屏幕的选项中配置占位符。

Material 底部标签导航器​

以下更改位于 @react-navigation/material-bottom-tabs 包中。

要安装 @react-navigation/material-bottom-tabs 的 6.x 版本，请运行

npm install @react-navigation/material-bottom-tabs

Material 底部标签现在使用 react-native-safe-area-context 来应用安全区域内边距​

现在，在使用 @react-navigation/material-bottom-tab 时，需要安装 react-native-safe-area-context 包，如果您之前没有安装。

抽屉导航器​

以下更改位于 @react-navigation/drawer 包中。

要安装 @react-navigation/drawer 的 6.x 版本，请运行

npm install @react-navigation/drawer

抽屉现在使用 Reanimated 2（如果可用）​

有一个基于最新 Reanimated 的新实现，如果可用，将使用它，否则抽屉将回退到旧实现。

如果您需要，可以将 useLegacyImplementation={true} 传递给 Drawer.Navigator 以强制它始终使用旧实现。

抽屉屏幕默认显示标题​

标签屏幕现在默认显示标题，类似于堆栈导航器和底部标签导航器中的屏幕。请参阅 其选项 以查看所有与标题相关的选项。

要保留之前的行为，你可以在 screenOptions 中使用 headerShown: false。

滑动动画现在是 iOS 上的默认动画​

抽屉现在在 iOS 上默认使用滑动动画。要保留之前的行为，您可以在 screenOptions 中指定 drawerType="front"。

抽屉状态现在是字符串而不是布尔值​

以前，抽屉的状态是一个 boolean（true | false）来表示打开和关闭状态。现在它是一个字符串，其值为 open 和 closed。这将使我们能够在将来实现更多类型的状态。

为了匹配此更改，以下 API 也已重命名

  • getIsDrawerOpenFromState -> getDrawerStatusFromState
  • useIsDrawerOpen -> useDrawerStatus
  • openByDefault -> defaultStatus

抽屉不再发出drawerOpen 和 drawerClose 事件​

drawerOpen 和 drawerClose 事件现已移除，因为相同的信息可以通过以下辅助函数获取

  • useDrawerStatus 钩子
  • getDrawerStatusFromState 辅助函数（例如 - getDrawerStatusFromState(navigation.getState())）

drawerContentOptions 属性现在更灵活，已移至抽屉的 options​

drawerContentOptions 属性已移除，其中的选项已移至屏幕的 options。 这使得它们可以在每个屏幕的基础上进行配置。

以下选项已移动，但未重命名

  • drawerPosition
  • drawerType
  • keyboardDismissMode
  • overlayColor
  • gestureHandlerProps

以下选项已移动并重命名

  • hideStatusBar -> drawerHideStatusBarOnOpen
  • statusBarAnimation -> drawerStatusBarAnimation
  • edgeWidth -> swipeEdgeWidth
  • minSwipeDistance -> swipeMinDistance

旧选项仍然可以使用，但会发出弃用警告。要避免弃用警告，请将这些选项移至 screenOptions。

drawerContent 属性不再在其参数中接收 progress​

传递给 drawerContent 的回调不再在其参数中接收动画 progress 值。 相反，您可以使用 useDrawerProgress 钩子来获取当前进度值。

function CustomDrawerContent(props) {
  const progress = useDrawerProgress();

  // ...
}

// ...

<Drawer.Navigator drawerContent={(props) => <CustomDrawerContent {...props} />}>

useDrawerProgress 钩子根据使用的实现返回一个 Reanimated Node 或 Reanimated SharedValue。

lazy 属性已移至 lazy 选项，用于在每个屏幕上配置抽屉​

与底部标签类似，lazy 属性现在已移至抽屉的 options。

元素库​

我们有一个新的包，其中包含与导航相关的各种 UI 元素，例如 Header 组件。这意味着我们现在可以在所有导航器中使用这些组件。您也可以安装该库以导入 Header 等组件，以便在任何导航器中使用。

npm install @react-navigation/elements

现在您可以从那里导入项目。

import { useHeaderHeight } from '@react-navigation/elements';

有关库中可用内容的更多详细信息，请参阅 元素库页面。

开发者工具​

有一个新的 React Navigation Flipper 插件，可以帮助您调试导航和深层链接配置。

有关如何安装和配置它的更多详细信息，请参阅 useFlipper 文档。