navigation3
| 最近更新时间 | 稳定版 | 候选版 | 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/430807423DeferredAnimatedContent使用DeferredTransition将过渡分为延迟阶段(通过defer)和自动阶段(通过animateTo),前者在滑动操作期间应用手动转换,后者在滑动操作提交时运行过渡。
已知问题
- 在过渡期间,共享元素会在退出场景(而非进入场景)中呈现。(b/582354988)
- 共享元素在延迟(手势)阶段不会跳转。
Navigation3 版本 1.2
版本 1.2.1
2026 年 11 月 4 日
发布了 androidx.navigation3:navigation3-*:1.2.1。1.2.1 版包含这些提交内容。
变更
compileSdk已从 37 降级到 36。1.2 版依赖于 Compose1.10,后者不需要compileSdk37。
版本 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 字符串或 AndroidIntent创建的深层链接请求。您可以使用通过requestExtrasDSL 和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可以使用requestExtrasDSL 进行实例化。(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'sT 上限已从Any?更改为Any。(I6bf1a)DeepLinkRequest构造函数字段uri现在默认为 null。辅助构造函数的uriString已重命名为uri。(Ia0f14、b/522194187)
bug 修复
ResultEffect现在使用rememberUpdatedState捕获最新的onResultlambda。(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
- 添加了
rememberResultEventBusAPI,该 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) - 添加了新的
requestExtrasDSL,作为构建 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,使其在匹配期间缺少必需参数时返回 nullUriMatchResult,而不是抛出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将返回 nullUriMatchResult,而不是抛出异常。(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)UriDeepLinkMatcherDeepLinkMatcher的一种特定实现,通过将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)
新功能
- 添加了
ResultEventBusAPI,以便通过新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)
Navigation3 版本 1.1
版本 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 修复
entryProviderDSL 现在会优先考虑使用键实例构建的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添加了NavMetadataKeyDialogKey,以便与 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,以便它们可以与新的metadataDSL 搭配使用,从而向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)
依赖项更新
- 从
Navigation31.0.1 开始:Navigation3现在依赖于NavigationEvent1.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 包含这些提交内容。
新功能
- 现在,您可以通过
EntryProviderDSL 动态添加元数据,同时考虑条目键。(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现在依赖于NavigationEvent1.0.2。这修复了在AndroidStudio预览期间使用NavDisplay导致的IllegalStateException问题。(Id7212、b/477149762)
版本 1.0.0
2025 年 11 月 19 日
发布了 androidx.navigation3:navigation3-*:1.0.0。1.0.0 版包含这些提交内容。
Navigation3 隆重推出!
版本 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的onBacklambda 不再提供count: Int参数来指示何时应弹出多个条目。现在,在极少数情况下,如果您的 Scene 请求弹出多个条目,系统会连续多次调用() -> Unitlambda。(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)
- 改进了
entryProviderDSL 的泛型处理。如果您之前导入了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)
依赖项变更
- 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,导致生命周期基于场景而非单个条目,这会破坏生命周期,导致提供给
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字段标识,该字段由新的contentKeyFactorylambda 生成,默认为从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 指南。