导航组件

源：Navigation

Navigation 组件是 Android Jetpack 库的一部分，用于在应用中的不同目的地（Destinations）之间进行导航。它简化了 Fragment 事务的处理、DeepLink、参数传递以及转场动画等操作。

添加依赖

libs.versions.toml

[versions]
navigation = "2.7.7"

[libraries]
androidx-navigation-fragment-ktx = { group = "androidx.navigation", name = "navigation-fragment-ktx", version.ref = "navigation" }
androidx-navigation-ui-ktx = { group = "androidx.navigation", name = "navigation-ui-ktx", version.ref = "navigation" }
androidx-navigation-dynamic-features-fragment = { group = "androidx.navigation", name = "navigation-dynamic-features-fragment", version.ref = "navigation" }
androidx-navigation-testing = { group = "androidx.navigation", name = "navigation-testing", version.ref = "navigation" }
androidx-navigation-compose = { group = "androidx.navigation", name = "navigation-compose", version.ref = "navigation" }

[plugins]
androidx-navigation-safeargs = { id = "androidx.navigation.safeargs.kotlin", version.ref = "navigation" }

build.gradle.kts

plugins {
    alias(libs.plugins.androidx.navigation.safeargs)
}

dependencies {
    implementation(libs.androidx.navigation.fragment.ktx)
    implementation(libs.androidx.navigation.ui.ktx)
    implementation(libs.androidx.navigation.dynamic.features.fragment)
    androidTestImplementation(libs.androidx.navigation.testing)
    implementation(libs.androidx.navigation.compose)
}

build.gradle

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

dependencies {
    def nav_version = "2.7.7"

    implementation "androidx.navigation:navigation-fragment-ktx:$nav_version"
    implementation "androidx.navigation:navigation-ui-ktx:$nav_version"
    implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version"
    androidTestImplementation "androidx.navigation:navigation-testing:$nav_version"
    implementation "androidx.navigation:navigation-compose:$nav_version"
}

创建导航图

1. 在 res 目录下新建 navigation 目录。
2. 新建 nav_graph.xml 资源文件。
3. 使用 Navigation Editor 添加 Destination（通常是 Fragment）并创建 Action（连接线）。

<?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"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/nav_graph"
    app:startDestination="@id/homeFragment">

    <fragment
        android:id="@+id/homeFragment"
        android:name="com.example.HomeFragment"
        android:label="fragment_home"
        tools:layout="@layout/fragment_home">
        <action
            android:id="@+id/action_homeFragment_to_detailFragment"
            app:destination="@id/detailFragment" />
    </fragment>

    <fragment
        android:id="@+id/detailFragment"
        android:name="com.example.DetailFragment"
        android:label="fragment_detail"
        tools:layout="@layout/fragment_detail">
        <argument
            android:name="userId"
            app:argType="integer" />
        
        <!-- 深层链接配置 -->
        <deepLink app:uri="example.com/user/{userId}" />
    </fragment>
</navigation>

添加 NavHost

NavHost 是一个空容器，当用户在应用中导航时，Destination 会在这里换入和换出。默认实现是 NavHostFragment。

在 Activity 的布局文件（例如 activity_main.xml）中添加：

<androidx.constraintlayout.widget.ConstraintLayout ...>

    <androidx.fragment.app.FragmentContainerView
        android:id="@+id/nav_host_fragment"
        android:name="androidx.navigation.fragment.NavHostFragment"
        android:layout_width="0dp"
        android:layout_height="0dp"
        app:layout_constraintLeft_toLeftOf="parent"
        app:layout_constraintRight_toRightOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:layout_constraintBottom_toBottomOf="parent"
        app:defaultNavHost="true"
        app:navGraph="@navigation/nav_graph" />

</androidx.constraintlayout.widget.ConstraintLayout>

• app:navGraph: 指定关联的导航图。
• app:defaultNavHost="true": 确保 NavHostFragment 拦截系统返回键。

使用 NavController 导航

NavController 是用于在 NavHost 中管理应用导航的对象。

基本导航

在 Fragment 中：

// 使用 view.findNavController()
view.findViewById<Button>(R.id.navigate_btn).setOnClickListener {
    it.findNavController().navigate(R.id.action_homeFragment_to_detailFragment)
}

// 或者使用 Fragment 扩展方法
findNavController().navigate(R.id.action_homeFragment_to_detailFragment)

使用 Safe Args 传递参数

如果使用了 Safe Args 插件，它会为每个定义了 action 或 argument 的 Fragment 生成对应的 Directions 和 Args 类。

发送数据 (Source Fragment):

val action = HomeFragmentDirections.actionHomeFragmentToDetailFragment(userId = 123)
findNavController().navigate(action)

接收数据 (Destination Fragment):

val args: DetailFragmentArgs by navArgs()

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    val userId = args.userId
    // ...
}

NavigationUI

Navigation 组件包含 NavigationUI 类，用于将导航与顶部应用栏（Top App Bar）、抽屉式导航栏（Navigation Drawer）和底部导航栏（Bottom Navigation）绑定。

绑定 BottomNavigationView

val navHostFragment = supportFragmentManager.findFragmentById(R.id.nav_host_fragment) as NavHostFragment
val navController = navHostFragment.navController
val bottomNavigationView = findViewById<BottomNavigationView>(R.id.bottom_nav)

bottomNavigationView.setupWithNavController(navController)

注意：BottomNavigationView 中的 menu item id 必须与 nav_graph.xml 中的 destination id 一致，才能自动关联。

绑定 Toolbar

val appBarConfiguration = AppBarConfiguration(navController.graph)
// 或者指定顶层 Destination (不显示返回箭头)
// val appBarConfiguration = AppBarConfiguration(setOf(R.id.homeFragment, R.id.profileFragment))

findViewById<Toolbar>(R.id.toolbar).setupWithNavController(navController, appBarConfiguration)

动画

可以在 XML Action 中定义转场动画：

<action
    android:id="@+id/action_next"
    app:destination="@id/nextFragment"
    app:enterAnim="@anim/slide_in_right"
    app:exitAnim="@anim/slide_out_left"
    app:popEnterAnim="@anim/slide_in_left"
    app:popExitAnim="@anim/slide_out_right" />

深层链接

支持通过 URI 直接跳转到特定页面。

1. 定义: 如上 nav_graph.xml 所示，在 fragment 中添加 <deepLink> 标签。
2. 配置 Manifest: 允许 Activity 拦截该 URI。

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

当用户点击 example.com/user/123 链接时，应用会自动打开 MainActivity 并导航到 DetailFragment，且参数 userId 自动填充为 123。