[Android 从零到一] Navigation Component：让页面跳转更清晰

在 Android 项目里，页面跳转一开始通常很简单：从 A 页面打开 B 页面，写一个 Intent；Fragment 之间切换，就在 FragmentTransaction 里 replace 一下。项目小的时候这样没问题，但随着页面数量变多，跳转关系、返回栈、参数传递、深链接都会慢慢变复杂。

Navigation Component 就是 Jetpack 提供的一套导航管理方案。它不是为了替代 Activity 或 Fragment，而是把“页面之间怎么走”这件事集中管理起来，让页面跳转更清楚，也更容易维护。

1. 为什么需要 Navigation Component

先看传统写法里常见的几个问题。

比如 Fragment 跳转：

supportFragmentManager.beginTransaction()
    .replace(R.id.container, DetailFragment())
    .addToBackStack(null)
    .commit()

这段代码能跑，但问题也明显：

• 跳转逻辑散落在不同页面里
• 返回栈需要自己管理
• 页面参数通常靠 Bundle 手动传递
• 页面关系不直观，维护成本会变高
• 深链接、底部导航、多返回栈场景容易写乱

Navigation Component 的核心思路是：把导航关系抽出来，放到一个导航图里，由 NavController 统一执行跳转。

也就是说，页面只关心“我要去哪里”，具体怎么管理返回栈、怎么找到目标页面、怎么传参数，则交给导航组件处理。

2. Navigation Component 的三个核心角色

Navigation Component 里最常见的三个概念是：

• NavHost：页面容器，用来承载不同目的地
• NavController：导航控制器，负责执行跳转和返回
• NavGraph：导航图，描述页面之间的关系

可以简单理解成：

NavGraph 负责定义路线
NavHost 负责显示页面
NavController 负责执行跳转

这三个角色分清之后，Navigation Component 就不难理解了。

3. 添加依赖

在模块的 build.gradle 中添加依赖：

dependencies {
    implementation("androidx.navigation:navigation-fragment-ktx:2.7.7")
    implementation("androidx.navigation:navigation-ui-ktx:2.7.7")
}

如果项目使用的是版本目录，也可以把版本统一放到 libs.versions.toml 中管理。实际项目里建议用统一版本管理，避免多个 Jetpack 组件版本混乱。

4. 创建导航图

在 res/navigation 目录下创建一个导航图，比如 nav_graph.xml：

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/nav_graph"
    app:startDestination="@id/homeFragment">

    <fragment
        android:id="@+id/homeFragment"
        android:name="com.example.app.HomeFragment"
        android:label="首页">
        <action
            android:id="@+id/action_home_to_detail"
            app:destination="@id/detailFragment" />
    </fragment>

    <fragment
        android:id="@+id/detailFragment"
        android:name="com.example.app.DetailFragment"
        android:label="详情页" />
</navigation>

这里定义了两个页面：homeFragment 和 detailFragment。

app:startDestination 表示进入导航容器后默认显示哪个页面。action_home_to_detail 表示从首页跳转到详情页的一条路径。

5. 在布局中放入 NavHost

Activity 的布局中需要放一个 FragmentContainerView，作为导航页面的容器：

<androidx.fragment.app.FragmentContainerView
    android:id="@+id/nav_host_fragment"
    android:name="androidx.navigation.fragment.NavHostFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:defaultNavHost="true"
    app:navGraph="@navigation/nav_graph" />

几个属性需要注意：

• android:name 指定这里使用的是 NavHostFragment
• app:navGraph 绑定刚才创建的导航图
• app:defaultNavHost="true" 表示系统返回键优先交给这个导航容器处理

这样，一个基础的导航容器就准备好了。

6. 执行页面跳转

在 Fragment 中可以通过 findNavController() 获取导航控制器：

class HomeFragment : Fragment(R.layout.fragment_home) {

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        view.findViewById<Button>(R.id.btnOpenDetail).setOnClickListener {
            findNavController().navigate(R.id.action_home_to_detail)
        }
    }
}

相比手写 FragmentTransaction，这段代码表达更清楚：点击按钮后，按照导航图里定义的 action 跳转到详情页。

页面之间的关系不再散落在各个 Fragment 里，而是可以从 nav_graph.xml 里整体查看。

7. 页面返回怎么处理

Navigation Component 会自动维护返回栈。

如果从首页进入详情页，按系统返回键，默认会回到首页。如果你想在代码里主动返回，可以这样写：

findNavController().popBackStack()

如果想返回到指定页面，也可以使用：

findNavController().popBackStack(R.id.homeFragment, false)

第二个参数表示目标页面本身是否也要一起弹出。

• false：返回到目标页面，目标页面保留
• true：连目标页面一起弹出

这个参数在实际开发里很容易写错，需要特别注意。

8. 页面参数传递

最基础的方式是用 Bundle：

val bundle = bundleOf("articleId" to 1001)
findNavController().navigate(R.id.action_home_to_detail, bundle)

在目标页面读取：

val articleId = requireArguments().getInt("articleId")

这种方式简单直接，但缺点是 key 是字符串，类型也需要自己保证。如果项目比较大，更推荐使用 Safe Args。

9. 使用 Safe Args 提升安全性

Safe Args 是 Navigation Component 提供的参数安全插件。它会根据导航图生成类型安全的跳转代码。

添加插件后，可以在导航图里定义参数：

<fragment
    android:id="@+id/detailFragment"
    android:name="com.example.app.DetailFragment"
    android:label="详情页">

    <argument
        android:name="articleId"
        app:argType="integer" />
</fragment>

跳转时就可以写成：

val action = HomeFragmentDirections.actionHomeToDetail(articleId = 1001)
findNavController().navigate(action)

详情页读取参数：

val args: DetailFragmentArgs by navArgs()
val articleId = args.articleId

这样做的好处是：

• 参数名不容易写错
• 参数类型由编译器检查
• 重构时更安全
• 页面跳转代码更清晰

10. 和 Toolbar 配合

Navigation Component 也可以和 Toolbar 配合，自动处理标题和返回按钮。

val navHostFragment = supportFragmentManager
    .findFragmentById(R.id.nav_host_fragment) as NavHostFragment
val navController = navHostFragment.navController

setupActionBarWithNavController(navController)

然后重写：

override fun onSupportNavigateUp(): Boolean {
    return findNavController(R.id.nav_host_fragment).navigateUp()
            || super.onSupportNavigateUp()
}

这样在进入二级页面时，顶部返回按钮就能自动跟随导航栈工作。

如果项目使用 Toolbar 而不是默认 ActionBar，可以使用：

toolbar.setupWithNavController(navController)

11. 和 BottomNavigationView 配合

底部导航也是 Navigation Component 常见使用场景。

bottomNavigationView.setupWithNavController(navController)

只要 BottomNavigationView 中 menu item 的 id 和导航图里的 destination id 对应，组件就可以自动完成切换。

例如：

<item
    android:id="@id/homeFragment"
    android:title="首页"
    android:icon="@drawable/ic_home" />

这里的 android:id 要和导航图中的 homeFragment 保持一致。

这个约定很重要。如果 id 对不上，点击底部导航时就找不到对应页面。

12. 深链接支持

Navigation Component 支持直接在导航图里配置 deep link：

<fragment
    android:id="@+id/detailFragment"
    android:name="com.example.app.DetailFragment">

    <deepLink app:uri="https://example.com/article/{articleId}" />
</fragment>

当外部链接匹配这个规则时，可以直接打开详情页，并把路径里的参数传进来。

深链接适合这些场景：

• 推送通知点击后进入指定页面
• 浏览器链接打开 App 内页面
• 分享链接回流到 App
• 活动页、内容页直接唤起

不过深链接也要注意校验参数，不要默认相信外部传进来的值。

13. 常见坑

13.1 在错误的 Fragment 上找 NavController

如果页面结构比较复杂，比如 Fragment 里又嵌套 Fragment，可能会拿错 NavController。

常见解决方式是从正确的 View 或宿主 Fragment 获取：

view.findNavController()

或者在 Activity 中通过 NavHostFragment 获取。

13.2 重复点击导致多次跳转

按钮快速点击时，可能连续执行多次 navigate()，导致重复打开页面。实际项目里可以做点击防抖，或者在跳转前检查当前 destination：

val navController = findNavController()
if (navController.currentDestination?.id == R.id.homeFragment) {
    navController.navigate(R.id.action_home_to_detail)
}

13.3 返回栈和预期不一致

如果登录页、首页、支付成功页这类页面涉及清空历史栈，就要认真配置 popUpTo。

例如登录成功后进入首页，并清掉登录页：

<action
    android:id="@+id/action_login_to_home"
    app:destination="@id/homeFragment"
    app:popUpTo="@id/loginFragment"
    app:popUpToInclusive="true" />

popUpToInclusive="true" 表示把 loginFragment 自己也从返回栈中移除。这样用户在首页按返回键时，就不会回到登录页。

13.4 把导航图写得过大

导航图不是越大越好。大型项目里，如果所有页面都塞进一个导航图，维护起来也会变乱。

更合理的做法是按业务模块拆分，比如：

• 首页模块导航图
• 登录模块导航图
• 订单模块导航图
• 我的页面导航图

这样每个导航图只负责一个相对独立的业务范围。

14. 什么时候适合用 Navigation Component

适合使用的场景：

• Fragment 页面较多
• 页面跳转关系复杂
• 有底部导航、抽屉导航、深链接
• 希望统一管理返回栈
• 希望减少手写 FragmentTransaction

不一定需要使用的场景：

• 项目很小，只有一两个页面
• 页面完全由 Compose Navigation 管理
• 团队已有成熟的自研路由方案
• 业务强依赖跨模块动态路由

所以 Navigation Component 不是所有项目的唯一答案，但它很适合大多数 Jetpack 风格的中小型 Android 项目。

15. 小结

Navigation Component 解决的不是“能不能跳转”的问题，而是“页面跳转能不能清晰、统一、可维护”的问题。

它把页面关系集中到导航图里，用 NavController 统一执行跳转，并且内置了返回栈、参数传递、Toolbar、BottomNavigationView、Deep Link 等能力。

掌握它之后，Android 页面导航会从零散的手写事务，变成更结构化的页面流转管理。

对于刚开始学习 Jetpack 的开发者来说，可以先记住一句话：

Activity 提供宿主，Fragment 承载页面，Navigation Component 管理页面之间怎么走。

理解了这一点，再去看导航图、NavHost、NavController，就会顺很多。