将 Jetpack Navigation 迁移到 Navigation Compose

借助 Navigation Compose API,您可以在 Compose 应用中的可组合项之间导航,同时利用 Jetpack Navigation 的组件、基础架构和功能。

本页介绍了如何从基于 Fragment 的 Jetpack Navigation 迁移到 Navigation Compose,这只是将基于 View 的界面迁移到 Jetpack Compose 的更大迁移过程的一部分。

迁移先决条件

当您能够将所有 fragment 替换为相应的界面可组合项后,就可以迁移到 Navigation Compose。屏幕可组合项可以包含 Compose 和 View 内容的混合,但所有导航目的地都必须是可组合项,才能启用 Navigation Compose 迁移。在此之前,您应继续在互操作性 View 和 Compose 代码库中使用基于 fragment 的导航组件。如需了解详情,请参阅 Navigation Interoperability 文档

在仅使用 Compose 的应用中使用 Navigation Compose 并非前提条件。只要您保留 fragment 来托管可组合项内容,就可以继续使用基于 fragment 的 Navigation 组件

迁移步骤

无论您是遵循我们的推荐迁移策略还是采用其他方法,最终都会达到一个阶段,即所有导航目的地都是屏幕可组合项,而 fragment 仅用作可组合项容器。在此阶段,您可以迁移到 Navigation Compose。

如果您的应用已遵循 UDF 设计模式和我们的架构指南,那么迁移到 Jetpack Compose 和 Navigation Compose 应该不需要对应用的其他层进行重大重构,界面层除外。

如需迁移到 Navigation Compose,请按以下步骤操作:

  1. Navigation Compose 依赖项添加到您的应用。
  2. 创建一个 App-level 可组合项,并将其添加到 Activity 作为 Compose 入口点,替换 View 布局的设置:

    class SampleActivity : ComponentActivity() {
    
        override fun onCreate(savedInstanceState: Bundle?) {
            super.onCreate(savedInstanceState)
            // setContentView<ActivitySampleBinding>(this, R.layout.activity_sample)
            setContent {
                SampleApp(/* ... */)
            }
        }
    }

  3. 为每个导航目的地创建类型。对于不需要任何数据的目的地,请使用 data object;对于需要数据的目的地,请使用 data classclass

    @Serializable data object First
    @Serializable data class Second(val id: String)
    @Serializable data object Third
    

  4. 在需要引用它的所有可组合项都可以访问的位置设置 NavController(通常位于 App 可组合项内)。此方法遵循状态提升的原则,可让您将 NavController 用作可组合屏幕之间导航和维护返回堆栈的可信来源:

    @Composable
    fun SampleApp() {
        val navController = rememberNavController()
        // ...
    }

  5. App 可组合项内创建应用的 NavHost 并传递 navController

    @Composable
    fun SampleApp() {
        val navController = rememberNavController()
    
        SampleNavHost(navController = navController)
    }
    
    @Composable
    fun SampleNavHost(
        navController: NavHostController
    ) {
        NavHost(navController = navController, startDestination = First) {
            // ...
        }
    }

  6. 添加 composable 目的地以构建导航图。如果每个屏幕之前都已迁移到 Compose,则此步骤仅包含将这些屏幕可组合项从 fragment 提取到 composable 目的地:

    class FirstFragment : Fragment() {
    
        override fun onCreateView(
            inflater: LayoutInflater,
            container: ViewGroup?,
            savedInstanceState: Bundle?
        ): View {
            return ComposeView(requireContext()).apply {
                setContent {
                    // FirstScreen(...) EXTRACT FROM HERE
                }
            }
        }
    }
    
    @Composable
    fun SampleNavHost(
        navController: NavHostController
    ) {
        NavHost(navController = navController, startDestination = First) {
            composable<First> {
                FirstScreen(/* ... */) // EXTRACT TO HERE
            }
            composable<Second> {
                SecondScreen(/* ... */)
            }
            // ...
        }
    }

  7. 如果您遵循了设计 Compose 界面(特别是应如何将 ViewModel 和导航事件传递给可组合项)中的指南,那么下一步就是更改向每个屏幕可组合项提供 ViewModel 的方式。您通常可以通过 hiltViewModel 使用 Hilt 注入及其与 Compose 和 Navigation 的集成点:

    @Composable
    fun FirstScreen(
        // viewModel: FirstViewModel = viewModel(),
        viewModel: FirstViewModel = hiltViewModel(),
        onButtonClick: () -> Unit = {},
    ) {
        // ...
    }

  8. 将所有 findNavController() 导航调用替换为 navController 调用,并将这些调用作为导航事件传递给每个可组合屏幕,而不是传递整个 navController。此方法遵循了将可组合函数中的事件公开给调用方的最佳实践,并将 navController 保持为单一可信来源。

    您可以通过创建为该目的地定义的路线类的实例,将数据传递给目的地。然后,您可以直接从目的地返回堆栈条目中获取它,也可以使用 SavedStateHandle.toRoute()ViewModel 中获取它。

    @Composable
    fun SampleNavHost(
        navController: NavHostController
    ) {
        NavHost(navController = navController, startDestination = First) {
            composable<First> {
                FirstScreen(
                    onButtonClick = {
                        // findNavController().navigate(firstScreenToSecondScreenAction)
                        navController.navigate(Second(id = "ABC"))
                    }
                )
            }
            composable<Second> { backStackEntry ->
                val secondRoute = backStackEntry.toRoute<Second>()
                SecondScreen(
                    id = secondRoute.id,
                    onIconClick = {
                        // findNavController().navigate(secondScreenToThirdScreenAction)
                        navController.navigate(Third)
                    }
                )
            }
            // ...
        }
    }

  9. 移除所有 Fragment、相关 XML 布局、不必要的导航和其他资源,以及过时的 Fragment 和 Jetpack Navigation 依赖项。

您可以在设置文档中找到相同的步骤,以及更多与 Navigation Compose 相关的详细信息。

常见用例

无论您使用哪个 Navigation 组件,相同的导航原则都适用

迁移的常见用例包括:

如需详细了解这些用例,请参阅使用 Compose 进行导航

在导航时检索复杂数据

我们强烈建议在导航时不要传递复杂的数据对象。在执行导航操作时,应改为将最少量的必要信息(例如唯一标识符或其他形式的 ID)作为参数进行传递。您应将复杂对象以数据的形式存储在单一可信来源(例如数据层)中。如需了解详情,请参阅在导航时检索复杂数据

如果您的 fragment 将复杂对象作为参数传递,请考虑先重构代码,以便从数据层存储和提取这些对象。如需查看示例,请参阅 Now in Android 代码库

限制

本部分介绍 Navigation Compose 的当前限制。

逐步迁移到 Navigation Compose

目前,您无法在代码中同时使用 Navigation Compose 和 fragment 作为目的地。如需开始使用 Navigation Compose,您的所有目的地都需要是可组合项。您可以在问题跟踪器上跟踪此功能请求

过渡动画

Navigation 2.7.0-alpha01 开始,NavHost 现已直接支持设置自定义转换(以前来自 AnimatedNavHost)。如需了解详情,请仔细阅读版本说明

了解详情

如需详细了解如何迁移到 Navigation Compose,请参阅以下资源:

  • Navigation Compose Codelab:通过动手操作 Codelab 学习 Navigation Compose 的基础知识。
  • “Now in Android”代码库:这是一个完全使用 Kotlin 和 Jetpack Compose 构建的功能齐全的 Android 应用,遵循 Android 设计和开发最佳实践,并包含 Navigation Compose。
  • 将 Sunflower 迁移到 Jetpack Compose:这篇博文记录了 Sunflower 示例应用从 View 迁移到 Compose 的过程,其中还包括迁移到 Navigation Compose 的过程。
  • 适用于每个屏幕的 Jetnews:一篇博客文章,记录了 Jetnews 示例的重构和迁移,以支持使用 Jetpack Compose 和 Navigation Compose 的所有屏幕。