Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

navigation3

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

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

最近更新时间	稳定版	候选版	Beta 版	Alpha 版
2026 年 9 月 23 日	1.2.0	-	-	1.3.0-alpha01

声明依赖项

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

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

Groovy

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

Kotlin

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

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

反馈

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

创建新问题

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

版本 1.3

版本 1.3.0-alpha01

2026 年 9 月 23 日

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

** 问题修复 **

通过迁移到 DeferredAnimatedContent 并解决过渡切换问题，修复了 NavDisplay 中的预测性返回动画切换问题。I145eaedd b/430807423

此工件没有版本说明。

Navigation3 版本 1.2

版本 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 以支持将 ResultEventBus 提升到 ResultEventBusNavEntryDecorator 之外并将其传递给 rememberResultEventBusNavEntryDecorator。
传入的结果可以作为状态通过 ResultEventBus#conflateAsState 进行访问，也可以作为结果流通过 ResultEffect 进行收集。

深层链接 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，用于在成功匹配深层链接后构建合成返回堆栈。可以通过 DeepLinkMatcher.withBackStack 扩展函数创建 BackStackMatcher。

预测性返回处理

添加了 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 DSL 实例化 RequestExtras。（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 类，该类接受两个参数：匹配器实例和一个提供输入匹配器的匹配结果并返回返回堆栈的 build lambda。成功匹配后，BackStackMatcher 会返回一个扩展 WrappedMatchResult 的 BackStackMatchResult，其中包含原始匹配结果以及使用 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 fragment 的 UriDeepLinkMatcher 文档，以明确说明包含通配符的 fragment 将匹配任何输入，但输入不会被提取为实参。（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 map。（Id0c90、[b/513200887]
添加了 MimeTypeExtrasKey 和 mimeTypeExtra 函数，以创建包含 MimeTypeExtrasKey 的 extras 地图。（I85131、b/513200887）

DeepLinkMatcher

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

API 变更

DeepLinkRequest

移除 fromAction 工厂函数。如需创建与操作相关联的请求，请使用新的 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 用于仅使用 DeepLinkMatcher.Filter 匹配深层链接，通过 Boolean 进行匹配。（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）

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 修复

entryProvider DSL 现在优先考虑使用键实例（例如 entry(key = userKey) { ... }）构建的 NavEntry，而不是使用键类（例如 entry<UserKey>{ ... }）构建的 NavEntry。（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，该版本移除了检查模式下的 no-op NavigationEventHandler，以在 Android Studio 预览版中启用预测性返回。

版本 1.1.2

2026 年 5 月 19 日

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

bug 修复

将 NavigationEvent 依赖项提升至 1.1.1，该版本移除了检查模式下的 no-op 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 - Introduction of SceneDecoratorStrategy to support uses cases such as decorating scenes with common UI components or sharing state across scenes.

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，以便与元数据 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 参数来指示何时应弹出多个条目。现在，如果您的场景请求弹出多个条目，() -> 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 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，导致生命周期基于场景而非单个条目，这会破坏任何以下情况下的生命周期：提供给 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 指南。