本頁面由 Cloud Translation API 翻譯而成。

navigation3

API 參考資料
androidx.navigation3.runtime
androidx.navigation3.ui

Navigation 3 是專為搭配 Compose 設計的全新導覽程式庫。

最近更新時間	穩定版	候選版	Beta 版	Alpha 版
2025 年 10 月 22 日	-	-	1.0.0-beta01	-

宣告依附元件

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

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

Groovy

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

Kotlin

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

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

意見回饋

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

建立新問題

詳情請參閱 Issue Tracker 文件。

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

1.0 版本

1.0.0-beta01 版

2025 年 10 月 22 日

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

API 變更

SceneStrategyScope 現在只有不含引數的公開建構函式，適合單獨測試 SceneStrategy 和傳回的 Scene。如要處理更複雜的用途，請使用 rememberSceneState()。(I8440c、b/451679047)

修正錯誤

修正將 SceneStrategy 與 then 串連時的無限迴圈問題。(Iba3f0、b/450323470)
修正問題：在切換傳遞至 NavDisplay 的 backStack 時，使用動畫會導致螢幕閃爍。(Ief7b5、b/450967248)

1.0.0-alpha11 版本

2025 年 10 月 8 日

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

API 變更

SceneStrategy 的 calculateScene 方法不再是 @Composable。建議您改為將這項工作移至 SceneStrategy 方法 (即 rememberMySceneStrategy() 方法) 的建構作業，這樣就能完全根據正確的值定義任何 rememberSaveable 值或鍵 remember 陳述式的生命週期。(If1733、b/448709506)
SceneStrategy.calculateScene 的 onBack 參數已移至 SceneStrategyScope 的新接收器範圍，以便清楚瞭解這是選用參數，並為日後的 Navigation3 功能提供擴充點。(I3aea3、b/448460407)
傳遞至 NavDisplay 和 SceneStrategy 的 onBack lambda 不再提供 count: Int 參數，指出應彈出多個項目。在極少數情況下，如果 Scene 要求彈出多個項目，系統現在會連續多次呼叫 () -> Unit lambda。(Idedb5、b/446989346)
移除 NavEntryWrapper 類別，並以最終的 NavEntry 類別取代其功能，該類別具有新的次要建構函式，可使用新內容取得 NavEntry。這樣一來，系統就能繼續支援以新內容包裝項目。(I7da2a、b/444447130)
已移除建立及傳回 NavEntryDecorator 的 navEntryDecorator 函式，並以 NavEntryDecorator 類別取代，該類別現已公開，並開放建立子類別。(If81f8、b/444447434、b/447381176)
由於「SavedStateNavEntryDecorator」會使用「SaveableStateHolder」裝飾項目，因此已重新命名為「SaveableStateHolderNavEntryDecorator」。由於裝飾器在功能上是 NavEntryDecorator 的工廠，因此也從函式重構為類別。(Ie6013、b/447381176)
使用 SceneState 做為 NavDisplay 的替代方案，自訂顯示畫面不再需要使用 LocalEntriesToRenderInCurrentScene 組合區域 (現為內部)。(Ic40ef、b/414668196)
已從公開 API 介面中移除 SceneSetupNavEntryDecorator 和 rememberSceneSetupNavEntryDecorator()。這項功能現在預設會納入，您不需要手動加入。(Ieae42、b/444479133)
NavEntry、DialogScene、SinglePaneScene 和 SceneState 現在都會實作 equals。(I96121)
場景介面新增中繼資料欄位，可附加 NavDisplay 的場景專屬中繼資料。這樣一來，Scene 就能覆寫 NavDisplay 上的中繼資料，例如轉場效果。(I1fd96、b/443955625)
移除多餘的一般類型參數，簡化 rememberNavBackStack 簽章。函式現在可接受 vararg elements: NavKey。(I03e45)
NavDisplay 的預設動畫現已納入通用 API，因此可從所有平台呼叫。(I71af9、b/447147159)
將 EntryProviderBuilder 重新命名為 EntryProviderScope，準確反映這個類別是 Kotlin DSL，提供建構 NavEntries 的範圍。(Ia7465)

修正錯誤

rememberNavBackStack() 現在會對 NavKey 強制執行多型序列化，並要求自訂 SavedStateConfiguration，確保狀態還原正確無誤。KDoc 已更新，反映所有 NavKey 子型別都必須在提供的 SerializersModule 中註冊的要求。(I6de37、I782f2、b/446664383)

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)

依附元件變更

Navigation3 現在依附於 NavigationEvent Alpha08。

1.0.0-alpha08 版本

2025 年 8 月 27 日

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

新功能

已在 Navigation3 Runtime 構件中新增 Kotlin MultiPlatform (KMP) 目標。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、b/425901162、b/434109022)

已知問題

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

AndroidX 的預設 minSdk 已從 API 21 移至 API 23 (Ibdfca、b/380448311、b/435705964、b/435705223)

API 變更

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

修正錯誤

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

依附元件更新

Navigation3 現在依附於 Navigation Event 1.0.0-alpha06。

1.0.0-alpha06 版本

2025 年 7 月 30 日

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

依附元件更新

Navigation3 現在依附於 Navigation Event 1.0.0-alpha05。

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 指南。