Navigation Component 工程落地：从单 Activity 架构到深度链接配置

在 Android 开发中，页面导航一直是个容易出问题的环节：Fragment 回退栈混乱、参数传递不安全、深度链接配置繁琐。Jetpack Navigation Component 提供了一套声明式的导航方案，但要在真实项目中用好它，还需要处理不少工程细节。

本文从实际项目需求出发，讲解如何用 Navigation Component 搭建单 Activity 多 Fragment 架构、安全传参、处理回退栈、配置深度链接，以及在复杂场景下的边界处理。

传统导航方式的痛点：

FragmentTransaction 代码冗长 ：每次跳转都要写一堆 beginTransaction() + replace() + addToBackStack()
参数传递不安全：用 Bundle 手动塞数据，类型不安全，容易 key 写错
回退栈难管理：多层嵌套后，按返回键的行为不符合预期
深度链接配置麻烦：需要在 Manifest 和代码里重复声明

Navigation Component 的优势：

声明式导航图：在 XML 中定义所有页面和跳转关系，一目了然
Safe Args 插件：编译期生成类型安全的参数类
自动处理回退栈：框架自动管理 Fragment 的添加和移除
深度链接一站式配置：在导航图中声明，自动生成 Intent Filter

基础集成

1. 添加依赖

gradle 复制代码

dependencies {
    def nav_version = "2.7.7"
    implementation "androidx.navigation:navigation-fragment-ktx:$nav_version"
    implementation "androidx.navigation:navigation-ui-ktx:$nav_version"
}

2. 启用 Safe Args 插件

在项目根目录的 build.gradle 中添加：

gradle 复制代码

buildscript {
    dependencies {
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:2.7.7"
    }
}

在 app 模块的 build.gradle 中应用：

gradle 复制代码

plugins {
    id 'androidx.navigation.safeargs.kotlin'
}

创建导航图

在 res/navigation/ 目录下新建 nav_graph.xml：

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="详情">
        <argument
            android:name="itemId"
            app:argType="string" />
        <argument
            android:name="showComments"
            app:argType="boolean"
            app:defaultValue="false" />
    </fragment>
</navigation>

配置宿主 Activity

在 MainActivity 的布局中添加 NavHostFragment：

xml 复制代码

<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" />

app:defaultNavHost="true"：拦截系统返回键
app:navGraph：指定导航图

页面跳转与参数传递

基础跳转

在 HomeFragment 中：

kotlin 复制代码

findNavController().navigate(R.id.action_home_to_detail)

使用 Safe Args 传参

Safe Args 插件会为每个声明了 <argument> 的 Fragment 生成两个类：

XXXFragmentArgs：接收参数
XXXFragmentDirections：构建跳转参数

发送方（HomeFragment）：

kotlin 复制代码

val action = HomeFragmentDirections.actionHomeToDetail(
    itemId = "item_123",
    showComments = true
)
findNavController().navigate(action)

接收方（DetailFragment）：

kotlin 复制代码

class DetailFragment : Fragment() {
    private val args: DetailFragmentArgs by navArgs()

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        val itemId = args.itemId
        val showComments = args.showComments
        // 使用参数加载数据
    }
}

回退栈管理

场景 1：跳转时清空回退栈

从登录页跳到首页后，不希望按返回键回到登录页：

xml 复制代码

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

app:popUpTo：弹出栈直到指定目的地
app:popUpToInclusive="true"：包括指定目的地本身也弹出

场景 2：返回到指定页面

从详情页返回时，跳过中间页直接回到首页：

kotlin 复制代码

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

第二个参数 false 表示不包括 homeFragment 本身。

深度链接配置

1. 在导航图中声明

xml 复制代码

<fragment
    android:id="@+id/detailFragment"
    android:name="com.example.app.DetailFragment"
    android:label="详情">
    <argument
        android:name="itemId"
        app:argType="string" />
    <deepLink
        app:uri="myapp://item/{itemId}" />
</fragment>

2. 在 Manifest 中添加 nav-graph

xml 复制代码

<activity android:name=".MainActivity">
    <nav-graph android:value="@navigation/nav_graph" />
</activity>

编译后，插件会自动生成对应的 <intent-filter>。

3. 触发深度链接

外部触发（如通知、浏览器）：

kotlin 复制代码

val intent = Intent(Intent.ACTION_VIEW, Uri.parse("myapp://item/item_123"))
startActivity(intent)

内部触发：

kotlin 复制代码

findNavController().navigate(Uri.parse("myapp://item/item_123"))

进阶技巧

1. 全局 Action

在导航图根节点定义全局跳转：

xml 复制代码

<navigation ...>
    <action
        android:id="@+id/action_global_settings"
        app:destination="@id/settingsFragment" />
    <!-- 其他 fragment... -->
</navigation>

任何页面都可以直接调用：

kotlin 复制代码

findNavController().navigate(R.id.action_global_settings)

2. 共享元素过渡动画

在跳转时传递共享元素：

kotlin 复制代码

val extras = FragmentNavigatorExtras(
    imageView to "item_image"
)
findNavController().navigate(R.id.action_home_to_detail, null, null, extras)

在目标 Fragment 中设置过渡：

kotlin 复制代码

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    sharedElementEnterTransition = TransitionInflater.from(requireContext())
        .inflateTransition(android.R.transition.move)
}

3. 监听导航事件

kotlin 复制代码

findNavController().addOnDestinationChangedListener { _, destination, _ ->
    when (destination.id) {
        R.id.homeFragment -> toolbar.title = "首页"
        R.id.detailFragment -> toolbar.title = "详情"
    }
}

常见问题与边界处理

问题 1：嵌套导航图回退混乱

场景：Tab 页中每个 Tab 有自己的导航图，切换 Tab 后按返回键，回退行为不符合预期。

方案：每个 Tab 使用独立的 NavHostFragment，并在宿主 Fragment 中管理：

kotlin 复制代码

class TabContainerFragment : Fragment() {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        childFragmentManager.findFragmentById(R.id.tab_nav_host) as NavHostFragment
    }
}

问题 2：参数序列化复杂对象

Safe Args 只支持基本类型和 Parcelable。如果需要传递复杂对象：

方案 1：传递 ID，在目标页查询

kotlin 复制代码

val action = HomeFragmentDirections.actionHomeToDetail(itemId = item.id)

方案 2：使用共享 ViewModel

kotlin 复制代码

// 在宿主 Activity 范围内共享
val sharedViewModel: SharedViewModel by activityViewModels()

问题 3：深度链接参数类型不匹配

场景：URL 中传递的是字符串 "true"，但 argType 是 boolean。

解决：导航图中声明 argType="string"，在 Fragment 中手动转换：

kotlin 复制代码

val showComments = args.showCommentsStr.toBoolean()

与 Compose 的配合

如果项目混用了 Jetpack Compose，可以用 navigation-compose：

kotlin 复制代码

dependencies {
    implementation "androidx.navigation:navigation-compose:2.7.7"
}

在 Composable 中定义导航：

kotlin 复制代码

val navController = rememberNavController()
NavHost(navController, startDestination = "home") {
    composable("home") { HomeScreen(navController) }
    composable("detail/{itemId}") { backStackEntry ->
        val itemId = backStackEntry.arguments?.getString("itemId")
        DetailScreen(itemId)
    }
}

总结

Navigation Component 的核心价值在于把导航逻辑从代码搬到声明式配置，减少模板代码，提高可维护性。

工程落地时的关键点：

Safe Args 必开：编译期类型检查，避免运行时崩溃
回退栈提前规划 ：复杂流程用 popUpTo 明确回退行为
深度链接统一配置：避免 Manifest 和代码重复维护
嵌套导航谨慎使用：多层嵌套容易导致回退混乱，优先用全局 Action

当你的 App 架构从多 Activity 迁移到单 Activity + Navigation 后，你会发现页面跳转的代码量明显减少，回退逻辑也更清晰。但也要注意，Navigation Component 不是银弹------对于特别复杂的导航场景（如多栈切换、动态路由），可能需要结合自定义 Navigator 或者干脆手动管理 Fragment。

关键是理解它的设计思想，在合适的场景用合适的工具。

Navigation Component 工程落地：从单 Activity 架构到深度链接配置