navigation3

  
Navigation 3 是專為搭配 Compose 使用而設計的新導覽程式庫。
最近更新時間 穩定版 候選版 Beta 版 Alpha 版
2025 年 9 月 24 日 - - - 1.0.0-alpha10

宣告依附元件

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

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

Groovy

dependencies {
    implementation "androidx.navigation3:navigation3-runtime:1.0.0-alpha10"
    implementation "androidx.navigation3:navigation3-ui:1.0.0-alpha10"
}

Kotlin

dependencies {
    implementation("androidx.navigation3:navigation3-runtime:1.0.0-alpha10")
    implementation("androidx.navigation3:navigation3-ui:1.0.0-alpha10")
}

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

意見回饋

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

建立新問題

詳情請參閱 Issue Tracker 文件。

這個構件沒有任何版本資訊。

1.0 版本

1.0.0-alpha10 版本

2025 年 9 月 24 日

發布 androidx.navigation3:navigation3-*:1.0.0-alpha10。1.0.0-alpha10 版包含這些修訂項目。

API 變更

  • 新增 NavDisplay 超載，該超載會採用已由 rememberDecoratedNavEntries 裝飾的 NavEntry<T> 清單。(I4025b、b/441940314)
  • DialogScene 已移至新套件。(Ia5840)
  • 移除公用 API DecorateNavEntry。請改用 rememberDecoratedNavEntries，以裝飾器清單包裝 NavEntry。(Id8c09)
  • Navigation3 UI 現在提供新的預設 transitionSpec 屬性。(Ibcabd)
  • 新增 SceneState 物件，協助管理場景。這也提供新的 NavDisplay 超載，可擷取 SceneState 和 NavigationEventState。(Idfb46、b/444479133)
  • NavDisplay 現在可根據您要前往和離開的 Scene，透過 Transition 的 currentState 和 targetState 自訂轉場效果。(I906cc、b/443872322)
  • NavigationEventInfo 現在是 abstract class，而非 interface。更新所有自訂實作，從類別 (例如 data class MyInfo : NavigationEventInfo()) 繼承。(I1e59c、b/444734264)
  • 已更新 navigationevent-compose 處理常式 API，NavigationEventHandler 和 NavigationBackHandler (以及變體) 現在支援新的多載，可接受升高的 NavigationEventState。簡單的超載 (採用 currentInfo) 會保留，並在內部使用這個新狀態模型。(Ic3251、b/444734264)
  • 所有 Scene API 都已從 navigation3-ui 移至 navigation3-runtime。也就是說，這些 API 現在適用於 navigation3-runtime 支援的所有平台。(I431d0、b/444449993)
  • 新增 rememberDecoratedNavEntries 超載，可採用要裝飾的 NavEntry 清單。輸入項目可能已使用其他項目裝飾器裝飾。(I5a034、b/444230270)
  • 移除 navigation3 萬用字元型別參數 (I02540)
  • 改善 entryProvider DSL 的泛型處理方式。如果您先前匯入 androidx.navigation3.runtime.entry，現在可不必這麼做。(I299fc)
  • 將以反射為基礎的 NavBackStackSerializer 多載限制在 Android。在多平台程式碼中強制使用明確的 SavedStateConfiguration 多載，避免在非 Android 平台上發生隱含的執行階段序列化失敗情形。(I73313、b/420443609)
  • Make NavigationEvent's swipeEdge an @IntDef (Icee54, b/443950342)
  • 將 NavBackStack 序列化限制為 Android。這可避免非 Android 平台發生執行階段錯誤。如要跨平台儲存狀態，請使用具有明確 SavedStateConfiguration 的 rememberNavBackStack 多載。(I1e418、b/420443609)

修正錯誤

  • 修正巢狀 NavDisplay 只有一個子項時，在預測返回期間發生的異常終止問題。(I2cdc0、b/441933162)

1.0.0-alpha09 版本

2025 年 9 月 10 日

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

API 變更

  • DecoratedNavEntryProvider 已替換為 rememberDecoratedNavEntries，後者會建立並傳回以所提供裝飾器清單裝飾的 NavEntry (I0fe1c、b/441328236)
  • NavBackStack 現在是一般 NavKey 型別。這樣一來，應用程式和程式庫就能為返回堆疊定義自訂鍵類型，而不必受限於 NavKey。(I4d190、Iad2f4、b/420443609)
  • NavBackStack 現在是 @kotlinx.serialization.Serializable，因此您可以在程序終止和設定變更時儲存及還原導覽狀態，不必使用額外的樣板。(I2c3cf、b/420443609)
  • RememberNavBackStack 已移至 commonMain，確保所有平台目標都能提供這項資訊。(Id69e7、b/420443609)

修正錯誤

  • NavDisplay 現在可正確將每個 NavEntry 移至正確的 Lifecycle.State。(I30aac、b/440145700)
  • 修正 NavDisplay 會忽略透過 NavigationEvent 程式庫的 LocalNavigationEventDispatcherOwner 設定的所有巢狀 NavigationEventDispatcherOwner 問題。(I6224a)

依附元件變更

1.0.0-alpha08 版本

2025 年 8 月 27 日

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

新功能

  • 已將新的 Kotlin MultiPlatform (KMP) 目標新增至 Navigation3 Runtime 構件。Navigation3 Runtime 現在總共支援下列平台：JVM (Android 和桌上型電腦)、原生 (Linux、iOS、watchOS、macOS、MinGW) 和網頁 (JavaScript、WasmJS)。(I55078、b/424410398、b/419294028、b/419046226)。注意：這不會提供 Navigation3 UI 構件的 KMP 目標。在其他平台上，您需要實作自己的自訂 NavDisplay。如要支援這項功能，請在 Jetbrains 問題頁面上投票，並追蹤進度。
  • NavDisplayInfo 物件現在是公開物件，可用於從 NavDisplay 擷取可見項目清單。(Ibc91f)

API 變更

  • 新增 NavBackStackSerializer，可與 rememberNavBackStack 搭配使用，執行狀態還原作業。rememberNavBackStack() 現在也會使用 SavedStateConfiguration，可用來提供您自己的設定。(I2f4d2、I4cd58、b/420443609)

修正錯誤

已知問題

  • I8bf6d 導入的錯誤導致生命週期以場景為準，而非個別項目，因此如果提供給 NavEntry 的 key 不是 String，或 NavEntry 未覆寫 contentKey 並將其設為等於 key (請注意，這樣做會強制將鍵儲存到 Bundle 中)，生命週期就會中斷。這個問題已在下一個版本中修正。(b/440145700)

1.0.0-alpha07 版本

2025 年 8 月 13 日

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

MinSdk 更新

API 變更

  • SavedStateNavEntryDecorator 現在會使用 SaveableStateProvider 內建的 SaveableStateRegistry 儲存及還原狀態。(If8d9a)
  • 現在，系統會將滑動邊緣做為參數提供給 predictivePopTransitionSpec，讓您根據使用者啟動預測返回手勢的邊緣，自訂轉場效果。(I753a8)

修正錯誤

  • 修正問題：系統不會記住最近的場景，導致自訂場景無限重新計算。(I7ba84、b/418153031)

依附元件更新

1.0.0-alpha06 版本

2025 年 7 月 30 日

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

依附元件更新

1.0.0-alpha05 版本

2025 年 7 月 2 日

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

行為變更

  • NavEntry 的狀態現在會嚴格根據傳遞至 NavDisplay 的裝飾器清單。也就是說，如果有多個返回堆疊，裝飾器應沿著返回堆疊交換，才能保留返回堆疊中 NavEntry 的狀態。否則，系統會清除狀態，如同項目已彈出 (而非交換)。(I7a759、b/428033667)

1.0.0-alpha04 版本

2025 年 6 月 18 日

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

API 變更

  • 「NavEntry.content」現已設為私人。如要叫用 NavEntry 內容，請呼叫新的 NavEntry.Content() API，這個 API 不再需要 key 參數即可叫用。(Icd0fd、b/420991203)
  • NavEntry.key 現在是私有欄位。NavEntry 及其相關狀態應由新的 contentKey 欄位識別，該欄位是從新的 contentKeyFactory lambda 產生，預設為從 NavEntry.key 產生的可儲存雜湊 (I81a6c、b/422001357、b/420991203 I2d7d4、b/420991203、b/422841812)

依附元件變更

  • Navigation3 現在依附於新的 androidx.navigationevent.compose 構件。

1.0.0-alpha03 版本

2025 年 6 月 4 日

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

修正錯誤

  • Navigation3 不再清除已換出並替換為其他 backStack 執行個體的 backStacks 裝飾器狀態。(I28a42、b/415076044)

1.0.0-alpha02 版

2025 年 5 月 23 日

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

修正錯誤

  • 修正 SavedStateNavEntryDecorator 的問題，避免具有相同屬性值的不同資料類別發生衝突。(b/418070648、Iff4775)
  • 修正缺少類別的問題，避免在未宣告明確依附元件的情況下執行時發生當機問題。(b/419049149、I4b4ed)

1.0.0-alpha01 版

2025 年 5 月 20 日

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

新功能

Navigation3 是專為處理 Jetpack Compose 應用程式內導覽功能而建構的新導覽程式庫。androidx.navigation3.runtime 構件提供建構區塊，而 androidx.navigation3.ui 構件則透過 NavDisplay API 提供 UI 層。開發人員可以直接將自己的狀態提供給 NavDisplay 可組合函式，根據開發人員狀態的變化來變更內容。

@Serialiable object Home : NavKey
@Serialiable object Chat : NavKey

val backStack = rememberNavBackStack(Home)

NavDisplay(backStack, entryProvider = entryProvider {
  entry<Home> {
    Column {
      Text(“Home”)
      Button(onClick = { backStack.add(Chat) } ) {
        Text(“Go to Chat”)
      } 
    }
  }
  entry<Chat> { /* My Composable Content */ }
})

詳情請參閱 Navigation3 指南。