跳至主要內容
版本：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 或更低版本，請勿在 4 版中使用 react-native-safe-area-context，僅到 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`套件時，您需要處理這些變更。

如需安裝`@react-navigation/native`的 6.x 版本，請執行

npm install @react-navigation/native

參數現在會在導覽時覆寫，而不是合併​

這可能是最大的變更之一。導覽到現有畫面時，我們已將新參數與現有參數合併，這是 React Navigation 最早的版本開始。

例如，假設現有的`發布`畫面含有下列參數

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

您使用`navigation.navigate('發布', { postTitle: '一個不錯的發布' })`導覽至該畫面，則會有以下參數

{
  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 有一個針對連結的略微不同的設定格式。舊設定允許在物件中的 key 值對，而不管導航器的巢狀結構。

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 文件以取得更多詳細資訊。

類似於 screenOptions 的導覽器的新 screenListeners 道具​

現在可以透過使用 screenListeners 道具針對導覽器中的所有畫面增加監聽器。這可能有助於監控所有畫面的 tabPress 等事項、導覽器層級的 state 變更等等。

請參閱 導覽事件 文件以取得更多詳細資訊。

用於建立容器參照的新鉤子和輔助函數​

新的 useNavigationContainerRef 鉤子和 createNavigationContainerRef 輔助函數可用於簡化將參照新增到 NavigationContainer。

請參閱 NavigationContainer 和 在沒有導覽道具的情況下導覽 文件以取得更多詳細資訊和範例。

在較早之前的版本中，useNavigation、Link、useLinkProps 等只能在螢幕內部使用。但現在可以它們使用在任何是 NavigationContainer 子項元的元件中。

backBehavior 的預設值現在是分頁和抽屜的 firstRoute​

按下返回鍵後回到第一個路由在應用程式中似乎更常見。為了符合這種行為，因此像是底部分頁、材質頂部分頁、材質底部分頁等分頁導覽列，以及抽屜導覽列現在會將 backBehavior 屬性設為 firstRoute。若要保留舊行為，可以將 backBehavior="history" 屬性傳遞給導覽列。

如果你有使用 TabRouter 或 DrawerRouter 自訂自有的導覽列，除非你指定 了 backbehavior，否則也會受到此變更的影響。

更嚴格的 TypeScript 類型​

現在類型定義更加嚴格，這可以透過將不安全類型降到最低來更容易及早發現錯誤。例如，如果你沒有指定類型，則 useNavigation 現在會顯示類型錯誤。

你可以透過 標註 來處理此問題，或有一個更簡單的方法，就是 指定根導覽列的類型，這類型將用於 useNavigation 的所有用法中。

使用 TypeScript 時，可以指定根導覽列的類型​

在早期版本中，我們需要在每次使用 useNavigation、Link 等功能時，為其指定類型。但現在可以在一個地方指定根導覽列的類型，預設情況下會在所有地方使用這個類型。

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

請參閱 TypeScript 文件，以取得更多詳情。

新的 CompositeScreenProps 類型，適用於 TypeScript​

現在有一個類似的 CompositeNavigationProps 的 CompositeScreenProps 輔助程式，可用於 TypeScript。請參閱 組合導覽屬性 以取得更多詳情。

堆疊導覽器​

下列變更內容在套件中@react-navigation/stack。

若要安裝 6.x 的版本 @react-navigation/stack，執行下列指令

npm install @react-navigation/stack

keyboardHandlingEnabled 移至選項​

先前，keyboardHandlingEnabled 是導覽器的道具，但現在需要在螢幕的選項中指定。若要保留之前的行為，您可以在 screenOptions 中指定它

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

為了 presentation: 'modal' 移除了 mode="modal"​

現在有個新選項 presentation 可讓您自訂螢幕是模態對話方塊或不是，且以每個螢幕為依據。

此外，為了符合 iOS 的預設行為，現在 presentation: 'modal' 會顯示 iOS 13 中推出的新簡報模式。它還會自動調整標題列中的狀態列高度等事項，而這些原本需要您手動調整。此外，在螢幕動態更新時會自動管理狀態列內容的顏色。

先前，Android 對模態對話方塊沒有任何特殊動態效果。但現在有一項從底部滑入的動態效果 (取代預設動態效果)。

如果您不想使用新的動態效果，可以使用 與動態效果相關的選項，依您的喜好進行變更。若要使用 React Navigation 5 的 iOS 模態對話方塊動態效果，請使用 TransitionPresets.ModalSlideFromBottomIOS。

此外，還有個新選項 presentation: 'transparentModal' 讓您能更輕鬆地建立透明模態對話方塊。查看 透明模態對話方塊文件，以瞭解更多詳細資訊。

更佳地支援在單堆疊中混合不同類型動態效果​

先前，為了某些動態效果，有時需要嵌套 2 個不同的堆疊導覽器，例如：當我們想要使用模態簡報模式和一般模式時。

現在可以在相同的堆疊中混合一般螢幕和模態螢幕，因為這些選項不再需要套用在整個螢幕上。

為了 headerShown: false 移除了 headerMode="none"​

先前，您可以傳遞 headerMode="none" 屬性讓堆疊導航器中的標題隱藏起來。不過，也有一個 headerShown 選項，可以用來隱藏或顯示標題，且支援依據每個畫面進行設定。

因此，我們移除了 headerMode="none"，並改用 headerShown: false，這樣就不必有 2 種方法來做非常類似的事情。若要取得先前行為，請在 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 上的彈出視窗中更高​

標題在彈出視窗中現在高 56 dp，以符合原生 iOS 風格。如果您正使用 useHeaderHeight 鉤子取得標題高度，則無需變更任何程式碼。

隱藏標題中的標題高度現在會被忽略​

先前，如果標題在堆疊導航器中已隱藏，則 useHeaderHeight 鉤子會傳回 0。現在改為會傳回最接近的已顯示標題高度。

自訂標題現在預設使用「headerMode: screen」​

先前在使用自訂標題時，必須手動指定 `headerMode='screen'` 或自訂動畫。即使文件中有提及，還是讓許多人感到困擾。

但是，現在指定自訂標題會自動將 headerMode 設為 screen，因此不需要再多做任何事情。這現在之所以可行，是因為 headerMode 不再是導航器的屬性，因此可以在指定自訂標題的每個畫面進行設定。

傳遞給自訂標題的屬性已精簡​

先前，堆疊標題接受場景和先前場景，其中包含 descriptor、navigation 屬性、progress 等。相關屬性現已簡化為以下內容。請參閱 標題文件 以取得清單。

如果你有自訂標題，你可能需要調整它來使用新的道具。

標題現在使用 flexbox​

標題元素使用絕對定位來描繪，這在某些情況下運作不佳。我們現在針對標題元素使用 flexbox，運作應該會更好。

這可能什麼都不會改變，但是如果你有依賴絕對定位的程式碼，你可能需要修改它。

gestureResponseDistance 選項現在是數字而非物件​

先前的 gestureResponseDistance 選項採用一個包含 horizontal 和 vertical 屬性的物件。它現在採用一個會根據 gestureDirection 選項用作水平或垂直值的數字。

現在支援 iPad 軌跡板上的兩指返回手勢​

在 iPad 上，可以使用兩根手指在原生 app 中執行返回手勢。這現在在堆疊導覽器中也可以用了。

修復當 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 表示畫面是開啟還是關閉中。

原生堆疊現在可在網路中使用​

先前，native-stack 僅能在 Android 和 iOS 上使用。但我們也加入基本的網路支援，讓您可以在不變更程式碼的情況下撰寫跨平台應用程式。

底部標籤導覽列​

使用 @react-navigation/bottom-tabs 套件時，會產生以下變更。

要安裝 @react-navigation/bottom-tabs 的 6.x 版本，請執行

npm install @react-navigation/bottom-tabs

標籤畫面中預設會顯示標頭​

現在標籤畫面會預設顯示類似於堆疊導覽列畫面中的標頭。如此一來，就不需要在每個畫面中嵌套一堆導覽列來顯示標頭。請參閱 其選項 以查看所有標頭相關選項。

如要維持之前的行為，您可以在 screenOptions 中使用 headerShown: false。

現在標籤列會在沒有傳入圖示時顯示問號，而不是留空​

先前的底部標籤列在沒有指定圖示時會留空。現在會顯示問號，讓使用者更清楚圖示遺失了。

為了採用更彈性的底部標籤 options，現已移除 tabBarOptions 屬性​

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 道具已移至 bottom 標籤的 lazy 選項，以進行各畫面的設定​

lazy 道具現在可以針對每個畫面設定，而不再針對整個導航。因此已從道具移至 options。為維持舊有行為，您可以在 screenOptions 中指定，以套用至所有畫面。

新的 tabBarBackground 選項可用於指定自訂背景​

新的 tabBarBackground 選項可用於為標籤列新增自訂背景，例如圖片、漸層、模糊檢視等，而無需手動包覆 TabBar。

請參閱 tabBarBackground 的文件，以取得更多詳細資訊。

Material Top 標籤導航​

以下變更位於 @react-navigation/material-top-tabs 套件中。

若要安裝 @react-navigation/material-top-tabs 的 6.x 版本，請執行

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 標籤現在使用 `ViewPager` 而非 Reanimated 與 Gesture Handler​

react-native-tab-view 相依套件已升級至最新版本 (3.x)，現在改用 react-native-pager-view 而非 Reanimated 與 Gesture Handler。這將提供原生 UX，並提升效能。

請參閱 react-native-tab-view 的發布備註，以取得更多詳細資訊。

已刪除 tabBarOptions 道具，並改用更靈活的 options 選項，以供 Material Top 標籤使用​

與 bottom 標籤相似，已刪除 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 選項供 Material 頂端分頁的每個畫面設定​

與底端分頁類似，lazy 屬性現在已移至 options 供 Material 頂端分頁使用。

lazyPlaceholder 這個屬性已移至 lazyPlaceholder 選項供 Material 頂端分頁的每個畫面設定​

lazyPlaceholder 屬性現在已移至 options 供 Material 頂端分頁使用，因此您可以設定每個畫面的選項中的 placeholder。

Material 下端分頁導航元件​

下列變更內容包含於 @react-navigation/material-bottom-tabs 套件中。

若要安裝 6.x 版的 @react-navigation/material-bottom-tabs，請執行

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 套件中。

若要安裝 6.x 版的 @react-navigation/drawer，請執行

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 的文件，以瞭解更多有關如何安裝和設定的詳細資訊。