導覽

Navigation 是可在 Android 應用程式中瀏覽各個「目的地」的架構，無論目的地是以 Fragment、Activity 或其他元件實作，都能提供一致的 API。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2025 年 9 月 24 日 2.9.5 - - -

宣告依附元件

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

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

Groovy

plugins {
  // Kotlin serialization plugin for type safe routes and navigation arguments
  id 'org.jetbrains.kotlin.plugin.serialization' version '2.0.21'
}
  
dependencies {
  def nav_version = "2.9.5"

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

  // Views/Fragments Integration
  implementation "androidx.navigation:navigation-fragment:$nav_version"
  implementation "androidx.navigation:navigation-ui:$nav_version"

  // Feature module support for Fragments
  implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version"

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

  // JSON serialization library, works with the Kotlin serialization plugin.
  implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3"
}

Kotlin

plugins {
  // Kotlin serialization plugin for type safe routes and navigation arguments
  kotlin("plugin.serialization") version "2.0.21"
}

dependencies {
  val nav_version = "2.9.5"

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

  // Views/Fragments integration
  implementation("androidx.navigation:navigation-fragment:$nav_version")
  implementation("androidx.navigation:navigation-ui:$nav_version")

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

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

  // JSON serialization library, works with the Kotlin serialization plugin
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
}

Safe Args

如需将 Safe Args 添加到您的项目，请在顶层 build.gradle 文件中包含以下 classpath：

Groovy

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

Kotlin

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.9.5"
        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.9 版

2.9.5 版

2025 年 9 月 24 日

發布 androidx.navigation:navigation-*:2.9.5。2.9.5 版包含這些修訂項目。

修正錯誤

  • Navigation Safe Args 現在可以處理 AGP 9.0 內建 Kotlin 的支援功能。(I1d9d76)

依附元件更新

  • Navigation Safe Args 外掛程式現在依附於 Android Gradle 外掛程式 8.4.2 版。(b/431847270、I5932a)

2.9.4 版

2025 年 9 月 10 日

發布 androidx.navigation:navigation-*:2.9.4。2.9.4 版包含這些修訂項目。

修正錯誤

  • 在 NavHost 轉換中停用處理常式後，如果系統在影格中途傳送預測返回事件，可避免應用程式當機。(I5667c、b/384186542)

2.9.3 版

2025 年 7 月 30 日

發布 androidx.navigation:navigation-*:2.9.3。2.9.3 版包含這些修訂項目。

修正錯誤

  • 修正 NavController 中的錯誤，此錯誤在您使用 OnDestinationChangedListeners 時會導致 ConcurrentModificationException。(If7406、b/417784831)
  • 修正使用 navigate(uri, navOptions,navigationExtras) 時忽略額外內容的錯誤。(I67fb7、b/430336813)

2.9.2 版

2025 年 7 月 16 日

發布 androidx.navigation:navigation-*:2.9.2。2.9.2 版包含這些修訂項目。

修正錯誤

  • 修正了項目上方的對話方塊關閉時，項目不會繼續的問題 (Idb20e、b/418746335)
  • 修正使用自訂 NavTypes 時，測試具有型別安全路徑的 SavedStateHandle 時發生的 MissingFieldException 錯誤。(I2f843、b/421002511)

2.9.1 版

2025 年 7 月 2 日

發布 androidx.navigation:navigation-*:2.9.1。2.9.1 版包含這些修訂項目。

修正錯誤

  • 修正問題：使用 single top 建立的 NavEntries 在 Lifecycle.State 中永遠不會超出 CREATED 狀態。(I043ba、b/421095236)

2.9.0 版

2025 年 5 月 7 日

發布 androidx.navigation:navigation-*:2.9.0。2.9.0 版包含這些修訂項目。

自 2.8.0 版以來的重要異動

  • Navigation Safe Args 動作現在會使用 @CheckResult 註解產生，確保動作會被使用。

SupportingPane 介面

  • 自訂 Navigator 現在可以將目的地標示為實作 SupportingPane 介面，向 NavController 指出這些目的地會與其他目的地一起顯示。使用這個介面，即可同時RESUMED多個目的地。

Compose Kotlin Multiplatform

  • Navigation 現在提供新的通用 NavController.handleDeepLink() 函式，可採用 NavDeepLinkRequest 而非 Intent。這樣一來，Android 以外的平台就能正確處理深層連結。感謝 Konstantin Tskhovrebov！
  • Navigation 現在提供 NavUri，這項新的通用剖析器函式是 Android URI 在其他平台上的相容 API。這樣就能以平台中立的方式建立 URI。感謝 Konstantin Tskhovrebov！

型別安全函式

  • 先前只能透過 reified 方法存取的類型安全 API，composable<YourScreen> 現在有非具體化版本，可直接採用 KClass 執行個體。
  • 導覽型別安全現在支援將值類別做為路徑，或做為路徑的引數型別。

2.9.0-rc01 版

2025 年 4 月 23 日

發布 androidx.navigation:navigation-*:2.9.0-rc01。2.9.0-rc01 版包含這些修訂項目。

修正錯誤

  • 從 Jetpack Navigation 移除所有非 Android 平台目標，因為這些目標實際上無法運作。現在提供不同平台的存根。(I2877d)

2.9.0-beta01 版

2025 年 4 月 9 日

發布 androidx.navigation:navigation-*:2.9.0-beta01。2.9.0-beta01 版包含這些修訂項目。

API 變更

  • parseStringAsNavUri 的通用 API 已變更為可接收字串的 NavUri 工廠函式。(I4db6e、b/403616316)

依附元件更新

  • 這個程式庫現在指定 Kotlin 2.0 語言層級，且需要 KGP 2.0.0 以上版本。(Idb6b5)

2.9.0-alpha09 版

2025 年 3 月 26 日

發布 androidx.navigation:navigation-*:2.9.0-alpha09。2.9.0-alpha09 版包含這些修訂項目。

新功能

  • navigation-testing模組現在除了 Android 之外，也支援桌機、Linux、macOS 和 iOS。(I2b770、b/398265336)
  • NavType 現在除了 Android 之外，也支援桌機、Linux、macOS 和 iOS。(I297d8)

2.9.0-alpha08 版

2025 年 3 月 12 日

發布 androidx.navigation:navigation-*:2.9.0-alpha08。2.9.0-alpha08 版包含這些修訂項目。

修正錯誤

  • 自 Navigation 2.8.9 起：修正 Navigation 2.8.8 中發現的回歸問題，該問題會導致深層連結必須與深層連結要求或意圖的所有欄位完全相符，才會視為相符。這導致含有部分欄位相符項目且沒有其他項目的深層連結無法再運作。(Ie5e36、b/399826566)

外部貢獻

  • 新的通用剖析器函式，可建立 NavUri。感謝 Konstantin Tskhovrebov！(If0a6a)

2.9.0-alpha07 版

2025 年 2 月 26 日

發布 androidx.navigation:navigation-*:2.9.0-alpha07。2.9.0-alpha07 版包含這些修訂項目。

修正錯誤

  • 修正問題：嘗試使用非包含式彈出視窗進行 saveState 時，會導致儲存的狀態為空值，可能造成還原時異常終止。(I9f3e8、b/395091644)
  • 自 Navigation 2.8.8 起：修正 NavDeepLink 比對問題，深層連結和深層連結要求必須在 URI、動作和 MIME 上完全相符。如果只有一或兩個欄位相符，系統就不會再進行比對。(I3b029、b/395712033)
  • 自 Navigation 2.8.8 起：修正了含有萬用字元路徑的路線與新增深層連結不符的錯誤 (I7ea92、b/389970341)

外部貢獻

  • 將 navigation-common、navigation-runtime 和 navigation-compose API 擷取到通用平台。感謝 Konstantin Tskhovrebov！(I1e626、Ica76f、Idf479)

已知問題

  • 為解決 b/395712033 問題，深層連結現在會錯誤地要求與深層連結要求和/或 Intent 具有所有相同的欄位。深層連結只需比對現有欄位，並忽略未納入的欄位。我們已在 b/399826566 中修正這個問題，並將在後續版本中發布。

2.9.0-alpha06 版

2025 年 2 月 12 日

發布 androidx.navigation:navigation-*:2.9.0-alpha06。2.9.0-alpha06 版包含這些修訂項目。

新功能

  • 系統現在會使用 @CheckResult 註解產生 Navigation Safe Args 動作，確保這些動作會被使用。(I14d4c、b/356323084)

修正錯誤

  • 修正 NavController 中的錯誤：當 backStack 狀態儲存至清單時，系統會嘗試將這些狀態還原至陣列，但這項作業會失敗。(Idfb9b)
  • 自 Navigation 2.8.7 起：Navigation Safe Args 現在支援可組合函式的目的地。(I35320、b/362791955)

2.9.0-alpha05 版

2025 年 1 月 29 日

發布 androidx.navigation:navigation-*:2.9.0-alpha05。2.9.0-alpha05 版包含這些修訂項目。

修正錯誤

  • 修正問題：使用 Navigation Compose 時，會導致出現非預期的縮放動畫。(I480f4、b/353294030)
  • 從「Navigation」2.8.6：系統會透過 NavType.get 剖析 XML 提供的 NavDestination 標籤，確保自訂 NavType 邏輯受到尊重。(I7ec2f、b/388100796)
  • 在 Navigation 2.8.6 中：使用 dataPattern 導覽至活動時，ActivityNavigator 現在會嘗試使用引數的 NavType 編碼 arg 值。(I16376、b/383616432)
  • 自 Navigation 2.8.5 起：修正問題，使用 Navigation Compose 並在目前動畫結束的同一影格中呼叫導覽時，會導致出現非預期的縮放動畫。(I26cb1、b/353294030)

2.9.0-alpha04 版

2024 年 12 月 11 日

發布 androidx.navigation:navigation-*:2.9.0-alpha04。2.9.0-alpha04 版包含這些修訂項目。

新功能

下表提供具體化和 KClass API。

具體化 KClass
composable<TestClass> { } composable(TestClass::class) { }
navigation<NestedGraph>(startDestination = TestClass::class) navigation(route = NestedGraph::class, startDestination = TestClass::class)
dialog<TestClass> {} dialog(TestClass::class) {}
navDeepLink<TestClass>(baseUri) navDeepLink(TestClass::class, baseUri)
NavDeepLink.Builder.setUriPattern<TestClass>(baseUri) NavDeepLink.Builder.setUriPattern(TestClass::class, baseUri)
NavDestinationBuilder.deepLink<TestDeepLink>(baseUri) { } NavDestinationBuilder.deepLink(TestDeepLink::class, baseUri) { }
navController.getBackStackEntry<TestClass>() navController.getBackStackEntry(TestClass::class)
navController.popBackStack<TestClass>(true) navController.popBackStack(TestClass::class, true)
navController.clearBackStack<TestClass>() navController.clearBackStack(TestClass::class)
NavOptions.setPopUpTo<TestClass>() NavOptions.setPopUpTo(TestClass::class)
navOptions { popUpTo<TestClass> {...} } navOptions { popUpTo(TestClass::class) {...} }
NavGraph.setStartDestination<TestClass>() NavGraph.setStartDestination(TestClass::class)
NavGraph.findNode<TestClass>() NavGraph.findNode(TestClass::class)
backStackEntry.toRoute<TestClass>() backStackEntry.toRoute(TestClass::class)
savedStateHandle.toRoute<TestClass>() savedStateHandle.toRoute(TestClass::class)

API 變更

  • Java 來源會隱藏類型安全的 Kotlin 專屬 NavGraph.setStartDestination 多載。(Ic640c、b/364634035)

修正錯誤

  • 自 Navigation 2.8.5 起：修正如果返回堆疊彈出至 1 個項目，且在同一影格中觸發系統返回，NavHost 可能會在 PredictiveBackHandler 內擲回例外狀況的問題。(I1a429、b/375343407)
  • 自 Navigation 2.8.5 起：修正更新圖表的 startDestination 時，NavDestination NullPointerException 的問題。(I99421、b/361560785)

外部貢獻

2.9.0-alpha03 版

2024 年 11 月 13 日

發布 androidx.navigation:navigation-*:2.9.0-alpha03。2.9.0-alpha03 版包含這些修訂項目。

新功能

  • 導覽型別安全現在支援將值類別做為路徑，或做為路徑的引數型別。(I9344a、b/374347483)

修正錯誤

  • 修正 ConcurrentModificationException，當附加至 NavBackStackEntry 的 LifecycleObserver 在代管 LifecycleOwner (例如包含的 Activity 或 Fragment) 變更生命週期狀態時，觸發返回堆疊變更，就可能發生此問題。(Ia9494)

2.9.0-alpha02 版

2024 年 10 月 30 日

發布 androidx.navigation:navigation-*:2.9.0-alpha02。2.9.0-alpha02 版包含這些修訂項目。

外部貢獻

  • 新的通用 NavController.handleDeepLink(request: NavDeepLinkRequest) 方法。感謝 Konstantin Tskhovrebov！(I3e228)

2.9.0-alpha01 版

2024 年 10 月 16 日

發布 androidx.navigation:navigation-*:2.9.0-alpha01。2.9.0-alpha01 版包含這些修訂項目。

新功能

  • 自訂 Navigator 現在可以將目的地標示為實作 SupportingPane 介面，向 NavController 指出這些目的地會與其他目的地一起顯示。使用這個介面，即可同時 RESUMED 多個目的地。(Id5559)
  • 自 Navigation 2.8.3 起：為 navigation-common、navigation-runtime 和 navigation-compose 模組新增 Lint 檢查，協助找出未正確使用 @Serializable 註解的任何型別安全路徑。這項檢查適用於所有 NavGraphBuilder 和 NavDeepLinkBuilder 擴充功能函式。(I4a259、I95402、Ie601a、Id8c6e、I28bda、b/362725816)
  • 自 Navigation 2.8.3 起：為 navigation-common、navigation-runtime 和 navigation-compose 模組新增 Lint 檢查，協助找出任何具有 Enum 引數且未正確使用 @Keep 註解的型別安全路徑。這項檢查適用於所有 NavGraphBuilder 和 NavDeepLinkBuilder 擴充功能函式。(I4a259、I95402、Ie601a、Id8c6e、I2b46f、b/358687142)

行為變更

  • 現在，如果嘗試使用先前已 DESTROYED 的 NavController，系統會擲回 IllegalStateException。(I520da、b/369616172)

修正錯誤

  • 更新「找不到列舉類別」例外狀況，建議在縮減建構作業中清除列舉類別時，使用 @Keep 註解。(I90e79、b/358137294)

已知問題

  • Navigation 2.8.* 中新增的 Lint 規則有問題，導致嘗試使用 Android Gradle 外掛程式 8.4 以上版本執行 Lint 時發生 Obsolete custom lint check 錯誤。(b/368070326、b/371463741)

2.8 版本

2.8.9 版

2025 年 3 月 12 日

發布 androidx.navigation:navigation-*:2.8.9。2.8.9 版包含這些修訂項目。

修正錯誤

  • 修正 Navigation 2.8.8 中發現的回歸問題，該問題會要求深層連結必須完全符合深層連結要求或意圖的所有欄位，才會視為相符。這導致含有部分欄位相符項目且沒有其他項目的深層連結無法再運作。(Ie5e36、b/399826566)

2.8.8 版

2025 年 2 月 26 日

發布 androidx.navigation:navigation-*:2.8.8。2.8.8 版包含這些修訂項目。

修正錯誤

  • 修正錯誤：含有萬用字元路徑的路徑與新增的深層連結不符。(I7ea92、b/389970341)
  • 修正 NavDeepLink 比對問題，深層連結和深層連結要求必須完全比對 URI、動作和 MIME。如果只有一或兩個欄位相符，系統就不會再進行比對。(I3227f、b/395712033)

已知問題

  • 為解決 b/395712033 問題，深層連結現在會錯誤地要求與深層連結要求和/或 Intent 具有所有相同的欄位。深層連結只需比對現有欄位，並忽略未納入的欄位。我們已在 b/399826566 中修正這個問題，並將在後續版本中發布。

2.8.7 版

2025 年 2 月 12 日

發布 androidx.navigation:navigation-*:2.8.7。2.8.7 版包含這些修訂項目。

修正錯誤

2.8.6 版

2025 年 1 月 29 日

發布 androidx.navigation:navigation-*:2.8.6。2.8.6 版包含這些修訂項目。

修正錯誤

  • 透過 XML 提供的 NavDestination 標籤會透過 NavType.get 剖析，確保系統會遵守自訂 NavType 邏輯。(Id366d、b/388100796)
  • 使用 dataPattern 導覽至活動時，ActivityNavigator 現在會嘗試使用引數的 NavType 編碼 arg 值。(I1a71d、b/383616432)

2.8.5 版

2024 年 12 月 11 日

發布 androidx.navigation:navigation-*:2.8.5。2.8.5 版包含這些修訂項目。

修正錯誤

  • 修正問題：如果返回堆疊彈出至 1 個項目，且在同一影格中觸發系統返回，NavHost 可能會在 PredictiveBackHandler 內擲回例外狀況。(I1a429、b/375343407)
  • 修正更新圖表的 startDestination 時，NavDestination NullPointerException 無法更新的問題。(I99421、b/361560785)
  • 修正問題：使用 Navigation Compose 並在目前動畫結束的同一影格中呼叫導覽時，會導致非預期的縮放動畫。(I26cb1、b/353294030)
  • 修正 ConcurrentModificationException，當附加至 NavBackStackEntry 的 LifecycleObserver 在代管 LifecycleOwner (例如包含的 Activity 或 Fragment) 變更生命週期狀態時，觸發返回堆疊變更，就可能發生此問題。(Ia9494)

外部貢獻

  • 導覽類型安全現在支援 List<Enum> 做為路徑的引數類型，不需任何自訂 NavType。感謝 Csaba Kozák！(GH-725、b/375559962)

2.8.4 版

2024 年 11 月 13 日

發布 androidx.navigation:navigation-*:2.8.4。2.8.4 版包含這些修訂項目。

新功能

修正錯誤

2.8.3 版

2024 年 10 月 16 日

發布 androidx.navigation:navigation-*:2.8.3。2.8.3 版包含這些修訂項目。

新功能

  • 為 navigation-common、navigation-runtime 和 navigation-compose 模組新增 Lint 檢查，協助找出未正確以 @Serializable 註解的任何型別安全路徑。這項檢查適用於所有 NavGraphBuilder 和 NavDeepLinkBuilder 擴充功能函式。(I4a259、I95402、Ie601a、Id8c6e、I28bda、b/362725816)
  • 為 navigation-common、navigation-runtime 和 navigation-compose 模組新增 Lint 檢查，協助找出未正確使用 @Keep 註解的 Enum 引數型別安全路徑。這項檢查適用於所有 NavGraphBuilder 和 NavDeepLinkBuilder 擴充功能函式。(I4a259、I95402、Ie601a、Id8c6e、I2b46f、b/358687142)

修正錯誤

  • 修正了在 Navigation 2.8.* 中新增的 Lint 規則，會在嘗試使用 Android Gradle 外掛程式 8.4 以上版本執行 Lint 時，導致 Obsolete custom lint check 錯誤的問題。(I1be3d、b/368070326、b/371463741)

已知問題

  • 嘗試使用 Lint 16 (AGP 8.7) 以上版本執行 Lint 時，Navigation Lint 會擲回過時的自訂 Lint 檢查錯誤。(b/371926651)

2.8.2 版

2024 年 10 月 2 日

發布 androidx.navigation:navigation-*:2.8.2。2.8.2 版包含這些修訂項目。

新功能

  • Navigation Type Safety 現在支援包含 Double、Double?、DoubleArray、DoubleArray?、List<Double> 和 List<Double>? 的 Serializable 類別，不需要任何自訂 NavType。(I570eb、Ibc4c0、I37461、I5bed4、b/359245753)

修正錯誤

  • 如果導覽功能無法將路徑的引數對應至 NavType，系統會顯示更完善的錯誤訊息，其中包含引數名稱、引數完整名稱和路徑完整名稱。(Id8416、b/346264232)

2.8.1 版

2024 年 9 月 18 日

發布 androidx.navigation:navigation-*:2.8.1。2.8.1 版包含這些修訂項目。

新功能

  • 新增 Lint 規則，確保嘗試使用型別安全 API popBackStack 時，使用的是採用具體化類別型別的 popBackStack 函式。(Ief161、b/358095343)

修正錯誤

  • 現在導覽時，傳遞至 NavGraph 的 startDestination 必須包含所有必要引數的值，包括不可為空值且沒有預設值的引數。(I18e74、b/362594265)
  • 導覽安全引數已新增對不可為空值的字串的支援，因此系統會剖析「null」值並原封不動地儲存到套件中。這與現有行為不同，現有行為會將「null」值剖析為空值物件。這項變更僅適用於不可為空值的字串型別。可為空值的字串維持不變。(I08b4a、b/348936238)
  • 除非深層連結已明確新增至目的地，否則無法再深層連結至 NavDestination。這也表示您只能使用採用字串路線的導覽函式超載，導覽至目的地的路線。修正了可深層連結至可能受保護目的地的安全漏洞。(Ie30e6)

依附元件更新

  • Navigation Safe Args 現在依附於 Kotlin 1.9.24，而非 Kotlin 2.X，確保開發人員不會被迫更新。(a4129a)
  • Navigation Compose 現在依附於 Compose 1.7.2。

2.8.0 版

2024 年 9 月 4 日

發布 androidx.navigation:navigation-*:2.8.0。2.8.0 版包含這些修訂項目。

自 2.7.0 版以來的重要異動

Navigation Kotlin DSL 類型安全

  • Navigation 現在使用 Kotlin 序列化，為 Kotlin DSL (Navigation Compose 使用) 提供類型安全，讓您透過類型安全物件和資料類別，在導覽圖中定義目的地：
    // Define a home destination that doesn't take any arguments
    @Serializable
    object Home

    // Define a profile destination that takes an ID
    @Serializable
    data class Profile(val id: String)

    // Now define your NavHost using type safe objects
    NavHost(navController, startDestination = Home) {
        composable<Home> {
            HomeScreen(onNavigateToProfile = { id ->
                navController.navigate(Profile(id))
            })
        }
        composable<Profile> { backStackEntry ->
            val profile: Profile = backStackEntry.toRoute()
            ProfileScreen(profile)
        }
    }

詳情請參閱「Navigation Compose meet Type Safety」網誌文章。

Navigation Compose 預測返回手勢

  • Navigation Compose 現在透過 compose-animation 的新 SeekableTransitionState API，支援應用程式內預測返回功能。這樣一來，您就能使用返回手勢，在決定要透過完成的手勢提交交易或取消交易前，先查看自訂 Transition 的先前目的地。

導覽片段可組合函式

  • 新增 navigation-fragment-compose 構件，其中包含 ComposableNavHostFragment 的替代項目 NavHostFragment，可讓您將可組合目的地新增至導覽 XML 檔案。每個 composable 目的地都必須表示為頂層、無引數的 @Composable 方法，其完整名稱會做為每個目的地的 android:name 屬性。導覽至其中一個目的地時，系統會建立包含片段，顯示可組合函式內容。
  // In HomeScreen.kt
  @Composable
  fun HomeScreen() {
    // Your Composable content here
  }

  // In your navigation.xml
  <composable
    android:id="@+id/home_screen"
    android:name="com.example.HomeScreenKt\$HomeScreen" />

其他變更

  • Navigation Compose 現在依附於 Compose 1.7.0。
  • Navigation 現在提供新的 CollectionNavType<T> 類別，這是 NavType<T> 的子類別，適用於以集合為基礎的引數，例如清單、陣列、對應。所有預設 NavType 陣列 (IntArrayType、LongArrayType、FloatArrayType、BoolArrayType 和 StringArrayType) 現在都會從這個新類別繼承。
  • NavType 現在內建支援 Int、String、Boolean、Float 和 Long 的清單。

2.8.0-rc01 版

2024 年 8 月 21 日

發布 androidx.navigation:navigation-*:2.8.0-rc01。2.8.0-rc01 版包含這些修訂項目。

修正錯誤

  • 修正將頂層列舉類別做為類型安全引數傳遞時，導致導覽功能當機的問題。(I0ba76、b/358137294)
  • Navigation 2.8 現在可正確搭配 SDK 34 運作，且在 2.9 版與其餘 AndroidX 程式庫一併發布前，不會切換至 SDK 35。(b/358798728)

2.8.0-beta07 版

2024 年 8 月 7 日

發布 androidx.navigation:navigation-*:2.8.0-beta07。2.8.0-beta07 版包含這些修訂項目。

已知問題

  • 由於 b/358137294，系統預設僅支援巢狀列舉。下一個版本將支援頂層列舉。

修正錯誤

  • 導覽至重複或共用的目的地時，導覽功能會優先前往圖表中與目前位置最接近的相符目的地。(Ic89a4、b/352006850)
  • Navigation in safe args 現在已新增 NavType.EnumType。也就是說，Enum 型別不再需要自訂 NavType。請注意，Enum的 SerialName必須是預設的完整名稱。(I66d22、b/346475493)
  • Safe Args 中的 Navigation 已新增對可為空值的引數類型 (包括 Int?、Long?、Float?、Boolean? 和 Enum<*>?) 的內建支援。(I32d13、I1c580、Ifba66、I978b0、Ide076、b/351994237)
  • 如果傳遞至 NavGraph 的 startDestination 路由與 startDestination.route 完全相同，NavGraph 的 startDestination 現在會使用預設引數值。(I13762、b/354046047)

2.8.0-beta06 版

2024 年 7 月 24 日

發布 androidx.navigation:navigation-*:2.8.0-beta06。2.8.0-beta06 版包含這些修訂項目。

修正錯誤

  • 修正 WrongStartDestinationType Lint 檢查不會檢查傳入類別型別的伴隨物件，導致 Lint 無法偵測錯誤的問題。(I92b09)

2.8.0-beta05 版

2024 年 7 月 10 日

發布 androidx.navigation:navigation-*:2.8.0-beta05。2.8.0-beta05 版包含這些修訂項目。

修正錯誤

  • 修正巢狀 NavGraphs 共用相同 startDestination 路線時，singleTop 導覽功能當機的問題。(I17b94、b/294408596)

2.8.0-beta04 版

2024 年 6 月 26 日

發布 androidx.navigation:navigation-*:2.8.0-beta04。2.8.0-beta04 版包含這些修訂項目。

修正錯誤

  • 導覽功能現在支援使用路徑引數中的空白字串進行導覽。(Ic5dbd、b/339481310)
  • 改善透過 @Serializable(with =...) 直接在類別欄位上宣告的自訂序列化程式錯誤訊息，明確指出目前不支援這項功能。(I052b0、b/341319151)
  • SavedStateHandleFactory 測試 API 現在可用於非 Android 測試，但需要 Robolectric 支援使用 Bundles 剖析引數。(I76cdc、b/340966212)
  • 修正在 Compose 中使用 Type-Safe Navigation 時，應用程式在程序終止後恢復運作時，還原狀態導致的當機問題。(Ia8f38、b/341801005)
  • 修正 Navigation Compose 的問題：取消預測返回手勢後，使用者返回的 NavBackStackEntry 不會返回 RESUMED 生命週期狀態。這也能確保返回目的地會正確地動畫返回，而不是在快速滑動後直接回到原位。(I97a0c、b/346608857)
  • 使用 Navigation Compose 的預測返回手勢時，彈出的目的地現在會具有正確的 Z 順序，並在傳入的目的地上方正確顯示動畫。(I2077b、b/345993681)

2.8.0-beta03 版

2024 年 6 月 12 日

發布 androidx.navigation:navigation-*:2.8.0-beta03。2.8.0-beta03 版包含這些修訂項目。

API 變更

  • CollectionNavType 有新的抽象 emptyCollection() 方法。覆寫此方法，處理以引數形式傳遞的空白集合。(Ie4d84、b/341723133)

修正錯誤

  • 新增 NavType.serializeAsValue 和 serializeAsValues 的說明文件，強調最終輸出內容應經過 URI 編碼。(Ida6bd、b/344943214)
  • 修正以空值 CollectionNavType 引數呼叫 toRoute<T> 時發生的當機問題。使用空值 CollectionNavType 導覽時，輸出引數會是 Serializable 類別中宣告的預設值，如果沒有預設值，則為 emptyCollection() 的回傳值。(I84158、Id630f、b/342672856)

2.8.0-beta02 版

2024 年 5 月 29 日

發布 androidx.navigation:navigation-*:2.8.0-beta02。2.8.0-beta02 版包含這些修訂項目。

修正錯誤

  • 修正使用可為空值的自訂 NavType 時，NavBackStackEntry.toRoute 導致 ClassCastException 異常終止的問題。(I1c29b、b/342239473)
  • 修正嘗試還原無法透過目前目的地 ID 存取的返回堆疊項目時，導致的 Navigation 返回堆疊狀態還原問題。由於路徑是以 ID 為基礎，因此以路徑建構的目的地也會受到影響。這也修正了因呼叫 clearBackStack() 而導致的當機問題，該問題的根本原因相同。(I423c3、b/339908057)

2.8.0-beta01 版

2024 年 5 月 14 日

發布 androidx.navigation:navigation-*:2.8.0-beta01。2.8.0-beta01 版包含這些修訂項目。

API 變更

  • SavedStateHandle.toRoute() 現在會使用 typeMap 參數，處理自訂引數型別。(Ie39fb、b/339026523)
  • 在 navigation-testing 中新增測試 API，可從 Kotlin Serializable 物件建立 SavedStateHandle。(Id4867、b/339080702)

修正錯誤

  • 已為 Navigation Kotlin DSL 函式新增缺少的參數文件。(I26a36)

2.8.0-alpha08 版

2024 年 5 月 1 日

發布 androidx.navigation:navigation-*:2.8.0-alpha08。2.8.0-alpha08 版包含這些修訂項目。

Navigation Compose 中的 Safe Args

這項功能會使用 Kotlin 序列化，讓您透過類型安全物件和資料類別，在導覽圖中定義目的地：

  // Define a home destination that doesn't take any arguments
  @Serializable
  object Home

  // Define a profile destination that takes an ID
  @Serializable
  data class Profile(val id: String)

  // Now define your NavHost using type safe objects
  NavHost(navController, startDestination = Home) {
      composable<Home> {
          HomeScreen(onNavigateToProfile = { id ->
              navController.navigate(Profile(id))
          })
      }
      composable<Profile> { backStackEntry ->
          val profile: Profile = backStackEntry.toRoute()
          ProfileScreen(profile)
      }
  }

詳情請參閱「Navigation Compose meet Type Safety」網誌文章。

新功能

  • navigation-fragment-compose 構件現在提供 LocalFragment 組合本機值，適用於 ComposableFragment 內的可組合方法。(If35e5)
  • NavType 現在內建支援 Int、String、Boolean、Float 和 Long 的清單。(I4b6dd、Ia914c、b/188693139)

2.8.0-alpha07 版

2024 年 4 月 17 日

發布 androidx.navigation:navigation-*:2.8.0-alpha07。2.8.0-alpha07 版包含這些修訂項目。

新功能

  • 新增 navigation-fragment-compose 構件，其中包含 ComposableNavHostFragment (NavHostFragment 的替代項目)，可讓您將 composable 目的地新增至導覽 XML 檔案。每個 composable 目的地都必須表示為頂層、無引數的 @Composable 方法，其完整名稱會做為每個目的地的 android:name 屬性。導覽至其中一個目的地時，系統會建立包含片段，顯示可組合函式內容。(I0ef2e、b/265480755)

    // In HomeScreen.kt
@Composable
fun HomeScreen() {
  // Your Composable content here
}

    // In your navigation.xml
<composable
  android:id="@+id/home_screen"
  android:name="com.example.HomeScreenKt\$HomeScreen" />

API 變更

2.8.0-alpha06 版

2024 年 4 月 3 日

發布 androidx.navigation:navigation-*:2.8.0-alpha06。2.8.0-alpha06 版包含這些修訂項目。

API 變更

修正錯誤

  • NavHost 現在會使用 Alignment.TopStart 做為預設的 contentAlignment 引數。這項變更可讓動畫與 AnimatedContent 的預設動畫保持一致，並修正從中心轉換時出現非預期縮放效果的部分情況。(I09e72、b/330111602)
  • 使用 Navigation Compose 時，如果輕拂預測返回手勢，NavHost 現在會正確完成自訂轉換，而不是立即結束。(I99017、b/327292110)

2.8.0-alpha05 版

March 20, 2024

發布 androidx.navigation:navigation-*:2.8.0-alpha05。2.8.0-alpha05 版包含這些修訂項目。

新功能

  • 您現在可以直接在 startDestination 路由中，將引數傳遞至 NavGraph 的 startDestination，不必依賴 defaultValue。這也適用於巢狀 NavGraph startDestinations。(I0e0b5、b/109505019、b/188693139)

API 變更

  • 新增抽象 CollectionNavType<T> 類別，這是 NavType<T> 的子類別，適用於以集合為基礎的引數，例如清單、陣列、對映。(Ic6d63、b/188693139)
  • 所有預設 NavType 陣列 (IntArrayType、LongArrayType、FloatArrayType、BoolArrayType 和 StringArrayType) 現在都是 CollectionNavType 型別 (Idcf79、b/188693139)
  • NavType 現在提供新的開放式 valueEquals API，可判斷相同型別的兩個值是否相等。(I6cb97、b/327229511)

修正錯誤

  • 深層連結中的查詢參數現在允許以大括號括住引數名稱 (即 {argName}) 的值，做為字串型 NavTypes 的有效值。修正這類值會被視為所有類型無效 (或沒有值) 的問題。(I18302、b/327274038)
  • 支援路徑的 NavController 函式 (例如 navigate 或 popBackStack) 現在可以正確比對以陣列 NavTypes 引數填入的路徑。(Iea805、b/327229511)

2.8.0-alpha04 版

2024 年 3 月 6 日

發布 androidx.navigation:navigation-*:2.8.0-alpha04。2.8.0-alpha04 版包含這些修訂項目。

新功能

  • 您現在可以在 Navigation Compose 中指定轉場效果的 SizeTranform，方法是在 composable 和/或 navigation 函式的初始化作業中定義這些效果。(I91062、b/296912651)

修正錯誤

  • 修正問題：在不使用手勢的情況下，透過系統返回鍵使用 Compose Navigation 中的 NavHost 時，無法正確顯示轉場效果。(Iceeae、b/325998468)

2.8.0-alpha03 版

2024 年 2 月 21 日

發布 androidx.navigation:navigation-*:2.8.0-alpha03。2.8.0-alpha03 版包含以下修訂項目。

API 變更

  • NavBackStackEntry.savedStateHandle 現在標示為 @MainThread，因為它使用的程式碼必須位於主執行緒。(Ibb988、b/299523245)

修正錯誤

  • 修正 Navigation 中的問題：由於相關聯項目的 ViewModel 不屬於已儲存狀態，導致 NavGraph ViewModel 過早 DESTROYED。(Ib6bb7、b/317581849)

依附元件更新

2.8.0-alpha02 版

2024 年 2 月 7 日

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

新功能

  • Navigation Compose 現在透過 compose-animation 的新 SeekableTransitionState API，支援應用程式內預測返回功能。這樣一來，您就能使用返回手勢，在決定要透過完成的手勢提交交易或取消交易前，先查看自訂 Transition 的先前目的地。(I8b8e9)

2.8.0-alpha01 版

2024 年 1 月 24 日

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

修正錯誤

  • 修正 BackStackState 洩漏問題：對目的地進行多次 saveState 呼叫時，系統會儲存多個狀態，但只能還原第一個狀態。(I598b0、b/309559751)
  • 修正問題：使用 NavigationUI 輔助程式填入應用程式列標題時，系統無法正確顯示非字串引數。(#636、b/316676794)

依附元件更新

外部貢獻

  • 感謝 SimonMarquis 修正問題，在使用 NavigationUI 輔助程式填入應用程式列標題時，非字串引數不會顯示。

2.7.7 版

2.7.7 版

2024 年 2 月 7 日

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

修正錯誤

  • 從「Navigation 2.8.0-alpha01」回溯移植：修正 BackStackState 洩漏問題，在單一 NavBackStackEntry 上多次呼叫 saveState() 會導致系統儲存多個狀態，但只能還原第一個儲存的狀態。(I598b0、b/309559751)
  • 從 Navigation 2.8.0-alpha01 回溯移植：修正使用 NavigationUI 輔助程式填入應用程式列標題時，非字串引數無法正確顯示的問題。(#636、b/316676794)

外部貢獻

  • 感謝 SimonMarquis 修正問題，在使用 NavigationUI 輔助程式填入應用程式列標題時，非字串引數不會顯示。

2.7.6 版

2.7.6 版

2023 年 12 月 13 日

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

修正錯誤

  • NavGraph equals() 函式現在會正確考量其他圖的節點，而不只是呼叫的節點。這項變更可確保系統不會再將具有不同 ID 節點的圖形視為相等 (I401cb、b/311414915)

2.7.5 版

2.7.5 版

2023 年 11 月 1 日

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

效能提升

  • 大幅提升比較兩個圖表的效能 (包括時間和分配次數)。這表示內部會比較新圖表與現有圖表的 setGraph 等呼叫速度會快上許多，並減少略過的影格。感謝 Michał Z 的深入分析，促成這項改善。(I6ad62)
  • NavHost 現在會在第一次組合傳遞時算繪起始目的地，不必等待第二次傳遞讀取更新的狀態。(I439a7、b/304852206)

修正錯誤

  • 修正問題：如果圖形中含有連結兩個目的地的動作，且您使用完全相同的圖形呼叫 setGraph 超過一次，系統就會彈出返回堆疊。(Ieaed7)
  • 如果對話方塊在快速連續導覽和關閉後，不再洩漏到 NavController.visibleEntries 清單中，(I67586、b/287969970)
  • 如果 saveState 為 false，當項目彈出後發生設定變更時，系統現在會正確清除項目的 ViewModel。(Idf242、b/298164648)
  • 修正問題：如果設定變更或呼叫 setGraph 之前，返回堆疊完全空白，且傳入的 Intent 已設定 FLAG_ACTIVITY_NEW_TASK 標記，NavController 可能會多次處理相同的深層連結。(I73c7f)

依附元件更新

  • 使用片段的 Navigation 現在依附於 Fragment 1.6.2，修正呼叫 clearBackStack 時，巢狀片段的 ViewModel 執行個體不會清除的問題。

2.7.4 版

2.7.4 版

2023 年 10 月 4 日

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

新功能

  • 新增支援 popUpTo 使用含引數的路徑，以便返回使用這些確切引數的特定項目，與 popBackStack 中的支援功能相符。(I731f4、b/299255572)

修正錯誤

  • 修正問題：使用 popUpTo 中斷導覽並進行其他導覽時，會導致 FragmentNavigator 當機。(I3c848、b/301887045)
  • 修正問題：系統返回鍵會導致 currentDestination 無法正確更新，與顯示的片段相符。(Id0d6c、b/289877514)
  • 現在，當系統關閉上方的對話方塊時，DialogFragment 生命週期會正確移至 RESUMED 狀態。(I88f0d、b/301811387)

2.7.3 版

2.7.3 版

2023 年 9 月 20 日

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

修正錯誤

  • 修正 Navigation with Fragments 中的問題，導致 visibleEntries 清單包含不正確的項目。(I5caa9、b/288520638)
  • 修正問題：導致浮動視窗目的地 (即 Dialogs、Bottomsheets 等) 永遠不會收到 RESUMED 生命週期回呼。(I3b866、b/287505132)

2.7.2 版

2.7.2 版

2023 年 9 月 6 日

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

修正錯誤

  • Navigation 現在依附於 Lifecycle 2.6.2，修正 rememberSaveable 與 Navigation Compose 的 NavHost 之間的互動，避免程序終止並重建後，目的地和任何 ViewModel 所擁有的 SavedStateHandle 例項無法正確還原 rememberSaveable 狀態。(b/298059596、b/289436035)
  • 修正問題：在 Navigation Compose 中同時顯示多個對話方塊時，部分遭遮蔽的對話方塊 (例如非最上層的對話方塊) 會處於 CREATED Lifecycle 狀態，而非 STARTED 狀態。(aosp/2728520、b/289257213)
  • 修正問題：在 Navigation Compose 中同時顯示多個對話方塊時，如果關閉最上層的對話方塊，新的最上層對話方塊會停留在 STARTED 生命週期狀態，而不是正確移至 RESUMED。(aosp/2629401、b/286371387)
  • 如果 Navigation Safe Args 實際上並未執行工作，就不會再急切地例項化工作。(I0e385、b/260322841)

依附元件更新

  • Navigation Compose 現在依附於 Compose 1.5.1。

2.7.1 版

2.7.1 版

2023 年 8 月 23 日

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

修正錯誤

  • 修正 Navigation with Compose 的問題：使用 Scaffold 時，可能會因嘗試存取 Lifecycle.State.DESTROYED ViewModel 而發生錯誤。(I1dc11、b/268422136)

2.7.0 版

2.7.0 版

2023 年 8 月 9 日

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

自 2.6.0 版以來的重要變更

Accompanist 的動畫

AnimatedContent 穩定版推出後，我們便能將程式碼從 Accompanist Navigation Animation 移回 Navigation Compose 本身。

也就是說，NavHost 直接支援 AnimatedNavHost 中所有自訂轉場效果的設定。

我們不會對 Accompanist Navigation Animation 進行任何額外變更，並將於近期正式淘汰這項功能，同時提供如何遷移回 Navigation Compose 的指南。不過，如果您已使用最新版 Accompanist Alpha (0.31.2-alpha)，只要按照遷移指南的相反步驟操作即可，不需要進行其他 API 變更。(b/197140101)

修正錯誤

  • 即使 Activity 處於 STOPPED 和 RESUMED 狀態，Navigation Compose 中的 NavHost 現在也能正確攔截系統返回呼叫。(Icb6de、b/279118447)

依附元件更新

  • Navigation 現在依附於 Compose 1.5.0，而非 1.1.0。

2.7.0-rc01 版

2023 年 7 月 26 日

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

修正錯誤

  • 修正問題：即使從組合中移除 NavHost，做為 NavHost 一部分建立的 EnterTransition 和 ExitTransition lambda 仍可能保留在記憶體中。(I893d0)

已知問題

  • Navigation 2.6.x 存在問題，使用 popUpTo 導覽時可能會導致 IllegalArgumentException。您可以重組圖表，避免發生這項例外狀況，類似於這裡建議的做法。(b/287133013)

2.7.0-beta02 版

2023 年 6 月 28 日

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

修正錯誤

  • Navigation Compose 現在可為使用 popUpTo 選項導覽的自訂轉場效果，設定正確的 z 順序。(/Ib1c3a、b/285153947)

2.7.0-beta01 版

2023 年 6 月 7 日

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

修正錯誤

  • 即使 Activity 已 STOPPED 和 RESUMED，Navigation Compose 中的 NavHost 現在仍可正確攔截系統返回呼叫。(Icb6de、b/279118447)

2.7.0-alpha01 版

2023 年 5 月 24 日

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

Accompanist 的動畫

AnimatedContent 穩定版推出後，我們便能將程式碼從 Accompanist Navigation Animation 移回 Navigation Compose 本身。

也就是說，NavHost 直接支援 AnimatedNavHost 中所有自訂轉場效果的設定。

我們不會對 Accompanist Navigation Animation 進行任何額外變更，並將於近期正式淘汰這項功能，同時提供如何遷移回 Navigation Compose 的指南。不過，如果您已使用最新版 Accompanist Alpha (0.31.2-alpha)，只要按照遷移指南的相反步驟操作即可，不需要進行其他 API 變更。(b/197140101)

修正錯誤

  • 自 Navigation 2.6.0-rc02 起：修正 Fragments 中的 Navigation 問題。使用 popUpTo 導覽並從返回堆疊彈出片段，但未重新建立其檢視區塊時，系統返回按鈕會停止運作。(Ieb8d4、b/281726455)

依附元件更新

  • Navigation 現在依附於 Compose 1.5.0-beta01。

2.6.0 版

2.6.0 版

2023 年 6 月 7 日

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

自 2.5.0 版以來，導覽功能的重要異動

  • NavBackStackEntry 的 arguments 和傳送至 OnDestinationChangedListener 的 arguments 現在只是不可變引數的副本 (您在導覽到目的地時建立了這些引數)。這表示在後續存取 arguments 或其他 OnDestinationChangedListener 執行個體時，不會反映對這些套裝組合所做的任何變更。
  • NavDeepLink 現在支援陣列的預設值，可讓您支援對應到引數的陣列類型的重複查詢參數。NavType 現在也包含預設方法，您可以覆寫該方法以合併兩個剖析值。
  • NavType 的自訂子類別現在可以覆寫 serializeAsValue，以便將值序列化為字串，讓序列化和反序列化程序 (透過 parseValue) 完全封裝在 NavType 類別中。StringType 現在會覆寫這個方法，進而在指定的 String 上呼叫 Uri.encode。

自 2.5.0 版以來，Navigation Compose 的重要變更

  • 使用 NavHost 預覽可組合項時，現在預設會顯示 NavGraph 的 startDestination。
  • NavController.popBackStack(route)、NavController.getBackStackEntry(route)、NavController.clearBackStack(route) 現在都支援填入部分或完整引數的路徑。請注意，引數必須與該項目的引數完全相符。
  • 現在，如果嘗試使用 navDeepLink Kotlin DSL 建立空白的 NavDeepLink，會顯示 Lint 警告，表示需要有效的 URI、動作和/或 MIME 類型才能建立深層連結。

自 2.5.0 版以來，Navigation 與片段的重要變更

  • NavHostFragment 不再攔截系統返回按鈕本身。這可讓基礎 FragmentManager 處理系統返回動作。這樣一來，Android U 裝置上的 Fragment 1.7.0-alpha01 以上版本就能提供應用程式內預測返回動畫。
  • 將 Navigation 與 Fragment 搭配使用時，如果嘗試手動執行 FragmentTransaction，將片段新增至 FragmentManager 的返回堆疊，系統現在會擲回 IllegalArgumentException。請務必透過 navigate() API 新增片段。
  • 在導覽 XML 檔案的活動元素的 app:data 和 app:dataPattern 屬性中將字串 ${applicationId} 設定為預留位置時，預留位置會在加載後自動填入背景資訊的 packageName。
  • 在瀏覽和彈出 NavBackStackEntries 時，FragmentNavigator 現在會使用轉換 API。這表示 NavBackStackEntry Lifecycle 現在會等到進入和離開片段的特效完成後，再移至最終的 Lifecycle.State。
  • 在瀏覽和彈出 NavBackStackEntries 時，DialogFragmentNavigator 現在會使用轉換 API。這表示 NavBackStackEntry Lifecycle 現在會等到 DialogFragment Lifecycle 移至 DESTROYED 後，再移至 DESTROYED
  • NavHostFragment 現在可讓您在 NavHostFragment 附加至 FragmentManager 後立即擷取 NavController，而不只是在 onCreate() 後。
  • Navigation 支援的動態功能模組現在依附於細部化的 Play Feature Delivery 程式庫。
  • Navigation Safe Args 現在依附於 Android Gradle 外掛程式 7.3.0 版本。這表示其現已與 7.3.0 以上版本相容。

自 2.5.0 版以來，NavigationUI 的重要變更

  • 將導覽圖的 ID 傳送至 AppBarConfiguration (例如透過 Menu) 時，NavigationUI 現在只會將該導覽圖的起始目的地視為頂層目的地，而不會錯誤地標記圖中每個目的地做為頂層目的地。傳遞個別目的地 ID 的行為則維持不變。您可以在 AppBarConfiguration 中透過新的 isTopLevelDestination 函式，將同樣的功能提供給自己的程式碼。
  • NavigationUI 中用於頂端應用程式列的 setupWithNavController 整合現在會將 android:label 中找到的 ReferenceType 引數的 R.string 值剖析為其字串值，而不是輸出自動產生的資源整數。
  • 現在如果 NavigationUI 未能透過選定的 MenuItem 進行導覽，則會提供記錄。

2.6.0-rc02 版

2023 年 5 月 24 日

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

修正錯誤

  • 修正片段中的 Navigation 問題：使用 popUpTo 導覽並從返回堆疊彈出片段，但未重新建立其檢視畫面時，系統返回功能會停止運作。(Ieb8d4、b/281726455)

2.6.0-rc01 版

2023 年 5 月 10 日

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

修正錯誤

  • 修正導覽功能中的片段問題：透過 onResume() 生命週期回呼中的 popUpTo 導覽移除片段時，會導致 IllegalStateException。(I21884、b/279644470)

2.6.0-beta01 版

2023 年 4 月 19 日

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

新功能

  • NavBackStackEntry 現在提供自訂 toString 實作。(Iff00b)

修正錯誤

  • 將 Navigation 與 Fragment 搭配使用時，如果嘗試手動執行 FragmentTransaction，將片段新增至 FragmentManager 的返回堆疊，系統現在會擲回 IllegalArgumentException。請務必透過 navigate() API 新增片段。(I6d38e)
  • 如果同一個影格中同時有 navigate 新增項目和 popBackStack 移除項目，返回堆疊中的頂端項目現在會一律返回 RESUMED Lifecycle.State。(Id8067、b/276495952)

2.6.0-alpha09 版

2023 年 4 月 5 日

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

修正錯誤

  • 修正無效路徑的檢查，如果 NavDestination 包含不可為空值的 NavArgument，則此目的地的路徑必須包含與不可為空值的 NavArgument 同名的引數預留位置。(Ic62bf、b/274697949)
  • 如果導覽作業缺少 NavDestination 要求的非空值 NavArgument，且 Action/MimeType 與該 NavDestination 相符，則以 Action/MimeType 為基礎的深層連結導覽作業會失敗。(Ibfa17、b/271777424)
  • 如果 NavController 設定的導覽圖與先前的導覽圖具有相同的路徑和目的地，現在會正確地以新例項取代目前的導覽圖節點和返回堆疊目的地。修正在 Navigation Compose 中使用 onLaunchSingleTop，但未儲存狀態時發生的當機問題。此外，也修正了導覽至與根圖表相關聯的目的地時，系統會建構不正確返回堆疊的錯誤。(I5bc58、b/275258161、b/275407804)

2.6.0-alpha08 版

2023 年 3 月 22 日

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

新功能

  • NavHostFragment 現在可讓您在 NavHostFragment 附加至 FragmentManager 後立即擷取 NavController，而不只是在 onCreate() 後。(Ic6382、b/220186282)

修正錯誤

  • 修正彈出包含不可為空引數的巢狀圖時，會發生 NullPointerException 的問題。(6b3581、b/249988437)
  • 使用 popUpTo 導覽後，使用系統返回鍵時，NavController 的狀態會彈出至正確的項目。(I3a8ec、b/270447657)
  • 現在透過系統返回或 popBackStack() 彈出返回堆疊時，FragmentNavigator 會正確彈出項目，無論交易是否使用片段效果都一樣。(I81bdf)
  • 將片段新增至 FragmentNavigator 的 FragmentManager，且不使用導覽功能時，不會再導致應用程式異常終止。(b17204、b/274167493)

依附元件更新

2.6.0-alpha07 版

2023 年 3 月 8 日

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

修正錯誤

  • 現在，採用路徑的 getBackStackEntry、popBackStack、clearBackStack API 變數會採用具有可為空引數和可為空查詢參數的路徑模式 (I22294、b/269302500)
  • 修正問題：從 NavController 呼叫 clearBackStack() 時，不會清除與已清除返回堆疊相關聯的片段管理員中儲存的狀態。(Ic1cce、b/271190202)
  • 修正 2.6.0-alpha06 中的迴歸問題，該問題會導致在分頁之間使用系統返回鍵時，BottomNavigationView 中會醒目顯示錯誤的 MenuItem。(I634f6、b/270447657)
  • 修正 2.6.0-alpha06 中的迴歸問題，該問題會導致使用 Animation 時，NavBackStackEntry 無法移至 RESUMED 狀態。(Ib3589、b/269646882)

2.6.0-alpha06 版

2023 年 2 月 22 日

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

新功能

  • 使用 NavHost 預覽可組合項時，現在預設會顯示 NavGraph 的 startDestination。(I2b89f)

API 變更

  • 所有 NavController navigate 多載現在都會以 @MainThread 加註，確保這些多載是在主執行緒上呼叫。(I2c0b0、b/263427111)

修正錯誤

  • 修正使用動態 Fragment 導覽時，嘗試導覽時發生的當機問題。(I3ee29、b/268360479)
  • 修正錯誤：透過系統返回按鈕導覽至其他片段時，底部列不會更新為正確的所選項目 (If559f、b/269044426)

已知問題

  • 使用 Navigation 和 Fragment 時，使用 Animation API 會導致 NavBackStackEntry 的 Lifecycle 無法達到 RESUMED。(b/269646882)
  • 將 Navigation 與 Fragment 搭配使用，並透過 BottomNavigation 導覽時，如果嘗試還原含有多個項目的返回堆疊，BottomMenuItem 將無法正確更新。(b/270447657)
  • 使用 Navigation with Fragments 時，還原狀態後，NavBackStackEntry Lifecycle 不會在片段為 DESTROYED 時取得 DESTROYED。(b/270610768)

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)

依附元件更新

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)。

依附元件更新

2.5.1 版本

2022 年 7 月 27 日

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

修正錯誤

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

依附元件更新

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 變更

修正錯誤

  • 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 版的修訂項。

新功能

修正錯誤

  • 在 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 版本

2.4.2 版本

2022 年 4 月 6 日

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

修正錯誤

2.4.1 版本

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 版本

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)

依附元件更新

2.4.0-alpha08 版本

2021 年 9 月 1 日

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

新功能

行為變更

  • 產生動作時，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 變更

修正錯誤

  • 使用者按下系統返回按鈕或點選按鈕外的區域來關閉對話方塊時，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)

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

用於儲存及還原狀態的基礎 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 參數。

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

我們更新了 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)

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 版的修訂項。

依附元件更新

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 版本

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)

外部貢獻

2.3.4 版本

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 版本

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 版本

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 版本

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 版本

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)

依附元件更新

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)

依附元件更新

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 變更

修正錯誤

  • 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)

依附元件變更

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)

依附元件更新

2.2.2 版本

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)

依附元件更新

2.2.1 版本

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)

依附元件更新

2.2.0 版本

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 版的修訂項。

修正錯誤

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 變更

修正錯誤

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

2.1.0 版本

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 版本

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 版本

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 日

新功能

破壞性變更

  • 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 日

新功能

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。