navigation3

  
Navigation 3 是一个专为与 Compose 搭配使用而设计的新导航库。
最近更新时间 稳定版 候选版 Beta 版 Alpha 版
2026 年 11 月 4 日 1.2.1 - - 1.3.0-alpha04

声明依赖项

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

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

Groovy

dependencies {
    implementation "androidx.navigation3:navigation3-runtime:1.3.0-alpha04"
    implementation "androidx.navigation3:navigation3-ui:1.3.0-alpha04"
}

Kotlin

dependencies {
    implementation("androidx.navigation3:navigation3-runtime:1.3.0-alpha04")
    implementation("androidx.navigation3:navigation3-ui:1.3.0-alpha04")
}

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

反馈

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

创建新问题

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

版本 1.3

版本 1.3.0-alpha04

2026 年 11 月 4 日

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

bug 修复

  • 修复了以下问题:当共享 NavEntry 被弹出,然后在弹出完成之前再次被推送时,该 未在屏幕上呈现。(I6a482)

版本 1.3.0-alpha03

2026 年 10 月 21 日

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

与 1.3.0-alpha02 相比没有变化

版本 1.3.0-alpha02

2026 年 10 月 7 日

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

API 变更

  • SceneInfo 类添加了 title 和 url 属性,这些属性会根据场景的最后一个 NavEntry's 元数据自动填充。使用 TitleMetadataKey 和 UrlMetadataKey 在条目的元数据中定义目标页面标题和网址。(I78a20、b/542693522)

版本 1.3.0-alpha01

2026 年 9 月 23 日

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

bug 修复

  • 通过迁移到 DeferredAnimatedContent 并解决过渡切换问题,修复了 NavDisplay 中的预测性返回动画切换问题。I145eaedd b/430807423
    • DeferredAnimatedContent 使用 DeferredTransition 将过渡分为延迟阶段(通过 defer)和自动阶段(通过 animateTo),前者在滑动操作期间应用手动转换,后者在滑动操作提交时运行过渡。

已知问题

  • 在过渡期间,共享元素会在退出场景(而非进入场景)中呈现。(b/582354988)
  • 共享元素在延迟(手势)阶段不会跳转。

版本 1.2.1

2026 年 11 月 4 日

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

变更

  • compileSdk 已从 37 降级到 36。1.2 版依赖于 Compose 1.10,后者不需要 compileSdk 37。

版本 1.2.0

2026 年 9 月 23 日

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

1.2.0 现已稳定!

自 1.1.0 以来的重要变更

Result API

  • 借助此新 API,您可以使用 LocalResultEventBus 和 ResultEventBusNavEntryDecorator 提供的 ResultEventBus 在 NavEntries 之间传递结果。
  • 添加了 rememberResultEventBus,以支持在 ResultEventBusNavEntryDecorator 之外提升 ResultEventBus 并将其传递给 rememberResultEventBusNavEntryDecorator。
  • 传入的结果可以作为状态通过 ResultEventBus#conflateAsState 访问,也可以作为结果流通过 ResultEffect 收集。

Deep Link API

Navigation3 现在通过 DeepLinkRequest、DeepLinkUri 和 DeepLinkMatcher 支持 androidx.navigation3.runtime.deeplink 中的 Kotlin Multiplatform (KMP) 深层链接。

  • DeepLinkRequest 和 RequestExtras:表示通过 DeepLinkUri、URI 字符串或 Android Intent 创建的深层链接请求。您可以使用通过 requestExtras DSL 和 RequestExtrasKey<T> 构建的类型安全 RequestExtras 容器来附加其他请求元数据。
  • DeepLinkMatcher:表示可与 DeepLinkRequest 匹配的深层链接。每个匹配器实例都与支持此深层链接的导航键相关联。一个导航键可以与多个匹配器相关联。如果匹配成功,调用 DeepLinkMatcher.match 将返回一个包含关联导航键的 MatchResult。DeepLinkMatcher 有两种默认实现:UriDeepLinkMatcher 用于根据 Uri 匹配深层链接,StaticKeyDeepLinkMatcher 用于仅通过 DeepLinkMatcher.Filter 匹配深层链接(通过布尔值进行匹配)。
  • BackStackMatcher:一个 DeepLinkMatcher,用于在深层链接匹配成功后构建合成返回堆栈。BackStackMatcher 可通过 DeepLinkMatcher.withBackStack 扩展函数创建。

预测性返回处理

  • 添加了 NavigationBackHandler 和 rememberNavigationEventState,以简化 SceneState 与预测性返回处理(onBackCompleted 和 onBackCancelled)的连接。这样,自定义界面组件便可支持标准返回导航和预测性返回手势,而无需手动计算返回堆栈增量。
  • 改进了预测性返回过渡效果,包括支持在前进动画播放期间触发预测性返回手势。

其他更改

  • NavEntry.contentKey 现在默认由 key.toString() 和 key::class.toString() 组合而成,可防止在不同接口之间共享相同简单名称的 data object 键之间发生键冲突。
  • EntryProvider 现在会优先根据键实例(而非键类型)进行匹配。
  • 添加了 lint 检查,以确保 Scene 实现是 data class 或实现 equals 和 hashCode。

版本 1.2.0-rc01

2026 年 9 月 9 日

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

bug 修复

  • 不允许在深层链接 URI 模式中使用重复的占位符名称。(I8985c、b/522343165)

版本 1.2.0-beta01

2026 年 8 月 26 日

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

API 变更

  • 将 DeepLinkRequest.extras 从 Map<String, Any> 重构为新的类型安全映射类 RequestExtras,该类存储 RequestExtrasKey<T> 到 T 的对。RequestExtras 可以使用 requestExtras DSL 进行实例化。(Ic929d、b/543883369)

bug 修复

  • 修复了以下问题:在向前过渡期间触发的预测性返回手势不会根据滑动进度显示动画。现在,预测性返回将正常播放动画并完成。(Icdcb0、b/456218398)
  • 添加了 lint 检查,以确保 Scene 实现是数据类,或实现 equals 和 hashcode,从而确保在适当情况下使用相同的 Scene。(Ibdf0d、b/542316099)
  • NavEntry.contentKey 现在默认为 key.toString() 和 key::class.toString() 的组合。这样可以确保名称相同但实现不同接口的数据对象不再具有相同的 contentKey。不过,JS 平台的 key::class 仅返回简单类名称,而不是完全限定名称,因此 JS 平台仍应为具有重复名称的数据对象实现自定义 contentKey。(I1fbbb、b/512534342)
  • 修复了在多个弹出转换正在进行时,SaveableStateProvider 针对快速返回导航期间使用的重复键抛出 IllegalArgumentException 的问题。(I4d728、b/516312097)

版本 1.2.0-alpha07

2026 年 7 月 29 日

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

API 变更

  • 添加了抽象 WrappedMatchResult 类,用于封装另一个 DeepLinkMatcher.MatchResult。这样,您就可以在另一个匹配结果的基础上叠加自定义匹配结果。(I7d4dc、b/470282247)
  • 添加了新的 BackStackMatcher 类,该类接受两个参数:一个匹配器实例,以及一个提供输入匹配器的匹配结果并返回返回堆栈的构建器 lambda。如果匹配成功,BackStackMatcher 会返回一个 BackStackMatchResult,该 扩展了 WrappedMatchResult,其中包含原始匹配结果以及使用 lambda 构建的返回堆栈。BackStackMatcher 只能使用新的 DeepLinkMatcher.withBackStack 扩展函数创建。(Ibf987、b/470282247)

  • 添加了扩展 KSerializer 的抽象 DeepLinkSerializer 类,用于将 value : T 编码和解码为 String。DeepLinkSerializer 可用于序列化非基元深层链接参数。与 rememberSaveable 和 rememberNavBackStack 兼容。(Id3c9f、b/470282247)

  • DeepLinkMatcher 添加了第二个类型形参 out R : DeepLinkMatcher.MatchResult<T>,以便开发者可以访问 DeepLinkMatcher.match() 返回的子类化 MatchResult 的属性,而无需进行类型转换。(I693d3、b/470282247)

  • DeepLinkMatcher.MatchResult's T 上限已从 Any? 更改为 Any。(I6bf1a)

  • DeepLinkRequest 构造函数字段 uri 现在默认为 null。辅助构造函数的 uriString 已重命名为 uri。(Ia0f14、b/522194187)

bug 修复

  • ResultEffect 现在使用 rememberUpdatedState 捕获最新的 onResult lambda。(I7d2a3、b/531709234)
  • 修复了空路径段的深层链接匹配问题。如果实参类型为 String,则空路径将被视为空字符串值。否则,空路径将被视为未提供任何值,并将回退到默认值。如果没有默认值,匹配将会失败。(I56575、b/535298128)
  • 在 DeepLinkRequest.uri 中添加了对空查询值的支持。如果实参为 String 类型,则空值将被视为字面量空字符串。否则,空值将被视为未提供值,匹配将尝试回退到默认值。如果没有默认值,匹配将会失败。(I30343、b/535127459)
  • EntryProvider 现在会优先根据键实例(而非键类型)进行匹配。(Ib5ec9、b/533331924)
  • SceneState 现在可以从最顶层的非叠加场景开始正确计算之前的场景。(I91915、b/513630541)

版本 1.2.0-alpha06

2026 年 7 月 15 日

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

bug 修复

  • 修复了有关 URI 片段的 UriDeepLinkMatcher 文档,以阐明带有通配符的片段将与任何输入匹配,但输入不会作为参数提取。(I5ad9b、b/524677091)
  • 修复了以下问题:如果 URI 格式不包含架构或不以双斜杠开头,则 UriDeepLinkMatcher 无法与请求匹配。例如,www.example.com/home 现在会与 http://www.example.com/home 匹配。(Ia6b65、b/522791926)

版本 1.2.0-alpha05

2026 年 7 月 1 日

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

新 API

  • 添加了 rememberResultEventBus API,该 API 会返回可传递给 rememberResultEventBusNavEntryDecorator 的 ResultEventBus。这样就可以将 ResultEventBus 提升到 ResultEventBusNavEntryDecorator 之外。(Ia655b、b/516995400)

DeepLinkRequest

  • 添加了两个与 KMP 兼容的构造函数,一个接受 DeepLinkUri,另一个接受原始字符串 URI。(I3c088、b/513200887、b/522194187)
  • (仅限 Android)添加了接受 Intent 的构造函数。(Ia0498、b/513200887、b/522194187)
  • 所有构造函数都有一个额外的 extras 字段,供 Map<String, Any> 附加额外的请求信息。(If81d5、b/513200887)
  • 添加了新的 requestExtras DSL,作为构建 extra 映射的类型安全方式。DSL 提供了一个 put 函数,用于存储 RequestExtrasKey 到 Any 的键值对。Map<String, Any>.get(key) 扩展函数可用于通过 RequestExtrasKey 从映射中读取数据(I5091c, b/513200887)
  • (仅限 Android)添加了 ActionExtrasKey 和 actionExtra 函数,用于创建包含 ActionExtrasKey 的 extra 映射。(Id0c90、[b/513200887]
  • 添加了 MimeTypeExtrasKey 和 mimeTypeExtra 函数,用于创建包含 MimeTypeExtrasKey 的 extra 映射。(I85131、b/513200887)

DeepLinkMatcher

  • 添加了 DeepLinkMatcher.mimeTypeFilter 和 DeepLinkMatcher.actionFilter 函数,用于创建按 mimeType 或 action 过滤 DeepLinkRequest 的 DeepLinkMatcher.Filters(仅限 Android)。这两个过滤条件均通过字符串相等性进行匹配,且不区分大小写。(Ie7e67、b/513191950)

API 变更

DeepLinkRequest

  • 移除 fromAction 工厂函数。如需创建与 Action 关联的请求,请使用新的 DeepLinkRequest.extras 字段。(Id0c90, b/513200887)
  • 移除了 fromMimeType 工厂函数。如需创建与 mimeType 关联的请求,请使用新的 DeepLinkRequest.extras 字段。(I85131、b/513200887)
  • (仅限 Android)移除了 fromIntent 工厂函数。替换为接受 Intent 和 extra 映射的新构造函数。(Ia0498、b/513200887、b/522194187)
  • 移除了工厂函数 fromUri 和 fromUriString。取而代之的是接受 DeepLinkUri 或原始字符串 URI 的新构造函数。(Id5b6f、b/522194187)
  • DeepLinkMatcher、DeepLinkMatcher.MatchResult 及其子类现在采用协变 T (out T),因此分层键在与 Matcher 一起使用时不需要进行类型转换。(I1e453、b/525094876)
  • 实参映射的 UriMatchResult 构造函数形参现在默认为空映射。(I3acdd)
  • DeepLinkMatcher.Filter 抽象类现在是一个函数式接口。filter 构造函数字段已被移除,应改为直接在子类中传递。(I9eb7d、b/522194187)

bug 修复

  • 修复了以下问题:在弹出到包含 lambda 值的嵌套元数据的条目时,弹出的条目会立即消失。(Idb872、b/520494430)
  • 修复了 UriDeepLinkMatcher,使其在匹配期间缺少必需参数时返回 null UriMatchResult,而不是抛出 MissingFieldException。(I5322f、b/524663005)
  • 包含采用 https 架构的 URI 的 UriDeeplinkMatcher 只能与同样采用 https 架构的请求匹配。(Ibfe22、b/522304329)
  • 修复了 UriDeepLinkMatcher,以便在将 DeepLinkRequest 与 UriDeepLinkMatcher 进行匹配时,正确地将 http 架构标识为与 https 正匹配。(I3a62b、b/518804264)
  • 现在,当两个结果相等时,DeepLinkMatcher.MatchResult 比较器默认返回 0。(I48ddb、b/518841353)
  • 现在,当匹配请求因缺少必需参数而失败时,UriDeepLinkMatcher 将返回 null UriMatchResult,而不是抛出异常。(I669a7、b/470282247、b/512923412)

版本 1.2.0-alpha04

2026 年 6 月 3 日

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

bug 修复

  • 修复了叠加层动画问题:当弹出嵌套叠加层(例如 ModalBottomSheet)上方的叠加层时,嵌套叠加层会意外重新播放动画。(Ia2b9e、b/502624496)

版本 1.2.0-alpha03

2026 年 5 月 19 日

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

新功能

Navigation 3 现在支持使用 DeepLinkRequest 和 DeepLinkMatcher 的深层链接:

  • DeepLinkRequest 请求的深层链接,其中包含 DeepLinkUri 以及可选的 mimeType 或 action(仅限 Android)。除了新类之外,还有配套函数,可用于创建具有 uri、mimeType 或 action 的实例。Android 平台还提供了一个辅助工具,用于根据 intent 构建请求。(Iaaac9、b/470282247)

    val uriOnlyRequest = DeepLinkRequest.fromUriString("https://sampledeeplink.com/home")
    val uriAndMimeRequest = DeepLinkRequest.fromUriString(
      "https://sampledeeplink.com/user/profile?id=123",
      "image/png"
    )
    
  • DeepLinkMatcher 表示可与 DeepLinkRequest 匹配的深层链接。每个匹配器实例都与支持此深层链接的导航键相关联。一个导航键可以与多个匹配器相关联。如果匹配成功,调用 DeepLinkMatcher.match 将返回一个包含关联导航键的 MatchResult。默认提供两种 DeepLinkMatcher 实现:UriDeepLinkMatcher 用于根据 Uri 匹配深层链接,StaticKeyDeepLinkMatcher 用于仅通过 Boolean 匹配 DeepLinkMatcher.Filter 的深层链接。(I3798e、b/470282247)

  • UriDeepLinkMatcher DeepLinkMatcher 的一种特定实现,通过将 DeepLinkUri 与可序列化的导航键进行匹配来处理深层链接。它支持基元类型或基元集合(例如列表、数组和集)的深层链接参数。(I1520b、b/470282247)

    @Serializable
    data class UserKey(val id: Int): NavKey
    
    // declare a deep link supported by UserKey
    val userMatcher = UriDeepLinkMatcher(
      uriPattern = "www.sampledeeplink.com/user?userId={id}",
      serializer = serializer<UserKey>()
    )
    
    // handle a requested deep link with fallback key
    val key = userMatcher.match(deepLinkRequest)?.key ?: HomeKey
    
  • 添加了 DeepLinkUri,它是 android.net.Uri 的 Kotlin 多平台版本 (Id4725, b/470282247)

API 变更

  • 已升级到 compileSdk 37,以与 Compose 的 compileSdk 保持一致

bug 修复

  • 修复了显示多个叠加层时 AnimatedBottomSheetSample 的 IllegalArgumentException 问题。示例 SceneStrategy 现在可以正确计算最后一个非 OverlayScene,并将其显示在所有叠加场景下。(If2281、b/506733412)
  • 将 NavigationEvent 依赖项升级到了 1.1.1,这会移除处于检查模式时的空操作 NavigationEventHandler,以便在 Android Studio 预览中启用预测性返回手势。(I487fd)

版本 1.2.0-alpha02

2026 年 4 月 22 日

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

API 变更

  • 将 onBack 重命名为 onBackCompleted,并向 NavigationBackHandler 添加了 onBackCancelled,以支持处理已取消的返回手势。(I92741)
  • 添加了 NavigationBackHandler,以简化使用 SceneState 时对返回手势和预测性返回的处理。这样,开发者就可以更轻松地创建支持标准返回导航和预测性手势的自定义界面组件,而无需手动计算返回堆栈增量。(I6a055)
  • 添加了 rememberNavigationEventState,可简化将 SceneState 与预测性返回处理相关联的过程。(Iae49c)

新功能

  • 添加了 ResultEventBus API,以便通过新 ResultEventBusNavEntryDecorator 提供的 LocalResultEventBus 在 NavEntry 之间传递结果。传入的结果可以作为状态(使用 ResultEventBus#conflateAsState)或结果流(使用 ResultEffect)进行评估。

版本 1.2.0-alpha01

2026 年 4 月 8 日

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

bug 修复

  • 从 OverlayScene 访问 LocalNavAnimatedContentScope 将不再导致 IllegalStateException,因为 OverlayScenes 现在提供了空操作 LocalAnimatedContentScope。(I2f00c、b/486067688)

版本 1.1.7

2026 年 8 月 26 日

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

bug 修复

  • 修复了以下问题:在向前过渡期间触发的预测性返回手势不会根据滑动进度显示动画。现在,预测性返回将正常播放动画并完成。(Icdcb0、b/456218398)

1.1.6 版

2026 年 8 月 12 日

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

bug 修复

  • NavEntry.contentKey 现在默认为 key.toString() 和 key::class.toString() 的组合。这样可以确保名称相同但实现不同接口的数据对象不再具有相同的 contentKey。不过,JS 平台的 key::class 仅返回简单类名称,而不是完全限定名称,因此 JS 平台仍应为具有重复名称的数据对象实现自定义 contentKey。(I1fbbb、b/512534342)
  • 修复了以下问题:由于从返回堆栈中快速弹出,多个弹出转换同时进行时,SaveableStateHolder 会因键重复使用而抛出 IllegalArgumentException。(I4d728、b/516312097)

版本 1.1.5

2026 年 7 月 29 日

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

bug 修复

  • entryProvider DSL 现在会优先考虑使用键实例构建的 NavEntry(例如 entry(key = userKey) { ... }),而不是使用键类构建的 NavEntry(例如 entry<UserKey>{ ... })。(Ib5ec9, b/533331924)

1.1.4 版

2026 年 7 月 1 日

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

bug 修复

  • 修复了以下问题:在弹出到包含 lambda 值的嵌套元数据的条目时,弹出的条目会立即消失。(Idb872、b/520494430)

版本 1.1.3

2026 年 6 月 17 日

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

bug 修复

  • 修复了叠加层动画问题:当弹出嵌套叠加层(例如 ModalBottomSheet)上方的叠加层时,嵌套叠加层会意外重新播放动画。(Ia2b9e、b/502624496)

  • 将 NavigationEvent 依赖项升级到 1.1.2,该版本在检查模式下移除了空操作 NavigationEventHandler,以便在 Android Studio 预览中启用预测性返回手势。

版本 1.1.2

2026 年 5 月 19 日

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

bug 修复

  • 将 NavigationEvent 依赖项升级到了 1.1.1,该版本移除了处于检查模式时的空操作 NavigationEventHandler,以便在 Android Studio 预览中启用预测性返回手势。

版本 1.1.1

2026 年 4 月 22 日

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

bug 修复

  • 从 OverlayScene 访问 LocalNavAnimatedContentScope 将不再导致 IllegalStateException,因为 OverlayScenes 现在提供了空操作 LocalAnimatedContentScope。(I2f00c、b/486067688)

版本 1.1.0

2026 年 4 月 8 日

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

1.1.0 现已稳定!

自 1.0.0 以来的重要变更

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

SceneDecoratorStrategy - 引入了 SceneDecoratorStrategy,以支持使用常见界面组件装饰场景或跨场景共享状态等用例。

NavMetadata DSL - Navigation3 现在提供了一种新的类型安全元数据 DSL。DSL 使用新的 MetadataKey 接口,该接口允许定义要提供给元数据映射的键和值类型。此版本还为 NavDisplay 过渡添加了新的 NavMetadataKeys,以便它们可以与新的元数据 DSL 搭配使用,从而向 NavDisplay 添加过渡。

OverlayScene 动画 - OverlayScene 接口新增了 onRemoved 挂起回调。当与场景关联的键从返回堆栈中移除后,但在其离开组合之前,系统会调用此回调。这样,在从组合中移除叠加层场景之前,在 onRemoved 中调用的退出动画便可完成。

其他变更 - NavDisplay 和 rememberSceneState 现在采用 List<SceneStrategy>,而不是之前由 then 中缀链接的单个 SceneStrategy 参数。 - 现在,您可以通过 EntryProvider DSL 动态添加元数据,同时考虑条目键。

版本 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,以便与 Metadata 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 接口,该接口允许定义要提供给元数据映射的键和值类型。此版本还为 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

October 22, 2025

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

API 变更

  • SceneStrategyScope 现在只有一个无参数公共构造函数,适合单独测试 SceneStrategy 和返回的 Scene。对于更复杂的用例,请使用 rememberSceneState()。(I8440c、b/451679047)

bug 修复

  • 修复了将 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 已重命名为 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 附加场景专属元数据。这样,Scene 就可以替换 NavDisplay 上的元数据,例如使用过渡。(I1fd96、b/443955625)
  • 通过移除多余的泛型类型参数来简化 rememberNavBackStack 签名。该函数现在接受 vararg elements: NavKey。(I03e45)
  • NavDisplay 的默认动画现在是通用 API 的一部分,允许从所有平台调用。(I71af9、b/447147159)
  • 将 EntryProviderBuilder 重命名为 EntryProviderScope,以准确反映该类是提供构建 NavEntries 的作用域的 Kotlin DSL。(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,后者会创建并返回使用提供的装饰器列表修饰的 NavEntry (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)

依赖项变更

版本 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 引入了一个 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 更新

API 变更

  • SavedStateNavEntryDecorator 现在使用 SaveableStateProvider 中内置的 SaveableStateRegistry 来保存和恢复状态。(If8d9a)
  • predictivePopTransitionSpec 现在将滑动的边缘作为参数提供,让您可以根据用户开始预测性返回手势的边缘来自定义过渡。(I753a8)

bug 修复

  • 修复了以下问题:由于系统无法记住最近的场景,导致自定义场景会被无限次重新计算。(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 包含这些提交内容。

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