Navigation | Android Developers

API 參考資料
androidx.nav
androidx.nav.fragment
androidx.nav.ui

Navigation 是可在 Android 應用程式中瀏覽各個「目的地」的架構，無論目的地是以 Fragment、Activity 或其他元件實作，都能提供一致的 API，

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2023 年 2 月 8 日	2.5.3	-	-	2.6.0-alpha05

宣告依附元件

如要為 Navigation 新增依附元件，必須將 Google Maven 存放區新增至您的專案。詳情請參閱「Google 的 Maven 存放區」一節。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

Groovy

dependencies {
  def nav_version = "2.5.3"

  // Java language implementation
  implementation "androidx.navigation:navigation-fragment:$nav_version"
  implementation "androidx.navigation:navigation-ui:$nav_version"

  // Kotlin
  implementation "androidx.navigation:navigation-fragment-ktx:$nav_version"
  implementation "androidx.navigation:navigation-ui-ktx:$nav_version"

  // Feature module Support
  implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version"

  // Testing Navigation
  androidTestImplementation "androidx.navigation:navigation-testing:$nav_version"

  // Jetpack Compose Integration
  implementation "androidx.navigation:navigation-compose:$nav_version"
}

Kotlin

dependencies {
  val nav_version = "2.5.3"

  // Java language implementation
  implementation("androidx.navigation:navigation-fragment:$nav_version")
  implementation("androidx.navigation:navigation-ui:$nav_version")

  // Kotlin
  implementation("androidx.navigation:navigation-fragment-ktx:$nav_version")
  implementation("androidx.navigation:navigation-ui-ktx:$nav_version")

  // Feature module Support
  implementation("androidx.navigation:navigation-dynamic-features-fragment:$nav_version")

  // Testing Navigation
  androidTestImplementation("androidx.navigation:navigation-testing:$nav_version")

  // Jetpack Compose Integration
  implementation("androidx.navigation:navigation-compose:$nav_version")
}

Safe Args

如要在專案中新增 Safe Args，請在頂層 build.gradle 檔案中納入下列 classpath：

Groovy

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.5.3"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

Kotlin

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.5.3"
        classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version")
    }
}

您也必須從兩個可用的外掛程式之中選擇一項套用。

如要產生適合 Java 或混用 Java 及 Kotlin 模組的 Java 語言程式碼，請將以下這一行新增至應用程式或模組的 build.gradle 檔案：

Groovy

plugins {
  id 'androidx.navigation.safeargs'
}

Kotlin

plugins {
    id("androidx.navigation.safeargs")
}

或者，如要產生適合 Kotlin 模組的 Kotlin 程式碼，請加入：

Groovy

plugins {
  id 'androidx.navigation.safeargs.kotlin'
}

Kotlin

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

根據遷移至 AndroidX 一文，gradle.properties 檔案中必須含有 android.useAndroidX=true。

如要進一步瞭解如何使用 Kotlin 擴充功能，請參閱 ktx 說明文件。

如要進一步瞭解依附元件，請參閱「新增建構依附元件」。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或想建議改善這個程式庫，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有問題。

回報新問題

詳情請參閱 Issue Tracker 說明文件。

2.6.0 版

2.6.0-alpha05 版

2023 年 2 月 8 日

發布 androidx.navigation:navigation-*:2.6.0-alpha05。查看 2.6.0-alpha05 版的修訂項。

新功能

NavController.popBackStack(route)、NavController.getBackStackEntry(route)、NavController.clearBackStack(route) 現在都支援填入部分或完整引數的路徑。請注意，引數必須與該項目的引數完全相符 (Iebd28、Ic678c、I3b37b、b/257514373)。
在瀏覽和彈出 NavBackStackEntries 時，FragmentNavigator 現在會使用轉換 API。這表示 NavBackStackEntry Lifecycle 現在會等到進入和離開片段的特效完成後，再移至最終的 Lifecycle.State (I3cb19、b/238686802)。
在瀏覽和彈出 NavBackStackEntries 時，DialogFragmentNavigator 現在會使用轉換 API。這表示 NavBackStackEntry Lifecycle 現在會等到 DialogFragment Lifecycle 移至 DESTROYED 後，再移至 DESTROYED (I53ee5、b/261213893)。

API 變更

NavigatorState 現在提供 prepareForTransition API，可讓 Navigator 將 NavBackStackEntries 移至中繼 Lifecycle.State (I42c21、b/238686802)。
現在可以透過 backstack 屬性，存取與 NavGraphNavigator 或 ComposeNavigator 相關聯的返回堆疊。ComposeNavigator 現在也會揭露 onTransitionComplete() 回呼，將執行導覽或 popBackStack 作業的 NavBackStackEntry 標示為已完成 (I02062、I718db、b/257519195)。

修正錯誤

現在使用 push/popWithTransition API 且項目已開始處理時，導覽器狀態不需人工管理 (Iadbfa、b/261213893)。
將 launchSingleTop 與巢狀 NavGraph 搭配使用時，從原始目的地到其 startDestination 的所有目的地只會正確新增至返回堆疊頂端 (Id4bea、b/253256629)。
導覽到相同目的地並將 launchSingleTop 標記設為 true 時，Navigation 現在可以正確取代 DialogFragment 例項 (I45b5a、b/149572817)。
使用 19 個字元的引數時，Navigation SafeArgs 不會再造成編譯錯誤 (Id60bc、b/257110095)。

2.6.0-alpha04 版

2022 年 11 月 9 日

發布 androidx.navigation:navigation-*:2.6.0-alpha04。查看 2.6.0-alpha04 版的修訂項。

新功能

NavType 的自訂子類別現在可以覆寫 serializeAsValue，以便將值序列化為字串，讓序列化和反序列化程序 (透過 parseValue) 完全封裝在 NavType 類別中。StringType 現在會覆寫這個方法，進而在指定的 String 上呼叫 Uri.encode。(Ie5213、b/247637434)
現在如果 NavigationUI 未能透過選定的 MenuItem 進行導覽，則會提供記錄 (I2af5a、b/247730357)

修正錯誤

系統現在會延遲剖析 Navigation 深層連結，而不會在圖表初始化時進行剖析，這有助於改善應用程式啟動時的效能。(Iab0ab)
修正了透過深層連結前往含有空值預設引數的目的地後，向上導覽所引發的當機問題。(I51c24、b/243183636)。

依附元件更新

Navigation 支援的動態功能模組現在依附於細部化的 Play Feature Delivery 程式庫。(Ib4ddc)
Navigation Safe Args 現在依附於 Android Gradle 外掛程式 7.3.0 版本。這表示其現已與 7.3.0 以上版本相容。(I47e49)

2.6.0-alpha03 版本

2022 年 10 月 24 日

發布 androidx.navigation:navigation-*:2.6.0-alpha03。查看 2.6.0-alpha03 版的修訂項。

修正錯誤

自 Navigation 2.5.3 起：當 Crossfade 沒有可用於組合的目的地時，NavHost 不會再造成 NoSuchElementException，而只會略過組合作業。(Ieb46e、b/253299416)
自 Navigation 2.5.3 起：修正目的地從返回堆疊彈出時，系統未忘記及移除已儲存的 Compose 狀態 (例如使用 rememberSaveable 的情形) 的問題。(I64949)

依附元件更新

Navigation 現在依附於 Fragment 1.5.4。(Icd424)

2.6.0-alpha02 版本

2022 年 10 月 5 日

發布 androidx.navigation:navigation-*:2.6.0-alpha02。查看 2.6.0-alpha02 版的修訂項。

行為變更

將導覽圖的 ID 傳送至 AppBarConfiguration (例如透過 Menu) 時，NavigationUI 現在只會將該導覽圖的起始目的地視為頂層目的地，而不會錯誤地標記圖中每個目的地做為頂層目的地。傳遞個別目的地 ID 的行為則維持不變。您可以在 AppBarConfiguration 中透過新的 isTopLevelDestination 函式，將同樣的功能提供給自己的程式碼。(Ie936e、b/238496771)

修正錯誤

navigation:navigation-fragment 元件現在依附於 Fragment 版本 1.5.2。(I00ba4)
前往 FloatingWindow 目的地 (例如對話方塊) 時，不會再更新所選選單項目。(I4cde8、b/240308330)

2.6.0-alpha01 版本

2022 年 9 月 7 日

發布 androidx.navigation:navigation-*:2.6.0-alpha01。查看 2.6.0-alpha01 版的修訂項。

新功能

NavigationUI 中用於頂端應用程式列的 setupWithNavController 整合現在將 android:label 中找到的 ReferenceType 引數的 R.string 值剖析為其字串值，而不是輸出自動產生的資源整數 (I5f803、b/167959935)。
NavDeepLink 現在支援陣列的預設值，可讓您支援對應到引數的陣列類型的重複查詢參數。NavType 現在也包含預設方法，您可以覆寫該方法以合併兩個剖析值 (Id68c3、b/209977108)。
在導覽 XML 檔案的活動元素的 app:data 和 app:dataPattern 屬性中將字串 ${applicationId} 設定為預留位置時，預留位置會在加載後自動填入背景資訊的 packageName (Iaabde、b/234223561)。
現在，如果嘗試使用 navDeepLink Kotlin DSL 建立空白的 NavDeepLink，會顯示 Lint 警告，表示需要有效的 URI、動作和/或 MIME 類型才能建立深層連結 (I08d2f、b/154038883)。

API 變更

新增新的 NavDestination 擴充功能函式，以將含有 android:label="{arg}" 格式的引數的動態標籤剖析為字串。將 R.string 值剖析為其字串值，以支援 ReferenceType 引數 (I07d89、b/236269380)。

行為變更

NavBackStackEntry 的 arguments 和傳送至 OnDestinationChangedListener 的 arguments 現在只是不可變引數的副本 (您在導覽到目的地時建立了這些引數)。這表示在後續存取 arguments 或其他 OnDestinationChangedListener 執行個體時不會反映對這些套裝組合所做的任何變更 (I676f5)。

修正錯誤

在 Navigation 2.5.2 中：Dynamic Navigation 現在會先嘗試從其他模組安裝 Activity 目的地，然後再導覽到這些目的地 (Ia2c16、b/240292838)。
自 Navigation 2.5.2 起：導覽到相同目的地並將 launchSingleTop 標記設為 true 時，Navigation 現在可以正確取代 Fragment 例項 (I5a2f1、b/237374580)。
自 Navigation 2.5.2 起：修正了因導覽到雙巢狀結構圖而造成的 IllegalStateException，該結構圖會與新的彈出起始目的地分享父項 (I9f7cb、b/243778589)。

2.5 版本

2.5.3 版本

2022 年 10 月 24 日

發布 androidx.navigation:navigation-*:2.5.3。查看 2.5.3 版的修訂項。

修正錯誤

當 Crossfade 沒有可用於組合的目的地時，NavHost 不會再造成 NoSuchElementException，而只會略過組合作業。(Ieb46e、b/253299416)
修正目的地從返回堆疊彈出時，系統未忘記及移除已儲存的 Compose 狀態 (例如使用 rememberSaveable 的情形) 的問題。(I64949)

2.5.2 版本

2022 年 9 月 7 日

發布 androidx.navigation:navigation-*:2.5.2。查看 2.5.2 版的修訂項。

修正錯誤

Dynamic Navigation 現在會先嘗試從其他模組安裝 Activity 目的地，然後再導覽到這些目的地 (Ia2c16、b/240292838)。
導覽到相同目的地並將 launchSingleTop 標記設為 true 時，Navigation 現在可以正確取代 Fragment 例項 (I5a2f1、b/237374580)。
修正了因導覽到雙巢狀結構圖而造成的 IllegalStateException，該結構圖會與新的彈出起始目的地分享父項 (I9f7cb、b/243778589)。

依附元件更新

Navigation 2.5.2 現在依附於 Fragment 1.5.2 (aosp/2178734)。

2.5.1 版本

2022 年 7 月 27 日

發布了 androidx.navigation:navigation-*:2.5.1。2.5.1 版本包含此連結所列的修訂項目。

修正錯誤

使用儲存在 Bundle 中的自訂引數類型時，Navigation Safe Args 不會再導致產生類別的淘汰警告。(Id86ed、b/237725966)

依附元件更新

Navigation 程式庫現在依附於 Lifecycle 2.5.1 (Ib4451)。
導覽程式庫現在依附於 Activity 1.5.1 (I3efe8)。
導覽程式庫現在依附於 Fragment 1.5.1 (I56177)。

2.5.0 版本

2022 年 6 月 29 日

發布了 androidx.navigation:navigation-*:2.5.0。查看 2.5.0 版的修訂項。

自 2.4.0 版本以來的重要異動

CreationExtras 整合 - Navigation 現在可透過 Lifecycle 2.5.0 的 CreationExtras 提供無狀態 ViewModelProvider.Factory。

Navigation SafeArgs

Navigation Safe Args 已升級 Android Gradle Plugin 依附元件以依賴 7.0.4，捨棄 7.0 前的 AGP 版本相容性。
新增 build.gradle 的命名空間屬性支援 (而不是 applicationId)。

其他變更

visibleEntries API 已不再處於實驗階段，並且提供函式，用於擷取目的地目前可根據 NavController 顯示的所有項目。

2.5.0-rc02 版本

2022 年 6 月 15 日

發布了 androidx.navigation:navigation-*:2.5.0-rc02。查看 2.5.0-rc02 版的修訂項。

修正錯誤

修正使用 Navigation Compose NavHost 時，快速切換底部目的地時會發生的當機問題。(I3979a、b/234054916)。
使用不含 applicationId 的 applicationIdSuffix 和命名空間，或 applicationId 和命名空間不同時，Navigation SafeArgs 不會再當機。(I754b1、b/233119646)
NavArgument 現在有自訂的 toString() 函式，可顯示引數的內部值。(I900a8)

2.5.0-rc01 版本

2022 年 5 月 11 日

發布 androidx.navigation:navigation-*:2.5.0-rc01。查看 2.5.0-rc01 版的修訂項。

新功能

新增 Lint 規則，以禁止在 navigation.xml 檔案中將 <deeplink> 元素放在 <activity> 元素中。(Ic15a5、b/178403185)

修正錯誤

系統會依照預期順序處理 NavHost 和 DialogHost 中的可組合元件範圍；也就是說，系統會先處理內部可組合元件，再處理外部可組合元件。(I157e6)
Navigation SafeArgs 現可透過 ArgumentsGenerationTask 中的 PathSensitivity.RELATIVE 允許快取移動位置。這表示您可以在本機版本中重新使用持續整合 (CI) 版本的快取項目。(I5f67c、b/173420454)
更新 UnrememberedGetBackStackEntryDetector Lint 規則，確保 getBackStackEntry() 呼叫前後的 remember 呼叫也會傳入 NavBackStackEntry 物件做為索引鍵。(Ib7081、b/227382831)

2.5.0-beta01 版本

2022 年 4 月 20 日

發布 androidx.navigation:navigation-*:2.5.0-beta01。查看 2.5.0-beta01 版的修訂項。

修正錯誤

DialogNavigator 現在在執行 dismiss() 呼叫時會使用 popWithTransition。當您 dialog 目的地中使用 ViewModel 時，如果使用系統返回機制或輕觸對話方塊外部區域關閉對話方塊，可能會導致 IllegalStateException，這類競爭狀況的問題已獲得修正。(Id7376、b/226552301)

依附元件更新

Navigation 現在依附於 Lifecycle 2.5.0-beta01，並修正以下問題：如果使用多個返回堆疊，將非主要底部瀏覽分頁標籤中的一個 NavHost 在另一個 NavHost 內建立巢狀結構時會發生 IllegalStateException。

2.5.0-alpha04 版本

2022 年 4 月 6 日

發布 androidx.navigation:navigation-*:2.5.0-alpha04。查看 2.5.0-alpha04 版的修訂項。

API 變更

visibleEntries 已不再處於實驗階段 (I4829f、b/225394514)。

修正錯誤

NavHost 現在取決於 NavController 中的 visibleEntries，以決定要撰寫的項目。這表示在使用巢狀的 NavHost 時，內部的 NavHost 現已可正確顯示動畫效果。(I4ba2b、b/225394514)
NavController 提供的 visibleEntries StateFlow 現在會以項目的最大生命週期狀態為基準，而非目前的生命週期狀態。也就說，即使 navController 的代管生命週期低於 STARTED，可見的項目清單仍會維持不變。(I9e2a8、b/225394514)
SavedStateViewFactory 現在支援使用 CreationExtras (即使已透過 SavedStateRegistryOwner 初始化也沒問題)。如果提供額外項目，系統將忽略初始化的引數 (I6c43b、b/224844583)
NavDeepLink 現在可以在沒有值的狀況下，以單一查詢參數來剖析 URI。(I0efe8、b/148905489)
現在，系統會將空白字串視為深層連結中的有效引數。(I70a0d、b/217399862)
使用命名空間且沒有任何 AndroidManifest.xml 時，Navigation Safe Args 不會再異常終止 (I17ccf、b/227229815)

2.5.0-alpha03 版本

2022 年 2 月 23 日

發布 androidx.navigation:navigation-*:2.5.0-alpha03。查看 2.5.0-alpha03 版的修訂項。

API 變更

現可將 CreationExtras 傳入 by navGraphViewModels 以建立 ViewModel (I29217、b/217618359)

修正錯誤

NavDeepLinks 現在可正確支援嵌入路徑/深層連結 URI 中經過編碼的新行字元。(I513d1、b/217815060)。
現在將 CreationExtras 與 NavBackStackEntries 搭配使用時可正確建立 ViewModel。(I69161、b/217617710)。
Navigation Safe Args 現在支援使用 build.gradle 中定義的命名空間，取代 AndroidManifest 中的套件 (I659ef、b/217414933)

2.5.0-alpha02 版本

2022 年 2 月 9 日

發布 androidx.navigation:navigation-*:2.5.0-alpha02。查看 2.5.0-alpha02 版的修訂項。

修正錯誤

自 Navigation 2.4.1 起：使用含有巢狀結構圖的 viewbinding 時，NavHostFragment 現在可正確設定 OnBackPressedDispatcher (Ifbb51、b/214577959)。
自 Navigation 2.4.1 起：透過多個巢狀結構 NavGraph 設定深層連結時，返回堆疊現在可正確納入中繼起始目的地。(I504c0、b/214383060)

2.5.0-alpha01 版本

2022 年 1 月 26 日

發布 androidx.navigation:navigation-*:2.5.0-alpha01。查看 2.5.0-alpha01 版的修訂項。

新功能

NavBackStackEntry 現已整合 ViewModel CreationExtras (先前為 Lifecycle 2.5.0-alpha01 的部分元件)。(Ib9fe2、b/207012490)

修正錯誤

在 Fragment 的 onCreate() 中存取透過 by navGraphViewModels() 建立的 ViewModel 時會失敗並導致 IllegalStateException，這個問題已獲得修正。(I8a14d)
NavDeepLink 無需再對引數進行兩次不必要的解碼，這表示適當的引數現在會傳遞至最終目的地。(I31b0a、b/210711399)

Safe Args

Safe Args 現在依附於 Android Gradle 外掛程式 7.0.4 版本。這表示 Navigation Safe Args 將不再支援 Android Studio 7.0 以下版本，但現已支援 Android Gradle 外掛程式 7.1.0 以上版本 (I41c88、b/213086135、b/207670704)

2.4.2 版本

2022 年 4 月 6 日

發布 androidx.navigation:navigation-*:2.4.2。查看 2.4.2 版的修訂項。

修正錯誤

從 Navigation 2.5.0-alpha03 向後移植：NavDeepLinks 現可正確支援嵌入路徑/深層連結 URI 中經過編碼的新行字元。(I513d1、b/217815060)
從 Navigation 2.5.0-alpha03 向後移植：Navigation SafeArgs 現已支援使用 build.gradle 中定義的命名空間來取代 AndroidManifest 中的套件。(I659ef、b/217414933)
從 Navigation 2.5.0-alpha04 向後移植：使用命名空間且沒有 AndroidManifest.xml 時 Navigation Safe Args 不會再損毀。(I17ccf、b/227229815)
從 Navigation 2.5.0-alpha04 向後移植：現在會將空白字串視為深層連結中的有效引數。(I70a0d、b/217399862)

2.4.1 版本

2022 年 2 月 9 日

發布 androidx.navigation:navigation-*:2.4.1。查看 2.4.1 版的修訂項。

修正錯誤

使用含有巢狀結構圖的 viewbinding 時，NavHostFragment 現在可正確設定 OnBackPressedDispatcher (Ifbb51、b/214577959)。
透過多個巢狀結構 NavGraph 設定深層連結時，返回堆疊現可正確納入中繼起始目的地。(I504c0、b/214383060)
自 Navigation 2.5.0-alpha01 向後移植：在 Fragment 的 onCreate() 中存取透過 by navGraphViewModels() 建立的 ViewModel 時會失敗並導致 IllegalStateException，這個問題已獲修正。(I8a14d)
從 Navigation 2.5.0-alpha01 向後移植：NavDeepLink 無需再對引數進行兩次不必要的解碼，這表示適當的引數現已傳遞至最終目的地。(I31b0a、b/210711399)
從 Navigation 2.5.0-alpha01 向後移植：Safe Args 現在依附於 Android Gradle 外掛程式 7.0.4 版本。這表示 Navigation Safe Args 將不再支援 Android Studio 7.0 以下版本，但現已支援 Android Gradle 外掛程式 7.1.0 以上版本 (I41c88、b/213086135、b/207670704)

2.4.0 版本

2022 年 1 月 26 日

發布 androidx.navigation:navigation-*:2.4.0。查看 2.4.0 版的修訂項。

2.3.0 版之後的重要異動

所有 Navigation 構件都已使用 Kotlin 重新編寫，對於採用一般項目的類別 (例如 NavType 子類別) 改善了其「是否可為空值」的屬性。過去屬於 -ktx 構件的所有 Kotlin 擴充功能都已移至各自的主要構件中。-ktx 構件會繼續發布，但不會有任何內容。
navigation-fragment 構件現可透過新的 AbstractListDetailFragment，納入預先建構的雙窗格版面配置實作項目。此片段會使用 SlidingPaneLayout 管理清單窗格 (也就是子類別提供的清單) 和詳細資料窗格，其使用 NavHostFragment 做為實作方式，如實作範例中所示。
NavController 上的 currentBackStackEntryAsFlow() 方法提供 Flow，會在每次目前的 NavBackStackEntry 變化時發出。您可以將這個流程做為手動管理 OnDestinationChangedListener 的替代選項。
NavController 現在提供透過實驗性 visibleEntries 屬性，擷取所有可見 NavBackStackEntry 執行個體清單做為 StateFlow 的功能。
現在可以擴充 NavType 類別來建立自訂 NavType。只有在以程式輔助方式 (例如透過 Navigation Graph Kotlin DSL) 建構導覽圖時才支援自訂類型。
Navigation 現在提供 findStartDestination() 和 getHierarchy() API，可用來實作自訂 NavigationUI。findStartDestination() 是 NavGraph 的擴充功能函式，可用來找出前往特定導覽圖時才會顯示的實際起始目的地，即使 startDestination 本身就是巢狀結構的 NavGraph 也沒問題。getHierarchy() 是 NavDestination 上的函式，可用來驗證特定目的地是否位於另一個階層中。
```
val matchingRoute: Boolean = destination.hierarchy.any { it.route == routeToFind }
```
更新原本接受 BottomNavigationView 的 NavigationUI 方法，改為接受 Material 1.4.0 中引入的父類別 NavigationBarView。這樣即可將這些方法與 NavigationRailView 搭配使用。
當透過 XML 加載 <action> 元素時，動畫屬性可使用透過 app:enterAnim="?attr/transitionEnter" 語法從主題中擷取的屬性。

Safe Args 現在會為每個 NavArgs 類別產生 fromSavedStateHandle() 方法。(#122、b/136967621)

class HomeViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
  // Create a HomeDestinationArgs class with type safe accessors for each argument
  // defined on your destination
  private val args = HomeDestinationArgs.fromSavedStateHandle(savedStateHandle)
}

導覽路徑和 Kotlin DSL

先前版本的 Navigation 依附於每個具有常數整數 ID 的目的地，該 ID 可用來從同層目的地中識別對應的目的地，並允許直接或透過動作 navigate() 至該目的地。這個做法仍然有效且實用，尤其當您要在 XML 中定義導覽圖，且可以使用自動產生的 R.id 常數或 Safe Args (會在建構時間使用這些常數產生程式碼) 時。然而，當您要在執行階段以程式輔助方式建構完整動態圖形時，這種不重複整數的系統便無法透過 Navigation Kotlin DSL 擷取所需的語意含義和展現方式。

這個版本推出了一個新選項，有助於依照目的地「路徑」在導覽圖明確識別目的地。「路徑」為定義目的地唯一路徑的 String。過去接受目的地 ID 的所有 Kotlin DSL 方法現已淘汰，替換為接受路徑的同等 API。

每個路徑都應視為定義該目的地的 Uri 的「路徑」部分，例如 home、profile/{userId}、profile/{userId}/friends 等。如果目的地識別資訊與特定內容相關聯，這些動態引數應屬於路徑的一部分，並遵循與隱式深層連結相同的規則。

以往只接受 ID 的所有 NavController API 現在都具有接受路徑 String 的超載，包含 navigate()、popBackStack()、popUpTo() 和 getBackStackEntry()。

這對 API 產生了一些影響：

Kotlin DSL 上的 popUpTo Kotlin 屬性已淘汰，請改用 popUpToId。
getStartDestination() API 已淘汰，並改用 getStartDestinationId()。

與依照 ID 導覽不同的是，依照路徑導覽時會遵循與隱式深層連結相同的規則；您可以直接導覽至任何巢狀圖表中的任何目的地，確保這些路徑可在多模組專案中使用，無須為每個目的地明確加上外部可見的深層連結。

Navigation Compose

navigation-compose 構件可提供 Navigation Component 和 Jetpack Compose 之間的整合功能，並使用 @Composable 函式做為應用程式的目的地。

這個版本提供以下功能：

NavHost 可組合元件，可讓您使用 composable 和 dialog 目的地透過 Kotlin DSL 建構導覽圖，並支援選用導覽器，例如來自 Accompanist Navigation Material 的導覽器。
提供目的地之間交叉漸變效果的必要支援。Acomcomistist Navigation Animation 可讓您使用實驗性 Compose API 控制進入與退出的轉場效果。
將 Lifecycle 的範圍限定為成各個可組合元件目的地。每個目的地只會在任何進入的轉場效果結束時達到 RESUMED 狀態，並且在退出的轉場效果開始時立即降為 STARTED。如此一來，只要在 Lifecycle 為 RESUMED 狀態時觸發 navigate 呼叫，即可避免所有的 IllegalStateException 和多點觸控問題。
在目的地層級限定 ViewModel 的範圍 (透過 Lifecycle ViewModel Compose 2.4.0 的 viewModel() API 或 Hilt Navigation Compose 1.0.0 的 hiltViewModel())，提供一個設定變更後仍繼續存在並位於返回堆疊 (當可組合元件內容以其他方式處理時) 的範圍，同時在 ViewModel 的 onCleared() 中提供信號，指示系統永久處理及清除與該 NavBackStackEntry 相關聯的狀態。
在目的地層級限定 rememberSaveable 狀態的範圍，確保系統會自動儲存所有可組合元件的狀態，並在您返回目的地時還原這些狀態。
完整支援儲存 NavController 狀態及其目的地的狀態，並在程序死亡及重建後還原這些狀態。
自動與系統返回按鈕整合。
支援傳遞引數、將深層連結附加至目的地，以及將結果傳回至之前的目的地。
rememberNavController() 和 currentBackStackEntryAsState() 中的特定 Compose 輔助工具，可讓您提升狀態，並將 NavController 連接至 NavHost 外的可組合元件 (例如底部導覽列)。

val navController = rememberNavController()
Scaffold { innerPadding ->
    NavHost(navController, "home", Modifier.padding(innerPadding)) {
        composable("home") {
            // This content fills the area provided to the NavHost
            HomeScreen()
        }
        dialog("detail_dialog") {
            // This content will be automatically added to a Dialog() composable
            // and appear above the HomeScreen or other composable destinations
            DetailDialogContent()
        }
    }
}

詳情請參閱 Compose Navigation 指南。

多個返回堆疊

NavController 負責管理目的地的返回堆疊，當您 navigate() 至其堆疊位置時會在返回堆疊中新增目的地，並且在您呼叫 popBackStack() 或觸發系統返回按鈕時移除這些目的地。我們擴展了導覽圖 XML 中現有 NavOptions 類別以及與 <action> 元素的整合功能，以支援儲存及還原返回堆疊的功能。

做為本次異動的一部分，onNavDestinationSelected()、BottomNavigationView.setupWithNavController() 和 NavigationView.setupWithNavController() 的 NavigationUI 方法現在會自動儲存並還原彈出目的地的狀態，因此無需變更任何程式碼即可支援多個返回堆疊。將 Navigation 與 Fragment 搭配使用時，建議採用這個方法與多個返回堆疊整合。

用於儲存及還原狀態的基礎 API 會透過多個介面公開：

在 Navigation XML 中，<action> 元素現可使用 app:popUpToSaveState 和 app:restoreState 的布林值屬性，儲存透過 app:popUpTo 彈出的任何目的地狀態，並還原做為 app:destination 傳遞的目的地相關聯狀態：
```
<action
  android:id=”@+id/swap_stack”
  app:destination=”@id/second_stack”
  app:restoreState=”true”
  app:popUpTo=”@id/first_stack_start_destination”
  app:popUpToSaveState=”true” />
```

在 navOptions Kotlin DSL 中，您可以在 popUpTo 建構工具中加入 restoreState 布林值屬性和 saveState 布林值屬性：

// Use the navigate() method that takes a navOptions DSL Builder
navController.navigate(selectedBottomNavRoute) {
  launchSingleTop = true
  restoreState = true
  popUpTo(navController.graph.findStartDestination().id) {
    saveState = true
  }
}

透過 NavOptions.Builder 手動構建 NavOptions 物件時，可對接受額外 saveState 參數的 setPopUpTo() 使用 setRestoreState() 和新的過載。

NavOptions navOptions = new NavOptions.Builder()
  .setLaunchSingleTop(true)
  .setRestoreState(true)
  .setPopUpTo(NavGraph.findStartDestination(navController.getGraph()).getId(),
    false, // inclusive
    true) // saveState
  .build();
navController.navigate(selectedBottomNavId, null, navOptions);

對 popBackStack() 發出的程式輔助呼叫現可包含額外的 saveState 參數。
您可以使用 clearBackStack() 方法清除透過 popBackStack() 或 popUpToSaveState 儲存的任何狀態。

在所有情況下，NavController 會儲存及還原每個 NavBackStackEntry 的狀態，包括限定於任何導覽目的地的 ViewModel 執行個體。Navigator API 已經過更新，可讓每個 Navigator 支援儲存及還原本身的狀態。

行為變更

NavDeepLinkBuilder 現在會將 PendingIntent.FLAG_IMMUTABLE 新增至 createPendingIntent() 傳回的 PendingIntent 中，確保這個 API 在以 Android 12 為目標的環境中能正常運作。
Navigation 現在依附於 Lifecycle 2.3.1，且現在會將更新 NavBackStackEntry Lifecycle 的 setGraph()、popBackStack()、navigateUp() 和 navigate() 方法標示為 @MainThread，讓 Navigation 與 Lifecycle 2.3.0 中引入的主要執行緒強制執行功能保持一致。
深層連結現在會驗證 Uri 中是否包含所有必要引數 (不含預設值的引數)。
以 NavDeepLink 剖析的引數現在會將英鎊符號與問號一樣視為是路徑片段之間的分隔符，以免引數跨越英鎊符號。
產生動作時，Safe Args 產生的 Kotlin 程式碼現在會優先將不含預設值的引數做為參數，然後才使用含有預設值的引數。
產生引數時，Safe Args 現在會優先使用不含預設值的參數，然後才使用含有預設值的參數。
Safe-Args 現在依附於 Android Gradle 外掛程式 4.2.0。如此一來，您不會再收到使用 applicationIdTextResource 的警告。

已知問題

修正 Navigation 2.5.0-alpha01 中的問題：從 Fragment 的 onCreate() 存取透過 by navGraphViewModels() 建立的 ViewModel 時會失敗並顯示 IllegalStateException。(b/213504272)
修正 Navigation 2.5.0-alpha01 中的問題：Safe Args 2.4.0 與 Android Gradle 外掛程式 7.1.0 以上版本不相容。(b/213086135)
如果深層連結含有多個巢狀結構導覽圖，則無法正確建立完整的返回堆疊。(b/214383060)

2.4.0-rc01 版本

2021 年 12 月 15 日

發布 androidx.navigation:navigation-*:2.4.0-rc01。查看 2.4.0-rc01 版的修訂項。

行為變更

由 NavDeepLink 剖析的引數現在會將英鎊符號與問號一樣視為是引數之間的分隔符。(I21309、b/180042703)

修正錯誤

深層連結將不再忽略含有與預留位置名稱相同值的引數。(If8017、b/207389470)
還原 NavController 後，NavController 使用轉場效果彈出巢狀結構目的地時將不再發生當機。(I0f7c9、b/205021623)
使用無效的 startDestination 時，系統顯示的錯誤訊息將預設為起始目的地的路徑 (如有的話)。(I86b9d、b/208041894)

修正 Navigation Compose 錯誤

修正問題：使用底部導覽選單項目在起始目的地和其他目的地之間快速切換時可能會導致當機。(Ic8976、b/208887901)
在設定變更或程序死亡後，對話方塊目的地現在可以在螢幕頂端正確還原。(I4c0dc、b/207386169)
修正問題：對話方塊關閉時，系統嘗試從對話方塊的 NavBackStackEntry 擷取 ViewModel 的作業會失敗。(I6b96d、b/206465487)
修正問題：將 activity 目的地與 Navigation Compose 的 NavHost 搭配使用時會導致無限重組情形。(I8f64c)
修正 Navigation Compose 中的外洩問題：系統在設定變更或程序終止後會保留舊活動的參照。(I4efcb、b/204905432)

修正 Safe Args 錯誤

程序停擺後，SafeArgs 嘗試還原自訂可封裝陣列時不會再發生當機。(I618e8、b/207315994)
修正 Safe Args 不允許布林值陣列含有 null 值的錯誤 (I8c396、b/174787525)。

2.4.0-beta02 版本

2021 年 11 月 3 日

發布 androidx.navigation:navigation-*:2.4.0-beta02。查看 2.4.0-beta02 版的修訂項。

API 變更

如果導覽至其他導覽圖，系統在處理顯式與隱式深層連結時會自動新增 saveState 標記，以確保這類程式碼 (例如 NavigationUI.setupWithNavController 和使用多個返回堆疊的程式碼) 能正常運作。(Ic8807)

行為變更

深層連結模式現在是在 NavDeepLink 中 (而不是在加載期間) 延遲編譯。這樣可以改善含有深層連結的導覽圖的加載時間。(b8d257、b/184149935)

修正錯誤

修正問題：將 NavHost 直接加到活動的 setContent() 時，系統會將移至 Lifecycle.State.STARTED 後的 NavBackStackEntries 下推至 Lifecycle.State.CREATED。(Ia5ac1、b/203536683)
在對話方塊中實際顯示前從返回堆疊彈出 DialogFragment 目的地時，實際上不會關閉對話方塊，導致系統在使用者手動關閉錯誤的對話方塊時發生當機，這類競爭狀況已獲得修正。(I687e5)
修正問題：即使您實際上並未 navigate() 至該導覽圖，NavigationUI 上的 onNavDestinationSelected API 也會傳回 true。現在，該 API 使用的邏輯與 setupWithNavController 內部使用的邏輯相同，會採用目的地的 hierarchy，只選擇與目前目的地相關聯的 MenuItem。(I2b053)

2.4.0-beta01 版本

2021 年 10 月 27 日

發布 androidx.navigation:navigation-*:2.4.0-beta01。查看 2.4.0-beta01 版的修訂項。

新功能

您現在可以將 by navGraphViewModel 與路徑搭配使用，做為使用 ID 的替代方案，以便妥善支援使用 Navigation Kotlin DSL 處理 Fragment 的情況。(I901e3、b/201446416)

API 變更

visibleEntries API 目前處於實驗階段 (I93f6f)

修正錯誤

在相同螢幕之間來回切換而中斷轉場效果時，系統將不再刪除 ViewModel (Id52d8、b/200817333)
在 NavDestination 中新增深層連結時，可為空值的 NavDeepLink 引數不再需要預設值。(I5aad4、b/201320030)。
不同 Lifecycle 的 NavBackStackEntries 現已不再視為相等。也就是說，使用 singleTop 進行導覽，以及重新選取底部選單項目時，NavHost 可正確重新組合所有的目的地。(I1b351、b/196997433)
修正 AbstractListDetailFragment 的問題：導致 onCreateListPaneView() 傳回的清單窗格中的 layout_width 和 layout_weight 屬性被錯誤處理或遭到忽略。(f5fbf3)
對話方塊目的地的視覺化狀態現在可正確與 DialogFragmentNavigator 的狀態保持同步。也就是說，如果您手動呼叫 DialogFragment 的非同步 dismiss() API，系統現在可正確清除目前現已關閉的對話方塊之上的所有對話方塊目的地。這並不會對您使用 popUpTo 或 popBackStack() 關閉對話方塊的情況產生任何影響。(I77ba2)
AbstractAppBarOnDestinationChangedListener 現在可針對 onDestinationChanged() 提供更明確的錯誤訊息。(Ie742d)

2.4.0-alpha10 版本

2021 年 9 月 29 日

發布 androidx.navigation:navigation-*:2.4.0-alpha10。查看 2.4.0-alpha10 版的修訂項。

新功能

NavController 現在支援透過 visibleEntries StateFlow 擷取所有可見 NavBackStackEntry 執行個體清單的功能。(Ia964e)
rememberNavController() 現在接受可選用的 Navigator 執行個體組合；系統會將這個執行個體加到傳回的 NavController，對選用的導覽器 (例如來自 Accompanist Navigation Material 的導覽器) 提供更完善的支援。(I4619e)

修正錯誤

重新建立 Activity 時，Dynamic Navigation 不會再發生當機。(Ifa6a3、b/197942869)
修正只有在彈回包含 NavHost 的可組合目的地後才會發生的系統返回按鈕問題。(3ed148、b/195668143)
SafeArgs 現在會以適當的參數順序產生 fromBundle() 和 fromSavedStateHandle() 的引數。(I824a8、b/200059831)

2.4.0-alpha09 版本

2021 年 9 月 15 日

發布 androidx.navigation:navigation-*:2.4.0-alpha09。查看 2.4.0-alpha09 版的修訂項。

新功能

您現在可以使用 clearBackStack() 方法清除透過 popBackStack() 或 popUpToSaveState 儲存的任何狀態。(I80a0f)
您現在可以對巢狀結構導覽圖的建構工具傳入引數和/或深層連結的清單，而系統會自動將清單內容加到產生的圖形中。(I8a470、b/182545357)

API 變更

navArgument Kotlin DSL 函式現在隸屬於 navigation-common，而非 navigation-compose。您必須更新匯入內容才能繼續使用這個函式。(I1d095)

行為變更

產生引數時，Safe Args 現在會優先使用不含預設值的參數，然後才使用含有預設值的參數。(I89709、b/198493585)

修正錯誤

使用 Navigation Compose 時，只有在其所有子項為 DESTROYED 狀態時，NavGraphs 才會處於 DESTROYED 狀態。(I86552、b/198741720)
可為空值的 NavDeepLink 引數不再需要使用預設值 (Ia14ef、b/198689811)
使用新圖形呼叫 setGraph() 時，不僅會清除彈出返回堆疊之前的行為，也會一併清除所有已儲存的返回堆疊。(I97f96)
修正問題：使用 launchSingleTop 時，系統不會通知 OnDestinationChangedListener 執行個體和 currentBackStackEntryFlow。(Iaaebc)

依附元件更新

Navigation Compose 現在依附於 Activity Compose 1.3.1。(I05829)
Navigation Compose 現在依附於 Lifecycle ViewModel Compose 2.4.0-beta01。(Ib86a3)

2.4.0-alpha08 版本

2021 年 9 月 1 日

發布 androidx.navigation:navigation-*:2.4.0-alpha08。查看 2.4.0-alpha08 版的修訂項。

新功能

現在可以擴充 NavType 類別來建立自訂 NavType。只有透過程式輔助方式 (例如透過 Navigation Graph Kotlin DSL) 建構導覽圖時才支援自訂類型。(I78440、b/196871885)

行為變更

產生動作時，Safe Args 產生的 Kotlin 程式碼現在會優先將不含預設值的引數做為參數，然後才使用含有預設值的引數。(Idb697、b/188855904)
深層連結現在會驗證 Uri 中是否包含所有必要引數 (不含預設值的引數)。(#204、b/185527157)

修正錯誤

將 composable() 中的 getBackStackEntry 和 previousBackStackEntry 與 remember() 合併使用時，將不再導致返回堆疊中沒有目的地的例外狀況。(I75138、b/194313238)
變更返回堆疊引數並使用 launchSingleTop=true 時，Navigation Compose 現在可正確重組。(Iebd69、b/186392337)
使用具有 13 或 29 個目的地的圖形呼叫 setGraph 時，將不再出現 ArrayIndexOutOfBoundsException。(I1a9f1、b/195171984)
產生 Args 類別時，SafeArgs Java 產生器應該不會再導致 Lint 警告。(I1a666、b/185843837)

外部貢獻

感謝 ospixd 的協助，確認深層連結會驗證 Uri 中是否包含所有必要引數 (不含預設值的引數)。(#204、b/185527157)

2.4.0-alpha07 版本

2021 年 8 月 18 日

發布 androidx.navigation:navigation-*:2.4.0-alpha07。查看 2.4.0-alpha07 版的修訂項。

修正錯誤

在設定變更後，以及使用多個返回堆疊功能變更圖形時，Navigation Compose 現在可正確儲存狀態。(If5a3d、b/195141957)
將 Navigation Compose 與多個返回堆疊搭配使用時，重新選取同一個分頁不會再顯示空白螢幕。(I860dc、b/194925622)。
NavHost 現在會觀察 NavBackStackEntry 的 Lifecycle.State 中的任何異動；也就是說，NavHost 在片段中使用時會隨著生命週期變更正確重組，而不會顯示空白螢幕。(I4eb85、b/195864489)
修正問題：在重新建立活動之後 (例如在設定變更後)，關閉 DialogFragment 時不會正確更新 NavController 狀態。(Icd72b)
修正問題：彈出對話方塊目的地時不會更新 NavController 的系統返回按鈕處理作業，可能導致 NavController 攔截返回按鈕，即使沒有任何可彈出的返回堆疊。(If3b34)
Safe-args 現在會為引數自動產生 toSavedStateHandle 方法，可用於測試 ViewModel 程式碼。(If1e2d、b/193353880)

2.4.0-alpha06 版本

2021 年 8 月 4 日

發布 androidx.navigation:navigation-*:2.4.0-alpha06。查看 2.4.0-alpha06 版的修訂項。

API 變更

AbstractListDetailFragment 中的 requireSlidingPaneLayout() 和 requireDetailPaneNavHostFragment() 方法已分別重新命名為 getSlidingPaneLayout() 和 getDetailPaneNavHostFragment()。(I34a08)

行為變更

透過動畫 (例如 Crossfade) 導覽時，新目的地的 Lifecycle 現在只會在動畫結束時達到 RESUMED。(If0543、b/172112072、b/194301889)
Navigation Compose 的 NavHost 現在會將圖形設為第一個組合的一部分 (Ieb7be)

修正錯誤

彈出導覽圖的最後一個目的地時，不會再擲回 ClassCastException。(If0543、b/172112072、b/194301889)
修正問題：新增不含 Uri 的深層連結，以及透過路徑或深層連結導覽時，會發生 NullPointerException。(938a0c、b/193805425)。
修正 Navigation Compose 中的問題：加上深層連結的 NavBackStackEntry 無法達到 RESUMED 狀態 (I192c5)
修正問題：彈出對話方塊目的地時不會更新 NavController 的系統返回按鈕處理作業，可能導致 NavController 攔截返回按鈕，即使沒有任何可彈出的返回堆疊。(aosp/1782668)

2.4.0-alpha05 版本

2021 年 7 月 21 日

發布 androidx.navigation:navigation-*:2.4.0-alpha05。查看 2.4.0-alpha05 版的修訂項。

行為變更

在目的地之間導覽時，Navigation Compose 的 NavHost 現在會一律使用交叉漸變效果。(I07049、b/172112072)
您現在可以變更 NavHost 圖形。系統會將具有相同 startDestination 的圖形以及圖形中的目的地視為相等，且不會清除 NavController 返回堆疊。(I0b8db、b/175392262)

修正錯誤

從附加至 NavBackStackEntry 的 LifecycleObserver 內呼叫 popBackStack() 時，因對 NavController 的狀態進行重入更新而導致出現 NoSuchElementException，這個錯誤已獲得修正。(I64621)
在 AbstractListDetailFragment 未使用的情況下，AbstractListDetailFragment 現在允許從 APK 中完全刪除 SlidingPaneLayout。(I611ad)
NavGraph 和 NavDestination 現在會覆寫 equals 方法，因此兩個含有相同值的物件會視為相等。(I166eb、b/175392262)

2.4.0-alpha04 版本

2021 年 7 月 1 日

發布 androidx.navigation:navigation-*:2.4.0-alpha04。查看 2.4.0-alpha04 版的修訂項。

新功能

navigation-fragment 構件現可透過新的 AbstractListDetailFragment，納入預先建構的雙窗格版面配置實作項目。此片段使用 SlidingPaneLayout 來管理清單窗格 (也就是子類別提供的清單) 及詳細資料窗格，其使用 NavHostFragment 做為實作，如實作範例中所述。(Iac4be、b/191276636)
navigation-compose 構件的 NavHost 除了支援 composable 目的地外，現在也支援 dialog 目的地。這些對話方塊目的地都會顯示在各自對應的 Dialog 可組合元件內，並懸浮在目前 composable 目的地上方。(I011d0)

val navController = rememberNavController()
    Scaffold { innerPadding ->
        NavHost(navController, "home", Modifier.padding(innerPadding)) {
            composable("home") {
                // This content fills the area provided to the NavHost
                HomeScreen()
            }
            dialog("detail_dialog") {
                // This content will be automatically added to a Dialog() composable
                // and appear above the HomeScreen or other composable destinations
                DetailDialogContent()
            }
        }
    }

API 變更

NavigatorState 中的 add 函式已重新命名為 push。目前對 add() 的所有呼叫都必須變更為 push()。(Ie89fc、b/172112072)
自訂 Navigator 執行個體現在可透過 NavigatorState 上的 pushWithTransaction 和 popWithTransition API，以非同步的方式推送或彈出目的地。請注意，任何隨附的導覽器都還未使用這個 API。(Ic4d7c、b/172112072)

行為變更

NavDeepLinkBuilder 現在會將 PendingIntent.FLAG_IMMUTABLE 新增至 createPendingIntent() 傳回的 PendingIntent 中，確保這個 API 在以 Android 12 為目標的環境中能正常運作。(If8c52)

修正錯誤

修正問題：使用 <include-dynamic> 時，傳遞至圖形的引數無法正確傳遞至動態納入的圖形。(I3e115)
修正透過含有 @null 預設值的 string[] 引數導覽至目的地時會出現的 NullPointerException 問題。(I1fbe8)
新增 @Navigator.Name 的 ProGuard 規則，並修正使用 R8 3.1 完整模式時會出現的問題。(I2add9、b/191654433)
使用 Kotlin 1.5.0 以下版本建構應用程式時，SafeArgs 將不再發生錯誤。(Icd1ff、b/190739257)

2.4.0-alpha03 版本

2021 年 6 月 16 日

發布了 androidx.navigation:navigation-*:2.4.0-alpha03。查看 2.4.0-alpha03 版的修訂項。

修正錯誤

修正問題：需要呼叫兩次 navigate() 才能導覽至內含的動態圖形。(I7785c、b/188859835)
修正 Navigation 2.4.0-alpha01 中引發的迴歸問題：在頂層目的地時，setupActionBarWithNavController() 不會正確移除 Up 圖示。(I5d443、b/189868637)
修正在先前彈出 NavController 根圖形後呼叫 popBackStack() 時會出現的 IllegalStateException 問題。(I2a330、b/190265699)
使用 navigation-common 以及依附於它的所有構件時，現在可正確套用 by navArgs() 的 ProGuard 規則 (I68800、b/190082521)
如果 OnDestinationChangedListener 在第一次收到回呼時呼叫 navigate()，現在可正確收到第二次回呼，其中包含要導覽前往的目的地。(Ie5f9e、b/190228815)
將 Safe Args 與動態功能模組和 AGP 7.0 以上版本搭配使用時，不會再發生當機。(I69518、b/189966576)。

已知問題

由於 Gradle 6.7.0 依附於舊版的 Kotlin，因此在使用時會導致 Safe Args 失敗，並顯示 Unable to find method ‘’java.lang.String kotlin.text.CarsKt.titleCase(char, java.util.Locale)’’ 錯誤。只要更新至 Gradle 7.0 即可解決。(b/190739257)

2.4.0-alpha02 版本

2021 年 6 月 2 日

發布 androidx.navigation:navigation-*:2.4.0-alpha02。查看 2.4.0-alpha02 版的修訂項。

新功能

Activity、Fragment 和 Dialog 目的地以及整個 DynamicNavigation Kotlin DSL 現在都支援路徑。(Ib5544、Ia617b、I22f96、b/188914648、b/188901565)
NavigationUI 暫時新增了實驗性 API，可讓您選擇不要儲存狀態。雖然一律儲存狀態才是正確的行為，但系統仍會在儲存狀態時使用不受支援而淘汰的程式庫 (即保留的片段)，這麼做能讓應用程式逐漸汰換不受支援的 API。(Idf93c)
Navigation 現在提供 findDestination() 和 getHierarchy() API，可用於實作自訂 NavigationUI。findDestination() 是 NavGraph 上的擴充功能，可用來在圖形中找到目的地。getHierarchy() 則是 NavDestination 上的函式，可用來驗證特定目的地是否位於其他階層結構中。(I2932f、b/188183365)
```
val matchingRoute: Boolean = destination.hierarchy.any { it.route == routeToFind }
```
更新原本接受 BottomNavigationView 的 NavigationUI 方法，改為接受 Material 1.4.0 中引入的 NavigationBarView 父類別。這樣即可將這些方法與 NavigationRailView 搭配使用。(Ib0b36、b/182938895)
當透過 XML 加載 <action> 元素時，動畫屬性可使用透過 app:enterAnim="?attr/transitionEnter" 語法從主題中擷取的屬性。(I07bc1、b/178291654)

API 變更

淘汰使用 ID 的 Kotlin DSL 建構工具，請改用使用路徑的建構工具 (I85b42、b/188816479) (I9f58f、b/188816479)

修正錯誤

使用者按下系統返回按鈕或點選按鈕外的區域來關閉對話方塊時，DialogFragmentNavigator 現在會使用 NavigatorState.pop() API 來通知 NavController，以確保 NavController 狀態一律會與導覽器的狀態保持同步。(I2ead9)
使用 onDestinationChanged 回呼操控 OnDestinationChangedListeners 的清單時，Navigation 不會再提供 ConcurrentModificationException。(Ib1707、b/188860458)
嘗試在 Kotlin 中產生方向屬性時，Safe Args 不會再發生當機。(Id2416、b/188564435)
現在可正確使用 @IdRes 為 NavDestination 上的 setId 方法加上註解，因此這個方法只接受資源 ID。(I69b80)
findNode 的 int 參數現在是 resId，而不是 resid。(I7711d)

依附元件更新

Safe-Args 現在依附於 Android Gradle 外掛程式 4.2.0。如此一來，您不會再收到使用 applicationIdTextResource 的警告。(I6d67b、b/172824579)。

2.4.0-alpha01 版本

2021 年 5 月 18 日

發布 androidx.navigation:navigation-*:2.4.0-alpha01。查看 2.4.0-alpha01 版的修訂項。

新功能

NavController 上的 currentBackStackEntryAsFlow() 方法提供 Flow，會在每次目前的 NavBackStackEntry 變化時發出。您可以將這個流程做為手動管理 OnDestinationChangedListener 的替代選項。(I19c4a、#89、b/163947280)

多個返回堆疊

NavController 負責管理目的地的返回堆疊，當您 navigate() 至其堆疊位置時會在返回堆疊中新增目的地，並且在您呼叫 popBackStack() 或觸發系統返回按鈕時移除這些目的地。我們擴展了導覽圖 XML 中現有 NavOptions 類別以及與 <action> 項目的整合功能，以支援儲存及還原返回堆疊的功能。(b/80029773)

用於儲存及還原狀態的基礎 API 會透過多個介面公開：

在 Navigation XML 中，<action> 元素現可使用 app:popUpToSaveState 和 app:restoreState 的布林值屬性，儲存透過 app:popUpTo 彈出的任何目的地狀態，並還原做為 app:destination 傳遞的目的地相關聯狀態：
```
<action
  android:id=”@+id/swap_stack”
  app:destination=”@id/second_stack”
  app:restoreState=”true”
  app:popUpTo=”@id/first_stack_start_destination”
  app:popUpToSaveState=”true” />
```

在 navOptions Kotlin DSL 中，您可以在 popUpTo 建構工具中加入 restoreState 布林值屬性和 saveState 布林值屬性：

// Use the navigate() method that takes a navOptions DSL Builder
navController.navigate(selectedBottomNavRoute) {
  launchSingleTop = true
  restoreState = true
  popUpTo(navController.graph.startDestinationId) {
    saveState = true
  }
}

透過 NavOptions.Builder 手動構建 NavOptions 物件時，可對接受額外 saveState 參數的 setPopUpTo() 使用 setRestoreState() 和新的過載。

NavOptions navOptions = new NavOptions.Builder()
  .setLaunchSingleTop(true)
  .setRestoreState(true)
  .setPopUpTo(navController.getGraph().getStartDestinationId(),
    false, // inclusive
    true) // saveState
  .build();
navController.navigate(selectedBottomNavId, null, navOptions);

對 popBackStack() 發出的程式輔助呼叫現可包含額外的 saveState 參數。

我們更新了 Navigation Compose 中 composable 目的地所用的 ComposeNavigator，以及包含 Fragment 的 Navigation 中 <fragment> 目的地所用的 FragmentNavigator 和 DynamicFragmentNavigator，以便使用新的 Navigator API，並支援儲存及還原狀態的功能。

導覽路徑

「路徑」為識別目的地的唯一 String。雖然這個概念先前只在 Navigation Compose 中使用，但現在已成為核心 Navigation API 的一部分。透過 Navigation Kotlin DSL 建構圖形時，這可以做為使用整數 ID 的替代方法。(b/172823546)

以往只接受 ID 的所有 API 現在都具有接受路徑 String 的超載，包含 navigate()、popBackStack()、popUpTo() 和 getBackStackEntry()。

這對 API 產生了一些影響：

Kotlin DSL 上的 popUpTo kotlin 屬性已淘汰，請改用 popUpToId。(I59c73、b/172823546)
getStartDestination() API 已淘汰，改以 getStartDestinationId() 取代。(I0887f、b/172823546)

如果開發人員已經從舊版 Navigation Compose 升級至 Navigation Compose 2.4.0-alpha01 版本，便不再需要對擴充方法匯入以下項目，應將其移除：

import androidx.navigation.compose.navigation
import androidx.navigation.compose.createGraph
import androidx.navigation.compose.getBackStackEntry
import androidx.navigation.compose.navigate
import androidx.navigation.compose.popUpTo

KEY_ROUTE 引數已替換為 NavDestination 上的 route 屬性，可讓您直接呼叫 navBackStackEntry.destination.route。

API 變更

所有 Navigation 構件都已使用 Kotlin 重新編寫，對於採用一般項目的類別 (例如 NavType 子類別) 改善了其「是否可為空值」的屬性。過去屬於 -ktx 構件的所有 Kotlin 擴充功能都已移至各自的主要構件中。-ktx 構件會繼續發布，但不會有任何內容。(b/184292145)
NavDeepLinkBuilder 現在支援將在產生的返回堆疊中加入多個不同的目的地。(I3ee0d、b/147913689)
為 DynamicNavHostFragment 新增工廠函式。(Icd515、b/175222619)
NavBackStackEntry 的專屬 ID 現已公開，可做為公用 API 的一部分。(Ie033a)
NamedNavArgument 的 name 和 argument 欄位以及解構函式現已公開。(#174、b/181320559)
推出新的 NavBackStackEntry#provideToCompositionLocals 擴充功能，為相關的組合本機值提供 NavBackStackEntry。(#175、b/187229439)

Safe Args

Safe Args 現在會為每個 NavArgs 類別產生 fromSavedStateHandle() 方法。(#122、b/136967621)

class HomeViewModel(savedStateHandle: SavedStateHandle) : ViewModel() {
  // Create a HomeDestinationArgs class with type safe accessors for each argument
  // defined on your destination
  private val args = HomeDestinationArgs.fromSavedStateHandle(savedStateHandle)
}

更新 Safe Args 以依附於 KotlinPoet 1.8.0。(#172、b/183990444)

行為變更

Navigation 現在依附於 Lifecycle 2.3.1，且現在會將更新 NavBackStackEntry Lifecycle 的 setGraph()、popBackStack()、navigateUp() 和 navigate() 方法標示為 @MainThread，讓 Navigation 與 Lifecycle 2.3.0 中引入的主要執行緒強制執行功能保持一致。(b/171125856)
現在剖析深層連結中的 Enum 引數時不會區分大小寫，可讓 http://www.example.com/red 這類深層連結成功比對 www.example.com/{color} 深層連結，即使 Enum 的值為 RED 也沒問題。(#152、b/135857840)

Compose 相容性

androidx.navigation:navigation-compose:2.4.0-alpha01 只與 Compose 1.0.0-beta07 以上版本相容，

修正錯誤

修正問題：結尾的預留位置優先於含有完全比對後置字串的深層連結。(#153、b/184072811)
NavHostFragment 現在支援使用相同 @Navigator.Name("dialog") 做為預設 DialogFragmentNavigator 的自訂導覽器。(Ib1c2c、b/175979140)
改善 NavigatorProvider#addNavigator 的行為，確保透過同一執行個體重複呼叫時不會造成問題。(#176、b/187443146)

外部貢獻

感謝 simonschiller 的協助，提供建構 Safe Args 的支援，為每個 NavArgs 類別產生 fromSavedStateHandle() 方法。(#122、b/136967621)
感謝 Bradleycorn 的協助，讓系統剖析深層連結的 Enum 引數時不區分大小寫。(#152、b/135857840)
藉助 osipxd 修正問題，即後端引數預留位置優先於含有完全相符後置字串的深層連結。(#153、b/184072811)
感謝 tatocaster 協助更新 Safe Args，讓 Safe Args 依附於 KotlinPoet 1.8.0。(#172、b/183990444)
感謝 jossiwolf 的協助，公開 NamedNavArgument 的 name 和 argument 欄位以及銷毀函式。(#174、b/181320559)
感謝 jossiwolf 的協助，推出新的 NavBackStackEntry#provideToCompositionLocals 擴充功能，為相關組合本機值提供 NavBackStackEntry。(#175、b/187229439)
感謝 jossiwolf 的協助，改善 NavigatorProvider#addNavigator 的行為，確保透過同一執行個體重複呼叫時不會造成問題。(#176、b/187443146)

Navigation Compose 1.0.0 版本

1.0.0-alpha10 版本

2021 年 4 月 7 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha10。1.0.0-alpha10 版包含此連結所列的修訂項目。

API 變更

NavHost 現在接受 Modifier，可向下傳遞至會納入目的地可組合項的可組合項容器。(I85aca、b/175125483)

修正錯誤

即使沒有找到 OnBackPressedDispatcherOwner (例如預覽 NavHost 時)，NavHost 現在也可正常運作 (I7d8b4)
Navigation Compose 現在依附於 Navigation 2.3.5，並修正在 NavHost 目的地中使用 BackHandler 時出現的問題。(I7e63b、b/182284739)

1.0.0-alpha09 版本

2021 年 3 月 10 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha09。1.0.0-alpha09 版包含此連結所列的修訂項目。

API 變更

LocalViewModelStoreOwner.current 現在會傳回可為空值的 ViewModelStoreOwner，以便更準確地判斷目前組合中是否有可用的 ViewModelStoreOwner。如果 API 須使用 ViewModelStoreOwner (例如 viewModel() 和 NavHost)，在未設定 ViewModelStoreOwner 時仍會擲回例外狀況。(Idf39a)

修正錯誤

Navigation Compose 現在依附於 Navigation 2.3.4，其中修正了在設定圖形之後嘗試設定相同 ViewModelStore 物件的問題。(I65c24、b/177825470)

1.0.0-alpha08 版本

2021 年 2 月 24 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha08。查看 1.0.0-alpha08 版的修訂項。

新功能

NavHost 現在會在 LocalSavedStateRegistryOwner CompositionLocal 中填入該目的地的 NavBackStackEntry，確保直接儲存在 SavedStateRegistry 中的任何狀態都會隨著目的地儲存及還原。(I435d7、b/179469431)

1.0.0-alpha07 版本

2021 年 2 月 10 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha07。查看 1.0.0-alpha07 版的修訂項。

依附元件更新

Navigation Compose 現在依附於 Lifecycle ViewModel Compose 1.0.0-alpha01，可為 composable 目的地提供 viewModel() 支援。(I7a374)
NavHost 現在會使用 Activity-Compose 1.3.0-alpha01 中全新的 LocalOnBackPressedDispatcherOwner，以取得在 NavController 上設定的 OnBackPressedDispatcher。(I65b12)

1.0.0-alpha06 版本

2021 年 1 月 28 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha06。1.0.0-alpha06 版包含此連結所列的修訂項目。

API 變更

在 NavController 上新增 getBackStackEntry(route: String) 擴充功能方法，以傳回相關聯的 NavBackStackEntry。(If8931)

1.0.0-alpha05 版本

2021 年 1 月 13 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha05。查看 1.0.0-alpha05 版的修訂項。

進行相關更新，以依附於 Compose 1.0.0-alpha10。

1.0.0-alpha04 版本

2020 年 12 月 16 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha04。查看 1.0.0-alpha04 版的修訂項。

更新與 Compose 1.0.0-alpha09 的相容性。

1.0.0-alpha03 版本

2020 年 12 月 2 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha03。查看 1.0.0-alpha03 版的修訂項。

修正錯誤

修正問題：在設定變更或者程序結束並重建之後，popBackStack() 和 navigateUp() 無法正常運作。(Icea47、b/173281473)
導覽至 NavHost 中的巢狀結構圖現在可正常運作。(I0948d、b/173647694)

1.0.0-alpha02 版本

2020 年 11 月 11 日

發布 androidx.navigation:navigation-compose:1.0.0-alpha02。查看 1.0.0-alpha02 版的修訂項。

API 變更

Navigation Compose 現在支援使用 popUpTo 和 launchSingleTop 作業所需的的 NavOptions。(If96c3、b/171468994)
新增可接受路徑而非 ID 的導覽函式，讓您在 Navigation Compose DSL 中建構巢狀結構圖形。(I1661d)
在 NavHost 參數清單中，startDestination 現在位於路徑之前。(Ie620e)
現在建立圖形時，可使用路徑做為 NavHost 可組合項以外的起始目的地。(Iceb75)

1.0.0-alpha01 版本

2020 年 10 月 28 日

發布 android.navigation:navigation-compose:1.0.0-alpha01。1.0.0-alpha01 版包含此連結所列的修訂項目。

新功能

navigation-compose 構件可提供 Navigation Component 和 Jetpack Compose 之間的整合功能，並使用 @Composable 函式做為應用程式的目的地。

初始版本提供以下功能：

NavHost 可組合元件，可讓您透過 Kotlin DSL 建構導覽圖。
在目的地層級限定生命週期、ViewModel 以及記憶狀態的範圍。
自動與系統返回按鈕整合。
支援傳遞引數、將深層連結附加至目的地，以及將結果傳回至之前的目的地。
rememberNavController() 和 currentBackStackEntryAsState() 中的特定 Compose 輔助工具，可讓您提升狀態，並將 NavController 連接至 NavHost 外的可組合元件 (例如底部導覽列)。

詳情請參閱 Compose Navigation 指南。

2.3.5 版本

2021 年 4 月 7 日

發布 androidx.navigation:navigation-*:2.3.5。查看 2.3.5 版的修訂項。

新功能

使用 NavDeepLinkRequest 或 Uri 導覽時，您現在可在結果目的地中存取 Uri、動作和 MIME 類型，方法是透過 KEY_DEEP_LINK_INTENT 取得引數中的意圖，為可用於外部深層連結的函式建立鏡射。(I975c3、b/181521877)

修正錯誤

將 OnBackPressedCallbacks 新增至含有 NavBackStackEntry 的調度工具，因為在活動生命週期為 STOPPED 狀態，再變為 STARTED 狀態之後，LifecycleOwner 現在可正確攔截返回動作。(Iff94f、b/182284739)
深層連結網域剖析功能現在不區分大小寫，可確保 www.example.com 能同時正確比對 www.example.com 和 www.Example.com。請注意，查詢參數名稱仍有大小寫之分。(#144、b/153829033)
修正問題：如果目的地有多個不可為空值的預設引數，而且導覽至該目的地時只覆寫這些引數的子集，可能會發生 NullPointerException (aosp/1644827)

依附元件更新

Navigation Safe Args Gradle 外掛程式現在依附於 Kotlin Gradle 外掛程式 1.4.31。(aosp/1661058、b/181156413)

外部貢獻

感謝 bentrengrove 提出提取要求，讓深層連結剖析功能不區分大小寫。(#144、b/153829033)

2.3.4 版本

2021 年 3 月 10 日

發布 androidx.navigation:navigation-*:2.3.4。查看 2.3.4 版的修訂項。

新功能

系統現在可正確剖析做為深層連結 URI 的一部分傳送的 ReferenceType 引數。這同時支援原始整數值和以 0x 為開頭的十六進位值。(#127、b/179166693)
包含 app:argType="float" 的引數的 android:defaultValue 現在支援整數預設值，可讓您使用 android:defaultValue="0"，而無需使用 0.0。(#117、b/173766247)

修正錯誤

修正使用 Navigation 支援的動態功能時安裝進度停滯的問題。(Ib27a7、b/169636207)。
使用已完成設定的同一物件呼叫 setViewModelStore 或 setLifecycleOwner，現在不需要人工管理 (Idf491、b/177825470)。
使用 Java 時，Safe-Args 會在適當的方法中加上抑制註解。(I8fbc5、b/179463137)

外部貢獻

感謝 JvmName 提出提取要求，確保當 ReferenceType 引數做為深層連結 URI 的一部分傳送時，系統可正確剖析引數。(#127、b/179166693)
感謝 tatocaster 提出提取要求，讓內含 app:argType=”float” 的引數 defaultValue 現在能夠支援整數預設值。(#117、b/173766247)

2.3.3 版本

2021 年 1 月 27 日

發布 androidx.navigation:navigation-*:2.3.3。查看 2.3.3 版的修訂項。

修正錯誤

彈出 NavBackStackEntry 再將其 Lifecycle 移至 CREATED 狀態時，不會再異常終止 (Ie3ba3)
修正 b/171364502 引起的迴歸問題，亦即導覽至含有動畫資源值為 0 的活動時會發生 ResourceNotFoundException。(I7aedb、b/176819931)

2.3.2 版本

2020 年 12 月 2 日

發布 androidx.navigation:navigation-*:2.3.2。查看 2.3.2 版的修訂項。

修正錯誤

修正迴歸問題：在 NavigationUI 中搭配 onNavDestinationSelected 使用 <activity> 目的地時會無法導覽至 Activity。(I22e34、b/171364502)
修正問題：navigation-dynamic-features-fragment 會導致系統多次導覽至新安裝的目的地。(aosp/1486056、b/169636207)
修正問題：使用 launchSingleTop 時，預設引數不會傳送至 OnDestinationChangedListener 例項 (I2c5cb)
修正問題：導覽至巢狀結構圖時，系統不會在返回堆疊上建立新的圖形執行個體。(Ifc831)
修正問題：使用含有 popUpTo 的 navigate() 在導覽圖中移除最後一個目的地時，系統不會立即從返回堆疊中刪除及移除導覽圖本身。(I910a3)
Navigation SafeArgs 現在採用 KotlinPoet 1.7.2 版本，新增支援 Kotlin 的明確 API 模式。(I918b5)
NavHostFragment.findNavController(Fragment) 原本就會檢查 Fragment 階層和 Fragment 檢視區塊階層，現在還會檢查 DialogFragment 的根層級 DecorView。如此一來，您可以透過 FragmentScenario 和 Navigation.setViewNavController() 對使用 Navigation 的對話方塊片段進行測試。(I69e0d)

2.3.1 版本

2020 年 10 月 14 日

發布 androidx.navigation:navigation-*:2.3.1。查看 2.3.1 版的修訂項。

新功能

Navigation UI 已新增預設的 Animator 資源；建議改用這項資源，而不要使用預設動畫資源。(b/167430145)
NavOptions 現在會覆寫雜湊碼和 equals 方法。(b/161586466)
Navigation 現已在「無目的地含有 ID」的 LegalArgumentException 中加入目前目的地，以便改善開發人員偵錯體驗。(b/168311416)

修正錯誤

即使產生的引數類別名稱長度超過 100 個半型字元，Safe Args 也不會再納入回傳行。(b/168584987)

依附元件變更

navigation-ui 現在依附於 DrawerLayout 1.1.1，確保在使用 LOCK_MODE_LOCKED_CLOSED 或 LOCK_MODE_LOCKED_OPEN 的情況下 NavigationUI 也能開啟導覽匣。(b/162253907)
Safe Args 現在依附於 KotlinPoet 1.6.0。(aosp/1435911)
Safe Args 現在依附於 AGP 4.0.1。(aosp/1442337)

2.3.0 版本

2020 年 6 月 24 日

發布 androidx.navigation:navigation-*:2.3.0。查看 2.3.0 版的修訂項。

自 2.2.0 版本以來的重大異動

功能模組整合：navigation-dynamic-features-runtime 和 navigation-dynamic-features-fragment 構件可讓您導覽至功能模組中定義的目的地，並視需要自動處理功能模組的安裝作業。詳情請參閱「使用功能模組進行導覽」。
導覽測試：navigation-testing 構件會提供 TestNavHostController 來讓您設定目前的目的地，並在導覽作業完成之後驗證返回堆疊。詳情請參閱「測試導覽」。
傳回結果：您現在可透過 Navigation 返回堆疊中與每個目的地相關聯的 NavBackStackEntry 存取 SavedStateHandle，這個元件適合儲存少量應與特定返回堆疊項目相關聯的已儲存狀態。詳情請參閱「將結果傳回之前的目的地」。
對 Openable 的 NavigationUI 支援：在 NavigationUI 中使用的所有 DrawerLayout 都已替換為更一般的 Openable 介面。這個介面已新增至 CustomView 1.1.0 中，且由 DrawerLayout 1.1.0 中的 DrawerLayout 實作。
深層連結中的操作和 MIME 類型支援：除了原本可用的 app:uri 之外，深層連結也已支援 app:action 和 app:mimeType。NavController 現在支援透過新的 NavDeepLinkRequest 類別使用任何欄位組合進行導覽。詳情請參閱「使用 NavDeepLinkRequest 導覽」。

已知問題

資訊清單合併工具仍不支援深層連結動作和 MIME 類型。在提供支援之前，從資訊清單中 <nav-graph> 元素產生的任何 <intent-filter> 元素，都不會在其 <data> 元素或您的自訂 <action> 中納入 MIME 類型。您必須在資訊清單中手動新增適當的 <intent-filter>。

2.3.0-rc01 版本

2020 年 6 月 10 日

發布 androidx.navigation:navigation-*:2.3.0-rc01。查看 2.3.0-rc01 版的修訂項。

修正錯誤

修正問題：使用 singleTop 將不含引數的目的地例項替換為「包含」引數的其他例項時，會發生 NullPointerException (b/158006669)
NavController 擲回的所有 destination is unknown 例外狀況現在都會提供額外的偵錯資訊，協助判斷 NavController 的狀態 (b/157764916)

2.3.0-beta01 版本

2020 年 5 月 20 日

發布 androidx.navigation:navigation-*:2.3.0-beta01。查看 2.3.0-beta01 版的修訂項。

修正錯誤

修正 NavBackStackEntry 的 Lifecycle 在程序死亡後無法正確更新的問題。(b/155218371)
在程序終止後，現在可將還原的目的地正確傳送給呼叫 setGraph() 前就已註冊的 OnDestinationChangedListener 例項 (b/155218371)
使用 singleTop 時，NavBackStackEntry 現在可正確更新引數，並將更新後的引數傳送至所有 OnDestinationChangeListener 執行個體。(b/156545508)

依附元件更新

NavigationUI 構件現在依附於 CustomView 1.1.0-rc01 和 DrawerLayout 1.1.0-rc01。(aosp/1309696)

2.3.0-alpha06 版本

2020 年 4 月 29 日

發布 androidx.navigation:navigation-*:2.3.0-alpha06。(查看 2.3.0-alpha06 版的修訂項。)

新功能

除了先前可用的 app:uri 之外，深層連結也已進一步支援 app:action 和 app:mimeType。NavController 現在支援透過新的 NavDeepLinkRequest 類別使用任何欄位組合進行導覽。(b/136573074、b/135334841)

API 變更

大幅擴充 Kotlin DSL 對 Dynamic Navigation 目的地的支援 (b/148969800)

修正錯誤

修正問題：使用巢狀結構起始目的地時，系統會忽略深層連結意圖。(b/154532067)

2.3.0-alpha05 版本

2020 年 4 月 15 日

發布 androidx.navigation:navigation-*:2.3.0-alpha05。查看 2.3.0-alpha05 版的修訂項。

新功能

對於使用 <include-dynamic> 的內含動態圖形，您不再需要指定 app:graphPackage，只要在 applicationId 結尾依序加上點和 moduleName 後置字串，即可使用預設值。如果您需要自訂 graphPackage，系統現在也支援 ${applicationId} 預留位置。(b/152696768)
Navigation Graph Kotlin DSL 現在公開提供 defaultArguments Map，可讓您在 Navigation XML 檔案中設定 <action> 元素的預設值，並為這項功能建立鏡射。(b/150345605)

修正錯誤

自 Navigation 2.2.2 起：修正在 Activity 含有多個 NavHostFragment 例項時，透過深層連結前往圖形起始目的地時會出現的 IllegalStateException 問題 (b/147378752)

依附元件更新

Navigation 現在依附於 Fragment 1.2.4。(aosp/1277325)
Dynamic Navigation 現在依附於 Play Core 1.7.2。(aosp/1282257)

2.3.0-alpha04 版本

2020 年 3 月 18 日

發布 androidx.navigation:navigation-*:2.3.0-alpha04。查看 2.3.0-alpha04 版的修訂項。

新功能

在 Navigation Kotlin DSL 中新增對功能模組活動和片段目的地的支援。(b/148969800)

API 變更

DynamicExtras 類別不再使用建構工具模式，現在可直接進行建構。(aosp/1253671)
DynamicActivityNavigator 現可在其建構函式中使用 Context (而不是 Activity)。(aosp/1250252)

修正錯誤

NavigationUI 不會再忽略空白標籤 (亦即含有 android:label=”” 的目的地)，且現在會將標題正確設為空字串。(b/148679860)

依附元件更新

Navigation 動態功能構件現在依附於 Play Core 1.6.5。(b/149556401)

2.3.0-alpha03 版本

2020 年 3 月 4 日

發布 androidx.navigation:navigation-*:2.3.0-alpha03。查看 2.3.0-alpha03 版的修訂項。

API 變更

現在，AppBarConfiguration 不再需要使用 DrawerLayout 具體類別，改用 CustomView 1.1.0-alpha02 中引入的 Openable 介面 (自 DrawerLayout 1.1.0-alpha04 起由 DrawerLayout 進行實作)，可讓您將 Openable 自訂實作項目與 NavigationUI 搭配使用。(b/129030452)

修正錯誤

navigation-common-ktx ProGuard 規則現在只會正確保留已使用的 NavArgs 類別，而非所有的 NavArgs 執行個體。(b/150213558)

依附元件變更

Navigation 已還原對 1.2.0 的依附性，並且現在依附於 1.1.0，以避免當 Navigation 不依附於 Core 1.2.0 中的任何新 API 時，強制開發人員改用更高版本的依附元件。

2.3.0-alpha02 版本

2020 年 2 月 19 日

發布 androidx.navigation:navigation-*:2.3.0-alpha02。查看 2.3.0-alpha02 版的修訂項。

新功能

您現在可透過 NavBackStackEntry 存取 SavedStateHandle，這個元件適合儲存少量應與特定返回堆疊項目相關聯的已儲存狀態。如需用途範例，請參閱「傳回結果」。(b/79672220)

API 變更

新增 getCurrentBackStackEntry() 和 getPreviousBackStackEntry() 的簡易方法，以便輕鬆擷取目前和先前目的地的 NavBackStackEntry。(b/79672220)

修正錯誤

在自己的工作堆疊中啟動應用程式時，navigateUp() 現在會將目前目的地的引數和 KEY_DEEP_LINK_INTENT 傳遞至之前的目的地。(b/147456890)

依附元件變更

Navigation 現在依附於 Core 1.2.0。

2.3.0-alpha01 版本

2020 年 2 月 5 日

發布 androidx.navigation:navigation-*:2.3.0-alpha01。查看 2.3.0-alpha01 版的修訂項。

新功能

新的 navigation-testing 構件會提供 TestNavHostController 類別。這個類別可做為測試 Navigation 時使用模擬 NavController 的替代方法，以便您設定目前目的地，並在導覽作業完成後驗證返回堆疊。(b/140884273)
新的 navigation-dynamic-features-fragment (及其傳遞依附元件 navigation-dynamic-features-runtime) 可讓您從功能模組加入目的地或整個導覽圖 (透過 <include-dynamic>)，以便在導覽至這些目的地時可視需求無縫安裝功能模組。詳情請參閱「使用功能模組進行導覽」。(b/132170186)

修正錯誤

自 Navigation 2.2.1 起：不含查詢參數的深層連結現在可正確忽略任何查詢參數，而不會將其附加在 {argument} 元素結尾，或不與深層連結比對。(b/147447512)
自 Navigation 2.2.1 起：更新 DrawerArrowDrawable 的 navigation-ui ProGuard 規則，確保不需使用 android.enableJetifier=true (b/147610424)
從 Navigation 2.2.1 起：navigation-common-ktx 模組現在擁有專屬的資訊清單套件名稱，不再和 navigation-runtime-ktx 共用相同的資訊清單套件名稱。(aosp/1141947)

依附元件更新

自 Navigation 2.2.1 起：Navigation 2.2.1 現在依附於 Lifecycle ViewModel SavedState 2.2.0 和 Fragment 1.2.1。

2.2.2 版本

2020 年 4 月 15 日

發布 androidx.navigation:navigation-*:2.2.2。查看 2.2.2 版的修訂項。

修正錯誤

修正問題：在 Activity 含有多個 NavHostFragment 例項時，透過深層連結前往圖形起始目的地時會出現 IllegalStateException (b/147378752)
NavigationUI 不會再忽略空白標籤 (亦即含有 android:label=”” 的目的地)，且現在會將標題正確設為空字串。這項功能先前已在 Navigation 2.3.0-alpha04 中發布。(b/148679860)
navigation-common-ktx ProGuard 規則現在只會正確保留已使用的 NavArgs 類別，而非所有的 NavArgs 例項。這項功能先前已在 Navigation 2.3.0-alpha03 中發布。(b/150213558)

依附元件更新

Navigation 現在依附於 Fragment 1.2.4。(aosp/1277325)

2.2.1 版本

2020 年 2 月 5 日

發布 androidx.navigation:navigation-*:2.2.1。查看 2.2.1 版的修訂項。

修正錯誤

不含查詢參數的深層連結現在可正確忽略任何查詢參數，而不會將其附加在 {argument} 元素結尾，或不與深層連結比對。(b/147447512)
已更新 DrawerArrowDrawable 的 navigation-ui ProGuard 規則，確保不需要 android.enableJetifier=true。(b/147610424)
navigation-common-ktx 模組現在擁有專屬的資訊清單套件名稱，不再與 navigation-runtime-ktx 共用相同的資訊清單套件名稱。(aosp/1141947)

依附元件更新

Navigation 2.2.1 現在依附於 Lifecycle ViewModel SavedState 2.2.0 和 Fragment 1.2.1。

2.2.0 版本

2020 年 1 月 22 日

發布了 androidx.navigation:navigation-*:2.2.0。查看 2.2.0 版的修訂項。

2.1.0 版之後的重要異動

NavBackStackEntry：您現在可以呼叫 NavController.getBackStackEntry()，傳入返回堆疊上特定目的地或導覽圖的 ID。傳回的 NavBackStackEntry 除了提供用來啟動該目的地的引數，還會提供以 Navigation 為基礎的 LifecycleOwner、ViewModelStoreOwner (與 NavController.getViewModelStoreOwner() 傳回的值相同) 以及 SavedStateRegistryOwner。
整合 Lifecycle ViewModel SavedState：將 by navGraphViewModels() 或 ViewModelProvider 建構函式與由 NavController.getBackStackEntry() 或 NavController.getViewModelStoreOwner() 傳回的 ViewModelStoreOwner 搭配使用時，系統現在會將 SavedStateViewModelFactory 做為預設的工廠函式。
支援深層連結的查詢參數：包含查詢參數的深層連結現在支援重新排序的查詢參數；比對深層連結時，現在可選用包含預設值或可為空值的引數。
改善動畫支援：NavHostFragment 現在會使用 Fragment 1.2.0 的 FragmentContainerView，修正動畫 Z 排序以及視窗插邊會分派給 Fragment 的問題。

2.2.0-rc04 版本

2019 年 12 月 18 日

發布 androidx.navigation:navigation-*:2.2.0-rc04。查看 2.2.0-rc04 版的修訂項。

修正錯誤

調整 navigation-ui 所使用的預設淡出動畫效果，以符合 Fragment 1.2.0-rc04 中經過調整的淡出動畫效果。(b/145769814)

2.2.0-rc03 版本

2019 年 12 月 4 日

發布了 androidx.navigation:navigation-*:2.2.0-rc03。查看 2.2.0-rc03 版的修訂項。

修正錯誤

修正深層連結剖析問題：使用查詢參數和引數做為路徑的最後一部分時，會導致最終路徑引數的多個字元無法剖析。(b/144554689)
修正深層連結剖析問題：選用的參數會接收到 "@null"，而不是 null (b/141613546)
與 FragmentContainerView 搭配使用時，NavHostFragment 現在可在變更設定後正確還原圖形 (b/143752103)

依附元件變更

Navigation 現在會視情況依附於 Lifecycle 2.2.0-rc03、Lifecycle ViewModel SavedState 1.0.0-rc03、Activity 1.1.0-rc03 以及 Fragment 1.2.0-rc03。

2.2.0-rc02 版本

2019 年 11 月 7 日

發布了 androidx.navigation:navigation-*:2.2.0-rc02。2.2.0-rc02 版包含此連結所列的修訂項目。

依附元件變更

Navigation 現在依附於 androidx.lifecycle 2.2.0-rc02。

2.2.0-rc01 版本

2019 年 10 月 23 日

發布 androidx.navigation:navigation-*:2.2.0-rc01，且自 2.2.0-beta01 版以來皆無異動。查看 2.2.0-rc01 版的修訂項。

2.2.0-beta01 版本

2019 年 10 月 9 日

發布了 androidx.navigation:navigation-*:2.2.0-beta01。2.2.0-beta01 版包含此連結所列的修訂項目。

新功能

NavDestination 及其子類別現在會覆寫 toString()，以便在偵錯時提供更多實用資訊。(b/141264986)

行為變更

比對深層連結時，系統現在會忽略額外的查詢參數，而不會導致比對失敗。(b/141482822)

修正錯誤

修正問題：如果同時指定了查詢參數，系統會忽略深層連結路徑中的引數。(b/141505755)
即時沒有額外項目，Activity 上的 navArgs() Kotlin 擴充功能現在也會提供更明確的錯誤訊息 (b/141408999)
Safe Args 產生的 Directions Java 類別現在包含預設值。(b/141099045)
Safe Args 產生的 Args Java 類別現在包含預設值。(b/140123727)
使用 Toolbar 時，如果在兩個頂層目的地之間移動，NavigationUI 不會再顯示文字變更的動畫效果。(b/140848160)

2.2.0-alpha03 版本

2019 年 9 月 18 日

發布 androidx.navigation:navigation-*:2.2.0-alpha03。查看 2.2.0-alpha03 版的修訂項。

行為變更

在呼叫 setGraph 之後，呼叫 setViewModelStore() 會導致 IllegalStateException。這個項目應一律在初始設定中透過 NavHost 設定，以確保所有 NavBackStackEntry 執行個體都具有一致的儲存空間供 ViewModel 執行個體使用。(aosp/1111821)

修正錯誤

修正問題：使用 ViewModel 例項時，如果該例項已附加到多個不同導覽圖限定範圍內的 ViewModelStore 例項，會導致 ConcurrentModificationException (aosp/1112257)

2.2.0-alpha02 版本

2019 年 9 月 5 日

發布了 androidx.navigation:navigation-*:2.2.0-alpha02。您可以前往這裡查看這個版本包含的修訂項目。

新功能

包含查詢參數的深層連結現在支援重新排序的查詢參數；比對深層連結時，現在可選用包含預設值或可為空值的引數。(b/133273839)
您現在可以呼叫 NavController.getBackStackEntry()，傳入返回堆疊上的目的地或導覽圖的 ID。傳回的 NavBackStackEntry 除了提供用來啟動該目的地的引數，還會提供以 Navigation 為基礎的 LifecycleOwner、ViewModelStoreOwner (與 NavController.getViewModelStoreOwner() 傳回的值相同) 以及 SavedStateRegistryOwner。(aosp/1101691\aosp/1101710)

修正錯誤

修正問題：將 NavHostFragment 新增至 ViewPager2 時會發生失敗並出現 IllegalArgumentException。(b/133640271)
NavInflater 現可避免不必要的 getResourceName() 呼叫，讓加載時間最多加快 40%。(b/139213740)

2.2.0-alpha01 版本

2019 年 8 月 7 日

發布了 androidx.navigation:navigation-*:2.2.0-alpha01。您可以前往這裡查看這個版本包含的修訂項目。

新功能

將 by navGraphViewModels() 或 ViewModelProvider 建構函式與由 NavController.getViewModelStoreOwner() 傳回的 ViewModelStoreOwner 搭配使用時，現在的預設工廠函式為 SavedStateViewModelFactory (b/135716331)

API 變更

自 Navigation 2.1.0-rc01 起：針對 2.1.0-alpha02 中引入的 NavController，移除其中已淘汰的 getViewModelStore() API。(aosp/1091021)

修正錯誤

NavHostFragment 現在使用 FragmentContainerView，修正了動畫 Z 排序問題以及視窗插邊會派給 Fragment 的問題。(b/137310379)

2.1.0 版本

2019 年 9 月 5 日

發布了 androidx.navigation:navigation-*:2.1.0。您可以前往這裡查看這個版本包含的修訂項目。

自 2.0.0 版以來的重要異動

將 ViewModel 範圍限定為導覽圖：您現在可透過 by navGraphViewModels() 屬性委派 (適用於使用 -ktx 程式庫的 Kotlin 使用者) 或加到 NavController 的 getViewModelStoreOwner() API，建立範圍限定在導覽圖層級的 ViewModel。詳情請參閱「在目的地之間共用 UI 相關資料」。
對話方塊目的地：您現在可以建立 <dialog> 目的地，系統會在您 navigate 至這些目的地時顯示 DialogFragment。NavHostFragment 預設支援對話方塊目的地。詳情請參閱「透過 DialogFragment 建立目的地」。
使用 Uri 導覽：現在可以使用 Uri 的 navigate，以使用新增至目的地的 <deepLink> 進行導覽。詳情請參閱「使用 URI 進行導覽」。
NavHostController：專門用於建構自訂 NavHost 的 API 已移至 NavHostController，以便您進行實作，將其 NavController 連結至代管的 LifecycleOwner、OnBackPressedDispatcher 和 ViewModelStore。

2.1.0-rc01 版本

2019 年 8 月 7 日

發布了 androidx.navigation:navigation-*:2.1.0-rc01。您可以前往這裡查看這個版本包含的修訂項目。

API 變更

已移除 2.1.0-alpha02 中引入的 NavController 的已淘汰 getViewModelStore() API。(aosp/1091021)

2.1.0-beta02 版本

2019 年 7 月 19 日

發布 androidx.navigation:*:2.1.0-beta02。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

移除 2.1.0-beta01 中意外引入的 jacoco 依附元件。(b/137782950)

2.1.0-beta01 版本

2019 年 7 月 17 日

發布 androidx.navigation:*:2.1.0-beta01。您可以前往這裡查看這個版本包含的修訂項目。

新功能

將 setupWithNavController() 與 Toolbar 或 CollapsingToolbarLayout 搭配使用時，NavigationUI 現在可顯示移除向上按鈕的動畫 (b/131403621)

修正錯誤

修正透過 findNavController() 使用包含相同容器的多個 NavHostFragment 時會發生的計時問題 (b/136021571)

2.1.0-alpha06 版本

2019 年 7 月 2 日

發布 androidx.navigation:*:2.1.0-alpha06。您可以前往這裡查看這個版本包含的修訂項目。

新功能

NavHostFragment 使用的 app:navGraph 屬性現已移至 navigation-runtime 構件。可透過 XML 新增的自訂導覽器應使用這個屬性，藉此與導覽編輯器的主機面板整合。(b/133880955)

API 變更

NavController 上的 getViewModelStore() API 已淘汰，並改用會傳回 ViewModelStoreOwner 的新 getViewModelStoreOwner() 方法。(aosp/987010)
將浮動視窗目的地 (例如 <dialog> 目的地) 的實作一般化為標記介面 FloatingWindow，因此現在可以實作所有的 <dialog> 目的地。用於與頂部應用程式列互動的 NavigationUI 方法現在會忽略 FloatingWindow 目的地。(b/133600763)

行為變更

使用 <dialog> 目的地時，Navigation 現可正確讓其狀態與螢幕顯示內容保持同步。因此，當導覽至非對話方塊及非活動目的地時，例如 <fragment> 目的地，Navigation 會自動彈出 <dialog> 目的地。(b/134089818)

修正錯誤

如果在處理深層連結時重新建立活動，Navigation 現在會抑制動畫效果，藉此修正影像閃爍問題。(b/130362979)
修正錯誤：如果在新增初始片段時彈出 Fragment，Navigation 返回堆疊會無法同步 (b/133832218)

2.1.0-alpha05 版本

2019 年 6 月 5 日

發布 androidx.navigation:*:2.1.0-alpha05。您可以前往這裡查看這個版本包含的修訂項目。

API 變更

NavController 上的主機相關 API 已重新命名，並移至 NavController 的新子類別 NavHostController。(aosp/966091)
NavController setHostOnBackPressedDispatcherOwner() 方法已替換為 NavHostController 的 setOnBackPressedDispatcher() 方法，現在，您必須先呼叫 setLifecycleOwner() 才能呼叫此方法。(aosp/965409)
NavHostController 現在包含 enableOnBackPressed(boolean) 方法，取代先前由 setHostOnBackPressedDispatcherOwner() 傳回的 NavHostOnBackPressedManager 類別。(aosp/966091)

修正錯誤

修正在透過 URI 導覽後返回堆疊不正確的問題。(b/132509387)
NavController 自動處理的深層連結現在只會觸發一次。(b/132754763)

2.1.0-alpha04 版本

2019 年 5 月 16 日

發布 androidx.navigation:*:2.1.0-alpha04。您可以前往這裡查看這個版本包含的修訂項目。

修正錯誤

攔截系統返回按鈕事件時，NavHostFragment 可正確遵守 app:defaultNavHost，進而修正 Navigation 2.1.0-alpha03 中的迴歸問題。b/132077777
DialogFragmentNavigator 現在可正確處理 popBackStack() 和 navigateUp() 作業。b/132576764
修正在不同巢狀結構圖之間重複導覽時發生的 IllegalStateException: unknown destination during restore 問題。b/131733658

2.1.0-alpha03 版本

2019 年 5 月 7 日

發布了 androidx.navigation:*:2.1.0-alpha03。您可以前往這裡查看這個版本包含的修訂項目。

已知問題

即使使用 app:defaultNavHost="false"，NavHostFragment 仍會繼續攔截系統返回按鈕。b/132077777

新功能

您現在可以建立 <dialog> 目的地，以便系統在您 navigate 至這些目的地時顯示 DialogFragment。NavHostFragment 預設支援對話方塊目的地。b/80267254
除了使用資源 ID 或 NavDirections 執行個體呼叫 navigate 之外，您現在也可使用 Uri 進行導覽，透過加到目的地的 <deepLink> 導覽至正確的目的地。b/110412864

行為變更

NavigationUI 提供的預設動畫效果已經從 400 毫秒加快到 220 毫秒，以便與活動和片段的預設動畫速度相符。b/130055522

API 變更

NavHostFragment 的 createFragmentNavigator() 方法已淘汰，其功能也已移至新的 onCreateNavController() 方法，以便您清楚瞭解這是建立子類別 NavHostFragment 時新增自訂導覽器的正確進入點。b/122802849
hasDeepLink() 方法已新增至 NavDestination，可讓您檢查處理特定 Uri 是否可由該目的地處理；或在有 NavGraph 的情況下，是否可由導覽圖的中的任何目的地處理。b/117437718

修正錯誤

預設引數現在可正確傳遞至 OnDestinationChangedListener 執行個體。b/130630686
NavHostFragment 現在會透過 OnBackPressedDispatcher 攔截系統返回事件，修正了返回 Fragment 時在 Fragment 生命週期方法中進行條件式導覽時會發生的問題。b/111598096
針對 Safe Args，現在可將未指定 app:argType 的 android:defaultValue=”@null” 正確推論為 string 引數。b/129629192

2.1.0-alpha02 版本

2019 年 4 月 3 日

發布 androidx.navigation:*:2.1.0-alpha02。您可以前往這裡查看這個版本包含的修訂項目。

新功能

您現在可透過適用於 Kotlin 使用者的 by navGraphViewModels() 屬性委派項目或加到 NavController 的 getViewModelStore() API，建立範圍限定在導覽圖層級的 ViewModel。b/111614463

API 變更

您現在可將 app:targetPackage 新增至 <activity> 目的地，以限制比對的套件名稱。支援 app:targetPackage="${applicationId}"，限制套件只能採用您自己的應用程式 ID。b/110975456

修正錯誤

<activity> 目的地的 android:name 將不再於加載時剖析為類別，從而在使用動態功能時可防止 ClassNotFoundExceptions。b/124538597

2.1.0-alpha01 版本

2019 年 3 月 19 日

這是 Navigation 2.1.0 的第一個 Alpha 版本。

依附元件變更

Navigation 現在依附於 androidx.core:core:1.0.1 和 androidx.fragment:fragment:1.1.0-alpha05。這個版本也會移除 androidx.legacy:legacy-support-core-utils:1.0.0 上的依附元件。b/128632612

API 變更

新增 Navigation.createNavigateOnClickListener(NavDirections) 方法，用於取代使用資源 ID 和 Bundle 建立點擊事件監聽器的做法。b/127631752
FragmentNavigator.instantiateFragment 目前已淘汰。預設實作現在會使用 FragmentFactory 對 Fragment 執行個體化。b/119054429

修正錯誤

如果目的地已附加引數，Navigation 不會再傳送空值的 Bundle，修正了使用 android:defaultValue="@null" 時會發生的問題。b/128531879
Safe Args 現在依附於 KotlinPoet 1.1.0，修正了套件名稱過長的問題。b/123654948

2.0.0 版本

2019 年 3 月 14 日

發布 Navigation 2.0.0，且自 2.0.0-rc02 版本以來沒有異動。

2.0.0-rc02 版本

2019 年 3 月 6 日

Navigation 2.0.0-rc02 提供具有 androidx.navigation 群組 ID 的新構件，並將其依附元件變更為 AndroidX 對應項目。

2.0.0-rc02 的行為與 Navigation 1.0.0-rc02 的行為相同，除了更新依附元件來比對新的依附元件外，從 1.0.0-rc02 更新時也不需要對程式碼進行任何變更。

您的專案必須遷移至 AndroidX，才能使用 Navigation 的 2.X 版本。Navigation 1.0 穩定版是採用支援資料庫依附元件的最後一個版本；1.0 之後的所有開發作業都將以 AndroidX 為基礎，並以 2.0 穩定版為基礎進行建構。

Pre-AndroidX 依附元件

使用 AndroidX 之前的 Navigation 版本時，請納入以下依附元件：

dependencies {
    def nav_version = "1.0.0"

    implementation "android.arch.navigation:navigation-fragment:$nav_version" // For Kotlin use navigation-fragment-ktx
    implementation "android.arch.navigation:navigation-ui:$nav_version" // For Kotlin use navigation-ui-ktx
}

針對 Safe Args，請在「頂層」build.gradle 檔案中新增以下「類別路徑」：

buildscript {
    repositories {
        google()
    }
    dependencies {
        classpath "android.arch.navigation:navigation-safe-args-gradle-plugin:1.0.0"
    }
}

1.0.0 版本

2019 年 3 月 14 日

發布 Navigation 1.0.0，且自 1.0.0-rc02 版本以來沒有異動。

1.0.0-rc02 版本

2019 年 2 月 26 日

這是 Navigation 1.0.0 穩定版的第二個候選版本。這個版本包含一些錯誤修正。

修正錯誤

修正系統在根圖形沒有 ID 的情況下忽略 popBackStack() 的問題。b/126251695
在處理不含 FLAG_ACTIVITY_NEW_TASK 的深層連結後呼叫 navigateUp() 時，可正確處理導覽至應用程式工作的所需操作。b/126082008
修正 ActivityNavigator.applyPopAnimationsToPendingTransition 無法套用正確的彈出式退出動畫的問題。b/126237567
Safe Args 產生的 Kotlin 程式碼現在會在與 R 類別相關聯的套件名稱中，正確逸出 Kotlin 關鍵字 (例如 in 和 fun)。b/126020455

1.0.0-rc01 版本

2019 年 2 月 21 日

這是 Navigation 1.0.0 穩定版的候選版本。這個版本包含一個錯誤修正。

修正錯誤

修正使用 Fragment 和 singleTop 導覽作業時發生的問題。b/124294805

1.0.0-beta02 版本

2019 年 2 月 12 日

這個版本包含幾項細微改善以及重大錯誤修正。

新功能

您現在可使用 0 做為 reference 引數的 android:defaultValue。b/124248602

行為變更

深層連結的完全相符項目現在優先於含有 .* 或相符引數的深層連結。b/123969518

修正錯誤

彈出返回堆疊上的最後一個目的地時，popBackStack() 和 navigateUp 現在可正確傳回 false，修正了 1.0.0-beta01 中引入的迴歸問題。b/123933201
在還原已儲存的執行個體狀態期間，Navigation 現在可正確設定 ClassLoader，避免在 Navigator 儲存的狀態或傳送至 NavDestination 的引數中使用自訂類別時發生問題。b/123893858
從已儲存的執行個體狀態還原 Parcelable[] 引數時，Safe Args 產生的 NavArgs 類別不會再發生當機。b/123963545
Safe Args 現在可正確清除由系統產生且不必要的 Kotlin 類別。b/124120883

1.0.0-beta01 版

2019 年 2 月 4 日

這是 Navigation 的第一個 Beta 版；之後，除非出現重大問題，否則 Navigation API 將保持穩定，直到推出下一個版本。這個版本包含一些錯誤修正及行為變更。

行為變更

Navigation 現在可確保引數預設值在執行階段中及透過 Safe Args 使用時，都以相同的方式處理。因此，只有包含 app:argType="reference" 的引數可以擁有指向其他資源 (例如 @color/colorPrimary) 的預設值。剖析導覽 XML 時，如果嘗試使用不同 app:argType 的參照預設值，會導致例外狀況發生。b/123551990
Safe Args 現在依附於 Android Gradle 外掛程式 3.3.0。aosp/888413
Safe Args 現在依附於 Kotlin 1.3.20。aosp/888414

修正錯誤

現在，在 Android Gradle 外掛程式所有版本的程式庫和功能模組中，都能使用 Safe Args。b/121304903
修正迴歸問題：這個問題會導致單一 popBackStack() 作業從返回堆疊的頂端彈出目的地的所有複本，而不只是一次彈出一個目的地。b/123552990
修正問題：FragmentNavigator 狀態不會與 NavController 的狀態保持同步，且在嘗試還原返回堆疊時導致 IllegalStateException 出現。b/123803044
修正問題：將 ProGuard 與模糊處理搭配使用時，系統不會顯示 NavigationUI 處理的返回箭頭。b/123449431
Safe Args 產生的程式碼現在可正確處理使用指向靜態內部類別 (格式為 .OuterClass$InnerClass) 的 app:argType 這類操作。b/123736741
Safe Args 產生的 Java 程式碼現在可正確處理全域動作以及深層巢狀結構目的地。b/123347762

1.0.0-alpha11 版本

2019 年 1 月 23 日

這是 1.0.0-alpha10 的 Hotfix 版本，修正了 Safe Args 的問題。

修正錯誤

修正問題：Safe Args 無法匯入與全域動作相關聯的 Directions 類別。b/123307342

1.0.0-alpha10 版本

2019 年 1 月 23 日

已知問題

Safe Args 無法匯入與全域動作相關聯的 Directions 類別。b/123307342

這個版本包含破壞性的 API 變更；請參閱下方「破壞性變更」一節。

新功能

Kotlin 使用者現在可使用 by navArgs() 屬性委派，來延遲取得對 Activity 或 Fragment 中由 Safe Args 產生的 NavArgs 類別的參照。b/122603367
Safe Args 現在讓您運用 androidx.navigation.safeargs.kotlin 外掛程式來產生 Kotlin 程式碼。Kotlin 程式碼專為 Kotlin 獨有模組打造，使用的是預設引數和不可變類別，而不是仍可透過先前 androidx.navigation.safeargs 外掛程式使用的建構工具模式。b/110263087

行為變更

相符的深層連結現已調整為含有最相符引數的深層連結。b/118393029
對 NavController 呼叫 setGraph() 現在會重設返回堆疊。b/111450672
未知的深層連結不會再擲回 IllegalStateException，但會遭到忽略，進而修正巢狀結構或多個 NavHostFragment 的問題。b/121340440

破壞性變更

對 Activity 套用的彈出動畫的 NavOptions.applyPopAnimationsToPendingTransition() 方法已移至 ActivityNavigator。b/122413117
Safe Args 現在可避免為不含引數的動作複製相同的類別。在產生的 NavDirections 類別中，不含引數方法的傳回類型現在為 NavDirections。b/123233147
Safe Args 產生的 Directions 類別不再提供公開的建構函式，因此您應只與產生的靜態方法互動。b/123031660
Safe Args 產生的 NavDirections 類別不再有公開建構函式；只能在產生的 Directions 類別中透過靜態方法產生這些類別。b/122963206
NavDirections 的 getArguments() 傳回的 Bundle 現在會標示為 @NonNull，而非 @Nullable。b/123243957

修正錯誤

NavDeepLinkBuilder 現在會使用您傳入的引數來判斷唯一性，以正確處理多個指向相同目的地的 PendingIntent。b/120042732
將巢狀結構的 NavHostFragment 或其他子項 Fragment 與返回堆疊搭配使用時，NavController 現在可正確處理 popBackStack() 作業。b/122770335
NavigationUI 現在可正確設定向上按鈕的內容說明。b/120395362
Safe Args 產生的 Directions 類別現在可正確處理與目的地的動作具有相同 ID 的全域動作。b/122962504
當 equals() 傳回 true 時，Safe Args 產生的 NavDirections 類別現在會擁有相等的 hashCode() 值。b/123043662
如果您嘗試在 NavHostFragment 的 FragmentManager 中自訂 FragmentTransactions，FragmentNavigator 現在會擲回更明確的錯誤訊息。建議您一律使用 getChildFragmentManager()。b/112927148

1.0.0-alpha09 版本

2018 年 12 月 18 日

這個版本包含破壞性的 API 變更；請參閱下方「破壞性變更」一節。

我們決定不繼續開發 android.arch.navigation:navigation-testing 構件。雖然經證明這對 NavController 的內部測試有幫助，但我們強烈建議採用其他測試策略 (例如模擬 NavController 執行個體)，以驗證目前進行的 navigate() 呼叫正確無誤。2018 年 Android 開發人員高峰會的單次活動講座詳細討論了這種做法，而我們也會專門針對 Navigation 測試提供更多說明文件。

新功能

與 NavigationUI 搭配使用時，含有 menuCategory="secondary" 的 MenuItem 不會再彈出返回堆疊。b/120104424
AppBarConfiguration 現在可讓您設定備用的 OnNavigateUpListener 執行個體，於 navController.navigateUp() 傳回 false 時進行呼叫。b/79993862 b/120690961

破壞性變更

將 <argument> 與 argType="reference" 搭配使用時，Navigation 不會再剖析參照，改為提供原始資源 ID 本身。b/111736515
根據預設，onNavDestinationSelected() 現在會彈回導覽圖的起始目的地，與 setup 方法維持一致。為 MenuItem 新增 menuCategory="secondary"，以免彈出返回堆疊。aosp/852869
產生的 Args 類別的 fromBundle() 方法現在接受非空值的 Bundle，而非可為空值的 Bundle。aosp/845616

修正錯誤

引數現在可從深層連結正確剖析為正確的 argType，而非一律剖析為字串。b/110273284
Navigation 現在可正確匯出公開資源。b/121059552
Safe Args 現在與 Android Gradle 外掛程式 3.4 Canary 4 以上版本相容。b/119662045

1.0.0-alpha08 版本

2018 年 12 月 6 日

這個版本包含破壞性的 API 變更；請參閱下方「破壞性變更」一節。

新功能

目的地標籤現在搭配 NavigationUI 方法使用時，將自動使用正確的引數取代 android:label 中的 {argName} 執行個體 b/80267266
Navigation 現在依附於支援資料庫 28.0.0。b/120293333

破壞性變更

OnNavigatedListener 已重新命名為 OnDestinationChangedListener。b/118670572
OnDestinationChangedListener 現在也會傳遞引數的 Bundle。aosp/837142
移除了 app:clearTask 和 app:launchDocument 屬性及其相關方法。您可以將 app:popUpTo 與圖形根層級搭配使用，來移除返回堆疊中的所有目的地。b/119628354
ActivityNavigator.Extras 現在採用 Builder 模式，並加入可設定任何 Intent.FLAG_ACTIVITY_ 標記的功能。aosp/828140
NavController.onHandleDeepLink 已重新命名為 handleDeepLink。aosp/836063
許多不適用於設定子類別的類別和方法 (例如 NavOptions、NavInflater、NavDeepLinkBuilder 和 AppBarConfiguration) 皆已設為 final。aosp/835681
移除已淘汰的 NavHostFragment.setGraph() 方法。aosp/835684
移除已淘汰的 NavigationUI.navigateUp(DrawerLayout, NavController) 方法。aosp/835684
Fragment 建立程序已移至 FragmentNavigator，以便將 Fragment 建立程序委派給 FragmentFactory。b/119054429
NavGraphNavigator 的建構函式不再接受 Context。aosp/835340
NavigatorProvider 現已成為類別，不再是介面。getNavigatorProvider() 傳回的 NavigatorProvider 並未改變其功能。aosp/830660
已移除 NavDestination.navigate()。請改為透過 Navigator 呼叫 navigate()。aosp/830663
大幅重構 Navigator，不再需要使用 OnNavigatorNavigatedListener，而是改為讓 navigate 傳回原本的導覽目的地 NavDestination。
Navigator 執行個體無法再將彈出事件傳送至 NavController。建議您使用 OnBackPressedCallback 來攔截返回按鈕點按動作，並呼叫 navController.popBackStack()。aosp/833716

修正錯誤

當目的地為 <navigation> 元素時，popUpTo 現在會穩定運作。b/116831650
修正因使用巢狀結構圖時發生 IllegalArgumentException 而導致的數個問題。 b/118713731 b/113611083 b/113346925 b/113305559
<activity> 目的地的 dataPattern 屬性現在可為引數填入非 String 引數，方法是呼叫 toString()。b/120161365

Safe Args

Secure Args 支援可序列化物件，包括 Enum 值。Enum 類型可以使用列舉常值來設定預設值，無須使用類別名稱 (例如 app:defaultValue="READ")。b/111316353
只要是 Safe Args 支援的類型，Safe Args 皆支援其陣列 b/111487504
Safe Args 現在會忽略資源目錄的子資料夾 b/117893516
Safe Args 會視情況新增 @Override 註解。b/117145301

1.0.0-alpha07 版本

2018 年 10 月 29 日

新功能

全新的 AppBarConfiguration 類別可讓您自訂要列為「頂層」的目的地。詳情請參閱更新版說明文件。b/117333663
您現在可以將引數傳遞至圖形的起始目的地。 b/110300470
深層連結現在支援含有半形句號、連字號和加號的自訂配置。b/112806402

破壞性變更

navigation-testing-ktx 模組已收入 navigation-testing artifact，因此無法再發布。
navigation-testing 構件現在依附於 Kotlin 標準程式庫。API 經變更後更符合 Kotlin 使用慣例，但您可以繼續使用該 API 執行以 Java 編寫的測試。
不再支援中繼資料資訊清單註冊導覽圖。b/118355937
無法再將動作附加至 <activity> 目的地。aosp/785539

修正錯誤

深層連結現在可正確地剖析查詢參數。b/110057514
Activity 目的地現在可正確地套用所有進入與退出的動畫。b/117145284
修正了使用自訂 Navigator 時因設定變更而發生的異常終止問題。b/110763345

Safe Args

Safe Args 現在可以固定依附於 Android Gradle 外掛程式 3.2.1。b/113167627
現在可以為內部類別產生 Directions。b/117407555
修正無法順利產生 Directions 並加到 <include> 導覽圖的問題。b/116542123

1.0.0-alpha06 版本

2018 年 9 月 20 日

新功能

現在支援 Fragment 和 Activity 目的地的共用元素轉換 b/79665225。詳情請參閱「使用導覽架構元件實作導覽功能」。
現在如果選取 NavigationView 中的某個項目，其所屬的所有底部功能表都會關閉 b/112158843

API 變更

破壞性變更：Navigator navigate() 方法現在接受 Navigator.Extras 參數。
NavController 的 getGraph() 方法現在為 NonNull。b/112243286

修正錯誤

NavigationUI.setupWithNavController() 與個別目的地的檢視搭配使用時，不會再洩露檢視內容 b/111961977
系統現在只會呼叫 Navigator onSaveState() 一次 b/112627079

Safe Args

導覽目的地的 Directions 類別現在會擴充其父項 Directions 類別 (如果有的話)。b/79871405
Directions 和 Args 類別現在具備實用的 toString() 實作。b/111843389

1.0.0-alpha05 版本

2018 年 8 月 10 日

修正錯誤

修正導致返回堆疊行為不正確的錯誤。b/111907708
修正所產生的 Args 類別在 equals() 中的錯誤。b/111450897
修正 Safe Args 中的建構失敗問題。B/109409713
修正將資源 ID 轉換成 Java 名稱時發生的問題。b/111602491
修正 Safe Args 外掛程式中針對是否可為空值顯示的錯誤訊息。
新增原本遺漏的是否可為空值註解。

1.0.0-alpha04 版本

2018 年 7 月 19 日

Navigation 1.0.0-alpha04 和相關聯的 Safe Args Gradle 外掛程式包含多項 API 變更、行為變更和錯誤修正。

API/行為變更

NavHostFragment 一律會將目前的 Fragment 設為主要導覽片段，以確保先彈出子項片段管理員，再彈出外部的 NavController。b/111345778

Safe Args

破壞性變更：app:type 已變更為 app:argType，以免與 ConstraintLayout 2.0.0-alpha1 等其他程式庫發生衝突。b/111110548
Safe Args 顯示的錯誤訊息現在可供點選。b/111534438
Args 類別現在會確認 NonNull 屬性實際並非空值 b/111451769
為 NavDirections 和 Args 所產生的類別新增 NonNull 註解。b/111455455 b/111455456

修正錯誤

修正透過深層連結前往片段目的地後發生的系統返回按鈕問題。b/111515685

1.0.0-alpha03 版本

2018 年 7 月 12 日

Navigation 1.0.0-alpha03 和相關聯的 Safe Args Gradle 外掛程式包含多項 API 變更、行為變更和錯誤修正。

API/行為變更

新增了工具列適用的 NavigationUI.setupWithNavController 方法 b/109868820
新增了 CollapsingToolbarLayout 適用的 NavigationUI.setupWithNavController 方法 b/110887183
現在，如果返回堆疊為空白或指定目的地 ID 不在返回堆疊中，popBackStack() 會傳回 false。b/110893637
現在，FragmentNavigator 在 FragmentManager 儲存狀態後會忽略導覽作業，以避免「無法在 onSaveInstanceState 之後執行這項動作」例外狀況 b/110987825

Safe Args

破壞性變更：如果動作和引數名稱包含非英數字元，在各自的 NavDirections 方法名稱中將改用駝峰式大小寫
- 例如：DemoController.index 會變成 setDemoControllerIndex b/79995048
- 例如：action_show_settings 會變成 actionShowSettings b/79642240
破壞性變更：現在系統預設會將引數視為非空值。想讓字串和可剖析引數使用空值，請新增 app:nullable="true" b/79642307
您現在能夠以「123L」的格式將 app:type="long" 與 defaultValue 搭配使用。b/79563966
現在支援可剖析引數，只要在 app:type 使用完整的類別名稱即可。唯一支援的預設值為 "@null" b/79563966
Args 類別現在會導入 equals() 和 hashCode() b/79642246
Safe Args 外掛程式現在可套用至程式庫專案。b/80036553
Safe Args 外掛程式現在可套用至功能專案。b/110011752

修正錯誤

修正在 Fragment 生命週期方法執行期間進行導覽時發生的問題。b/109916080
修正在透過巢狀結構圖多次進行導覽時發生的問題 b/110178671
修正在搭配使用 setPopUpTo 與圖形中第一個目的地時發生的問題。/b/109909461
修正所有 app:defaultValue 值都是以 String 形式傳遞的問題。b/110710788
Android Gradle 外掛程式 3.2 Beta 01 版隨附的 aapt2 現在會為 Navigation XML 檔案中的每個 android:name 屬性新增保留規則。b/79874119
修正在取代預設 FragmentNavigator 時發生的記憶體流失問題 b/110900142

1.0.0-alpha02 版本

2018 年 6 月 7 日

行為變更

FragmentNavigator 現在採用 setReorderingAllowed(true)。b/109826220
Navigation 現在會對從深層連結網址剖析出的參數進行　URLDecode 處理。b/79982454

修正錯誤

修正了在透過 Fragment 生命週期方法呼叫 navigate 時發生的 IllegalStateException。b/79632233
為修正使用動畫時的閃爍問題，Navigation 現在依附於支援資料庫 27.1.1。b/80160903
修正在使用 defaultNavHost="true" 做為子項片段時發生的 IllegalArgumentException。b/79656847
修正了在使用 NavDeepLinkBuilder 時發生的 StackOverflowError。b/109653065
修正在導覽回巢狀結構圖時發生的 IllegalArgumentException。b/80453447
修正使用 launchSingleTop 時的 Fragment 重疊問題。b/79407969
Navigation 現在會為巢狀圖建構正確的合成返回堆疊。b/79734195
現在使用巢狀結構圖做為 MenuItem 時，NavigationUI 會醒目顯示正確的項目。b/109675998

API 變更

淘汰了動作的 clearTask 屬性和 NavOptions 中相關聯的 API。b/80338878
淘汰了動作的 launchDocument 屬性和 NavOptions 中相關聯的 API。b/109806636

1.0.0-alpha01 版本

2018 年 5 月 8 日

Navigation 提供一個架構，可用於建構應用程式內導覽功能。初始版本為 1.0.0-alpha01。