此页面由 Cloud Translation API 翻译。

navigation3

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

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

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2025 年 10 月 8 日	-	-	-	1.0.0-alpha11

声明依赖项

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

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

Groovy

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

Kotlin

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

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

反馈

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

创建新问题

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

此工件没有版本说明。

版本 1.0

版本 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 现在，您可以根据 Transition 的 currentState 和 targetState 来自定义 Scene 的转场效果。（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。这意味着它们现在可在 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 和桌面）、原生（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 导致生命周期基于场景而非单个条目，这会破坏任何以下情况下的生命周期：提供给 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)

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 的当前装饰器列表。这意味着，如果存在多个返回堆栈，装饰器应沿着返回堆栈进行交换，以保留返回堆栈上 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 中包含这些提交内容。

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