navigation3

API 参考文档
androidx.navigation3.runtime
androidx.navigation3.ui

Navigation 3 是一个旨在与 Compose 搭配使用的新导航库。

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2026 年 3 月 25 日	1.0.1	1.1.0-rc01	-	-

声明依赖项

如需添加 navigation3 的依赖项，您必须将 Google Maven 制品库添加到项目中。如需了解详情，请参阅 Google 的 Maven 制品库。

在应用或模块的 build.gradle 文件中添加所需工件的依赖项：

Groovy

dependencies {
    implementation "androidx.navigation3:navigation3-runtime:1.1.0-rc01"
    implementation "androidx.navigation3:navigation3-ui:1.1.0-rc01"
}

Kotlin

dependencies {
    implementation("androidx.navigation3:navigation3-runtime:1.1.0-rc01")
    implementation("androidx.navigation3:navigation3-ui:1.1.0-rc01")
}

如需详细了解依赖项，请参阅添加 build 依赖项。

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题，或对此库有任何改进建议，请告诉我们。创建新问题前，请先查看此库中的现有问题。您可以点击星标按钮，为现有问题投票。

创建新问题

如需了解详情，请参阅问题跟踪器文档。

此工件没有版本说明。

版本 1.1

版本 1.1.0-rc01

2026 年 3 月 25 日

发布了 androidx.navigation3:navigation3-*:1.1.0-rc01。版本 1.1.0-rc01 中包含这些提交内容。

bug 修复

NavDisplay 现在可确保在叠加层下方显示的条目的 Lifecycle 上限为 STARTED。这样可确保在使用对话框时，dropUnlessResumed 等 API 能够继续正常运行。(If209f, b/483966071)
修复了 NavDisplay 中的一个问题：在同一屏幕之间来回导航并中断两个屏幕之间的动画可能会导致屏幕的 z 顺序不正确。(I4d491, b/459419800)

版本 1.1.0-beta01

2026 年 3 月 11 日

发布了 androidx.navigation3:navigation3-*:1.1.0-beta01。版本 1.1.0-beta01 中包含这些提交内容。

版本 1.1.0-alpha05

2026 年 2 月 25 日

发布了 androidx.navigation3:navigation3-*:1.1.0-alpha05。版本 1.1.0-alpha05 中包含这些提交内容。

API 变更

NavDisplay 和 rememberSceneState 现在采用 List<SceneStrategy>，而不是之前由 then 中缀链接的单个 SceneStrategy 参数。这与这两个 API 已经采用的 List<SceneDecoratorStrategy<T>> 更为一致。之前的 API 已被废弃。(I78b2c, b/482108465)
添加了元数据 #contains 运算符，用于检查元数据映射是否包含给定的 NavMetadataKey。(Ic30db, b/485311895)
为 DialogSceneStrategy 添加了 NavMetadataKey DialogKey，以便与元数据 DSL 搭配使用。(Ic7a26, b/483388817)

版本 1.1.0-alpha04

2026 年 2 月 11 日

发布了 androidx.navigation3:navigation3-*:1.1.0-alpha04。版本 1.1.0-alpha04 中包含这些提交内容。

新功能

Navigation3 现在提供新的类型安全元数据 DSL。该 DSL 使用新的 MetadataKey 接口，该接口允许定义他们希望提供给元数据映射的键和值类型。此外，该 DSL 还为 NavDisplay 转换添加了新的 NavMetadataKey，以便它们可以与新的 metadata DSL 搭配使用，从而向 NavDisplay 添加转换。(Ic10ef, Ic049c,b/476213928)

API 变更

OverlayScene 接口具有新的 onRemoved 挂起回调。此回调会在与场景关联的键从返回堆栈中移除后调用，但在离开组合之前调用。这样一来，在 onRemoved 中调用的退出动画便可在叠加场景从组合中移除之前完成。(I29a72, b/440558061)
SceneStrategy 已将装饰函数分离到新的 SceneDecoratorStrategy 中。这个新接口应该用于装饰场景。NavDisplay 和 rememberSceneState 具有新的 API，用于添加 SceneDecoratorStrategies。(If9385, b/477669607, b/477670333)

bug 修复

修复了以下错误：将 SharedTransitionLayout 传递到 NavDisplay 或 rememberSceneState 并使用任何 OverlayScene 会导致崩溃，因为使用 SharedTransitionLayout 仅适用于作为 AnimatedContent 的一部分呈现的 NavEntries，而 OverlayScene 则在自己的窗口中单独呈现。(I1bb76, b/478664101)

依赖项更新

从 Navigation3 1.0.1 开始：Navigation3 现在依赖于 NavigationEvent 1.0.2。这修复了在 AndroidStudio 预览期间使用 NavDisplay 导致的 IllegalStateException。(Id7212, b/477149762)

版本 1.1.0-alpha03

2026 年 1 月 28 日

发布了 androidx.navigation3:navigation3-*:1.1.0-alpha03。版本 1.1.0-alpha03 中包含这些提交内容。

新功能

您现在可以通过 EntryProvider DSL 动态添加元数据，同时考虑条目键。(I942fb, b/474416976)

版本 1.1.0-alpha02

2026 年 1 月 14 日

发布了 androidx.navigation3:navigation3-*:1.1.0-alpha02。版本 1.1.0-alpha02 中包含这些提交内容。

新功能

SceneStrategy 现在通过新的 calculatedScene(Scene) 函数支持嵌套场景。这意味着可以自定义 SceneStrategy，以便为其他场景提供额外的功能。(I5df7c,b/440333896)

版本 1.1.0-alpha01

2025 年 12 月 3 日

发布了 androidx.navigation3:navigation3-*:1.1.0-alpha01。版本 1.1.0-alpha01 中包含这些提交内容。

API 变更

Navigation3 现在支持将场景视为共享元素对象。这意味着，当场景发生变化时，可以确保它们平稳过渡。您可以通过将 SharedTransitionScope 传递给 NavDisplay 或 rememberSceneState 来启用此功能。(I15868)

版本 1.0

版本 1.0.1

2026 年 2 月 11 日

发布了 androidx.navigation3:navigation3-*:1.0.1。版本 1.0.1 中包含这些提交内容。

依赖项更新

Navigation3 现在依赖于 NavigationEvent 1.0.2。这修复了在 AndroidStudio 预览期间使用 NavDisplay 导致的 IllegalStateException。(Id7212, b/477149762)

版本 1.0.0

2025 年 11 月 19 日

发布了 androidx.navigation3:navigation3-*:1.0.0。版本 1.0.0 中包含这些提交内容。

隆重推出 Navigation3！

Navigation3 库现已稳定！Navigation3 是 AndroidX Compose 的首个导航方法。
如需了解详情，请参阅我们的公告博文、访问资源并尝试配方。

版本 1.0.0-rc01

2025 年 11 月 5 日

发布了 androidx.navigation3:navigation3-*:1.0.0-rc01。版本 1.0.0-rc01 中包含这些提交内容。

bug 修复

NavDisplay 现在在 Scene 级别设置 LocalLifecycleOwner，以便场景作者通过检查 Lifecycle.State 是否为 RESUMED 来确定所有转换是否已完成。NavEntry 级别的 LocalLifecycleOwner 的行为保持不变：如果转场正在进行中，其上限仍为 STARTED；如果该 NavEntry 已从返回堆栈中弹出并且正在进行动画退出，则其上限还会为 CREATED。(I03113, b/454045829)

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

bug 修复

修复了使用 then 链接 SceneStrategy 时出现的无限循环问题。(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 参数来指示何时应弹出多个条目。相反，在场景请求弹出多个条目的罕见情况下，现在将连续多次调用 () -> Unit lambda。(Idedb5, b/446989346)
移除 NavEntryWrapper 类，并将其功能替换为最终的 NavEntry 类，该类具有采用包含新内容的 NavEntry 的新辅助构造函数。这样一来，便可继续支持使用新内容封装条目。(I7da2a, b/444447130)
创建并返回 NavEntryDecorator 的 navEntryDecorator 函数已被移除，并替换为 NavEntryDecorator 类，该类现在已公开并可用于子类化。(If81f8, b/444447434, b/447381176)
SavedStateNavEntryDecorator 已重命名为 SaveableStateHolderNavEntryDecorator，因为它使用 SaveableStateHolder 装饰条目。此外，装饰器还从函数重构为类，因为它在功能上是 NavEntryDecorator 的工厂。(Ie6013, b/447381176)
使用 SceneState 作为使用 NavDisplay 的替代方案的自定义显示不再需要使用 LocalEntriesToRenderInCurrentScene 组合本地，该组合本地现在是内部的。(Ic40ef, b/414668196)
从公共 API Surface 中移除了 SceneSetupNavEntryDecorator 和 rememberSceneSetupNavEntryDecorator()。此功能现在默认包含在内，无需您手动添加。(Ieae42, b/444479133)
NavEntry、DialogScene、SinglePaneScene 和 SceneState 现在都实现了 equals。(I96121)
场景接口具有新的元数据字段，用于为 NavDisplay 附加场景专用元数据。这样一来，场景便可替换 NavDisplay 上的元数据，例如使用转换。(I1fd96, b/443955625)
通过移除冗余的泛型类型参数，简化了 rememberNavBackStack 签名。该函数现在接受 vararg elements: NavKey。(I03e45)
NavDisplay 的默认动画现在是通用 API 的一部分，因此可以从所有平台调用这些动画。(I71af9, b/447147159)
将 EntryProviderBuilder 重命名为 EntryProviderScope，以准确反映该类是一个 Kotlin DSL，提供用于构建 NavEntries 的范围。(Ia7465)

bug 修复

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 界面现在提供新的默认 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)
所有场景 API 都已从 navigation3-ui 移至 navigation3-runtime。这意味着，它们现在可在 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)
将 NavigationEvent 的 swipeEdge 设为 @IntDef (Icee54, b/443950342)
将 NavBackStack 序列化限制为 Android。这样可以防止在非 Android 平台上出现运行时失败。对于多平台状态保存，请使用带有显式 SavedStateConfiguration 的 rememberNavBackStack 重载。(I1e418, b/420443609)

bug 修复

修复了在嵌套 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，后者会创建并返回使用提供的装饰器列表装饰的 NavEntries (I0fe1c, b/441328236)
NavBackStack 现在是 NavKey 类型的泛型。这样一来，应用和库便可为其返回堆栈定义自定义键类型，而不受限于 NavKey。(I4d190,Iad2f4, b/420443609)
NavBackStack 现在是 @kotlinx.serialization.Serializable，因此无需额外的样板代码，即可在进程终止和配置更改后保存和恢复导航状态。(I2c3cf, b/420443609)
RememberNavBackStack 已移至 commonMain，以确保在所有平台目标上提供该函数。(Id69e7, b/420443609)

bug 修复

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 和桌面）、Native（Linux、iOS、watchOS、macOS、MinGW）和 Web（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)

bug 修复

修复了导航会导致触发不正确的生命周期事件的问题。(I8bf6d, b/425901162, b/434109022)

已知问题

I8bf6d 引入了一个 bug，该 bug 导致 Lifecycle 基于场景而不是单个条目，这破坏了为 key 提供的 NavEntry 不是 String 或 NavEntry 未替换 contentKey 并将其设置为等于 key 的任何情况下的 Lifecycle（请注意，这样做会强制将您的键保存到 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)

bug 修复

修复了以下问题：由于系统未记住最近的场景，导致自定义场景无限期地重新计算。(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 的当前装饰器列表。这意味着，如果存在多个返回堆栈，则应沿着返回堆栈交换装饰器，以便保留返回堆栈上 NavEntries 的状态。否则，状态将被清除，就像条目被弹出（而不是交换）一样。(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 中包含这些提交内容。

bug 修复

Navigation3 不再清除已换出并替换为另一个 backStack 实例的 backStacks 的装饰器状态。(I28a42, b/415076044)

版本 1.0.0-alpha02

2025 年 5 月 23 日

发布了 androidx.navigation3:navigation3-*:1.0.0-alpha02。版本 1.0.0-alpha02 中包含这些提交内容。

bug 修复

修复了 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 提供界面层。开发者可以直接向 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 指南。