Memulai komponen Navigation

Menyiapkan lingkungan Anda

Untuk menyertakan dukungan Navigation dalam project Anda, tambahkan dependensi berikut ke file build.gradle aplikasi Anda:

dependencies {
  def nav_version = "2.5.3"

  // Java language implementation
  implementation "androidx.navigation:navigation-fragment:$nav_version"
  implementation "androidx.navigation:navigation-ui:$nav_version"

  // Kotlin
  implementation "androidx.navigation:navigation-fragment-ktx:$nav_version"
  implementation "androidx.navigation:navigation-ui-ktx:$nav_version"

  // Feature module Support
  implementation "androidx.navigation:navigation-dynamic-features-fragment:$nav_version"

  // Testing Navigation
  androidTestImplementation "androidx.navigation:navigation-testing:$nav_version"

  // Jetpack Compose Integration
  implementation "androidx.navigation:navigation-compose:$nav_version"
}

dependencies {
  val nav_version = "2.5.3"

  // Java language implementation
  implementation("androidx.navigation:navigation-fragment:$nav_version")
  implementation("androidx.navigation:navigation-ui:$nav_version")

  // Kotlin
  implementation("androidx.navigation:navigation-fragment-ktx:$nav_version")
  implementation("androidx.navigation:navigation-ui-ktx:$nav_version")

  // Feature module Support
  implementation("androidx.navigation:navigation-dynamic-features-fragment:$nav_version")

  // Testing Navigation
  androidTestImplementation("androidx.navigation:navigation-testing:$nav_version")

  // Jetpack Compose Integration
  implementation("androidx.navigation:navigation-compose:$nav_version")
}

Untuk informasi tentang cara menambahkan Komponen Arsitektur lainnya ke project Anda, lihat Menambahkan komponen ke project Anda.

Membuat grafik navigasi

Navigasi terjadi di antara tujuan-tujuan aplikasi Anda—dalam hal ini, di mana saja dalam aplikasi Anda yang dapat dinavigasi oleh pengguna. Tujuan tersebut terhubung melalui tindakan.

Grafik navigasi adalah file resource yang berisi semua tujuan dan tindakan Anda. Grafik tersebut mewakili semua jalur navigasi aplikasi Anda.

Gambar 1 menunjukkan representasi visual grafik navigasi untuk aplikasi contoh yang berisi enam tujuan dan terhubung dengan lima tindakan. Setiap tujuan diwakili oleh thumbnail pratinjau, dan tindakan yang terhubung diwakili oleh tanda panah yang menunjukkan cara pengguna menavigasi dari satu tujuan ke tujuan lainnya.

1. Tujuan adalah area konten yang berbeda di dalam aplikasi Anda.
2. Tindakan adalah hubungan logis antara tujuan Anda yang mewakili jalur yang dapat diambil pengguna.

Untuk menambahkan grafik navigasi ke project Anda, lakukan hal-hal berikut:

1. Pada jendela Project, klik kanan di direktori res dan pilih New > Android Resource File. Dialog New Resource File akan muncul.
2. Ketik nama di kolom File name, seperti "nav_graph".
3. Pilih Navigation dari menu drop-down Resource type, lalu klik OK.

Saat Anda menambahkan grafik navigasi pertama, Android Studio akan membuat direktori resource navigation di dalam direktori res. Direktori ini berisi file resource grafik navigasi Anda (misalnya nav_graph.xml).

Navigation Editor

Setelah menambahkan grafik, Android Studio akan membuka grafik tersebut ke dalam Navigation Editor. Di dalam Navigation Editor, Anda dapat mengedit grafik navigasi secara visual atau langsung mengedit XML yang mendasarinya.

1. Destination panel: Menampilkan daftar host navigasi dan semua tujuan yang saat ini ada di dalam Graph Editor.
2. Graph Editor: Berisi representasi visual grafik navigasi Anda. Anda dapat beralih antartampilan Design dan representasi XML yang mendasarinya dalam tampilan Text.
3. Attributes: Menampilkan atribut untuk item yang saat ini dipilih dalam grafik navigasi.

Klik tab Text untuk melihat XML yang sesuai, yang akan terlihat mirip dengan cuplikan berikut:

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

</navigation>

Elemen <navigation> adalah elemen root pada grafik navigasi. Saat menambahkan tujuan dan menghubungkan tindakan ke grafik, Anda dapat melihat elemen <destination> dan <action> yang sesuai di sini sebagai elemen turunan. Jika Anda memiliki grafik bertingkat, elemen tersebut akan muncul sebagai elemen <navigation> turunan.

Menambahkan NavHost ke aktivitas

Salah satu bagian inti pada komponen Navigation adalah host navigasi. Host navigasi adalah penampung kosong tempat tujuan ditukar saat pengguna menavigasi aplikasi Anda.

Host navigasi harus berasal dari NavHost. Implementasi NavHost default komponen navigasi, NavHostFragment, akan menangani penukaran tujuan fragmen.

Menambahkan NavHostFragment melalui XML

Contoh XML di bawah ini menunjukkan NavHostFragment sebagai bagian dari aktivitas utama aplikasi:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    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:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <androidx.appcompat.widget.Toolbar
        .../>

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

    <com.google.android.material.bottomnavigation.BottomNavigationView
        .../>

</androidx.constraintlayout.widget.ConstraintLayout>

Perhatikan hal berikut:

• Atribut android:name berisi nama class implementasi NavHost Anda.
• Atribut app:navGraph mengaitkan NavHostFragment dengan grafik navigasi. Grafik navigasi tersebut menentukan semua tujuan di dalam NavHostFragment yang dapat dinavigasi oleh pengguna.
• Atribut app:defaultNavHost="true" memastikan bahwa NavHostFragment Anda menyela tombol Kembali sistem. Perhatikan bahwa hanya satu NavHost yang bisa menjadi default. Jika Anda memiliki beberapa host dalam tata letak yang sama (misalnya tata letak dua-panel), pastikan untuk menentukan hanya satu NavHost default.

Anda juga dapat menggunakan Layout Editor untuk menambahkan NavHostFragment ke aktivitas dengan melakukan hal berikut:

1. Dalam daftar file project, klik dua kali file XML tata letak aktivitas Anda untuk membukanya di Layout Editor.
2. Dalam panel Palette, pilih kategori Containers, atau dengan cara lain yaitu menelusuri "NavHostFragment".
3. Tarik tampilan NavHostFragment ke dalam aktivitas Anda.
4. Selanjutnya, dalam dialog Navigation Graph yang muncul, pilih grafik navigasi yang sesuai untuk dikaitkan dengan NavHostFragment ini, lalu klik OK.

Menambahkan tujuan ke grafik navigasi

Anda dapat membuat tujuan dari fragmen atau aktivitas yang ada. Anda juga dapat menggunakan Navigation Editor untuk membuat tujuan baru atau membuat placeholder agar nantinya diganti dengan fragmen atau aktivitas.

Dalam contoh ini, mari membuat sebuah tujuan baru. Untuk menambahkan tujuan baru menggunakan Navigation Editor, lakukan hal-hal berikut:

1. Di Navigation Editor, klik ikon New Destination , lalu klik Create new destination.
2. Dalam dialog New Android Component yang muncul, buat fragmen Anda. Untuk informasi selengkapnya tentang fragmen, lihat dokumentasi fragmen.

Kembali ke Navigation Editor, perhatikan bahwa Android Studio telah menambahkan tujuan ini ke grafik.

Gambar 3 menunjukkan contoh tujuan dan tujuan placeholder.

Untuk mengetahui cara lain terkait menambahkan tujuan ke grafik navigasi Anda, lihat Membuat tujuan.

Anatomi tujuan

Klik tujuan untuk memilihnya, dan perhatikan atribut-atribut berikut di panel Attributes:

• Kolom Type menunjukkan apakah tujuan diimplementasikan sebagai fragmen, aktivitas, atau class khusus lainnya di kode sumber Anda.
• Kolom Label berisi nama tujuan yang dapat dibaca pengguna. Kolom ini mungkin akan muncul di UI—misalnya, jika Anda menghubungkan NavGraph ke Toolbar menggunakan setupWithNavController(). Oleh karena itu, sebaiknya gunakan string resource untuk nilai ini.
• Kolom ID berisi ID tujuan yang digunakan untuk merujuk ke tujuan dalam kode.
• Drop-down Class menampilkan nama class yang dikaitkan dengan tujuan. Anda dapat mengklik drop-down ini untuk mengubah class terkait tersebut ke jenis tujuan lain.

Klik tab Text untuk menampilkan tampilan XML grafik navigasi Anda. XML tersebut berisi atribut id, name, label, dan layout yang sama untuk tujuan, seperti yang ditunjukkan di bawah ini:

<?xml version="1.0" encoding="utf-8"?>
<navigation xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    xmlns:android="http://schemas.android.com/apk/res/android"
    app:startDestination="@id/blankFragment">
    <fragment
        android:id="@+id/blankFragment"
        android:name="com.example.cashdog.cashdog.BlankFragment"
        android:label="@string/label_blank"
        tools:layout="@layout/fragment_blank" />
</navigation>

Menentukan layar sebagai tujuan awal

Tujuan awal adalah layar pertama yang dilihat pengguna saat membuka aplikasi Anda dan layar terakhir yang dilihat pengguna saat keluar dari aplikasi Anda. Navigation editor menggunakan ikon rumah untuk menunjukkan tujuan awal.

Setelah semua tujuan sudah siap, Anda dapat memilih tujuan awal dengan melakukan hal-hal berikut:

1. Pada tab Design, klik tujuan untuk menandainya.

2. Klik tombol Assign start destination . Atau, Anda dapat mengklik kanan pada tujuan dan mengklik Set as Start Destination.

Menghubungkan tujuan

Tindakan adalah hubungan logis antartujuan. Tindakan ditunjukkan sebagai tanda panah dalam grafik navigasi. Tindakan biasanya menghubungkan satu tujuan ke tujuan lain, meskipun Anda juga dapat membuat tindakan global yang mengarahkan Anda ke tujuan tertentu dari mana saja dalam aplikasi Anda.

Dengan tindakan, Anda mewakili jalur berbeda yang dapat diambil pengguna melalui aplikasi Anda. Perhatikan bahwa untuk benar-benar menavigasi ke tujuan, Anda masih perlu menulis kode untuk melakukan navigasi. Hal ini akan dibahas nantinya di bagian Menavigasi ke tujuan pada topik ini.

Anda dapat menggunakan Navigation Editor untuk menghubungkan dua tujuan dengan melakukan hal-hal berikut:

1. Pada tab Design, arahkan kursor ke sisi kanan tujuan yang akan dinavigasikan pengguna. Sebuah lingkaran akan muncul di sisi kanan tujuan, seperti yang ditunjukkan pada gambar 4.

   

2. Klik dan tarik kursor ke tujuan yang akan dinavigasikan pengguna, lalu lepaskan. Garis yang dihasilkan antara dua tujuan akan mewakili suatu tindakan, seperti yang ditunjukkan pada gambar 5.

   

3. Klik pada panah untuk menandai tindakan. Atribut berikut muncul dalam panel Attributes:

   • Kolom Type berisi “Tindakan”.
   • Kolom ID berisi ID untuk tindakan.
   • Kolom Destination berisi ID untuk aktivitas atau fragmen tujuan.

4. Klik tab Text untuk beralih ke tampilan XML. Elemen tindakan kini ditambahkan ke tujuan sumber. Tindakan tersebut memiliki ID dan atribut tujuan yang berisi ID tujuan berikutnya, seperti yang ditunjukkan dalam contoh di bawah:

   <?xml version="1.0" encoding="utf-8"?>
   <navigation xmlns:app="http://schemas.android.com/apk/res-auto"
       xmlns:tools="http://schemas.android.com/tools"
       xmlns:android="http://schemas.android.com/apk/res/android"
       app:startDestination="@id/blankFragment">
       <fragment
           android:id="@+id/blankFragment"
           android:name="com.example.cashdog.cashdog.BlankFragment"
           android:label="@string/label_blank"
           tools:layout="@layout/fragment_blank" >
           <action
               android:id="@+id/action_blankFragment_to_blankFragment2"
               app:destination="@id/blankFragment2" />
       </fragment>
       <fragment
           android:id="@+id/blankFragment2"
           android:name="com.example.cashdog.cashdog.BlankFragment2"
           android:label="@string/label_blank_2"
           tools:layout="@layout/fragment_blank_fragment2" />
   </navigation>
   

Dalam grafik navigasi, tindakan ditunjukkan oleh elemen <action>. Minimalnya, tindakan berisi ID-nya sendiri dan ID tujuan di mana pengguna harus diarahkan.

Menavigasi ke tujuan

Menavigasi ke tujuan dapat dilakukan menggunakan NavController, yaitu sebuah objek yang mengelola navigasi aplikasi dalam NavHost. Setiap NavHost memiliki NavController-nya sendiri yang sesuai. Anda dapat mengambil NavController dengan menggunakan salah satu metode berikut:

Kotlin:

• Fragment.findNavController()
• View.findNavController()
• Activity.findNavController(viewId: Int)

Java:

• NavHostFragment.findNavController(Fragment)
• Navigation.findNavController(Activity, @IdRes int viewId)
• Navigation.findNavController(View)

Saat membuat NavHostFragment menggunakan FragmentContainerView atau jika menambahkan NavHostFragment secara manual ke aktivitas melalui FragmentTransaction, berusaha mengambil NavController dalam onCreate() Aktivitas melalui Navigation.findNavController(Activity, @IdRes int) akan gagal. Anda harus mengambil NavController langsung dari NavHostFragment.

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

NavHostFragment navHostFragment =
        (NavHostFragment) getSupportFragmentManager().findFragmentById(R.id.nav_host_fragment);
NavController navController = navHostFragment.getNavController();

Memastikan keamanan jenis menggunakan Safe Args

Cara yang direkomendasikan untuk bernavigasi antartujuan adalah dengan menggunakan plugin Safe Args Gradle. Plugin ini menghasilkan class builder dan objek sederhana yang mengaktifkan navigasi keamanan jenis dan argumen yang melewati antartujuan.

Untuk menambahkan Safe Args ke project Anda, sertakan classpath berikut dalam file build.gradle level teratas:

buildscript {
    repositories {
        google()
    }
    dependencies {
        def nav_version = "2.5.3"
        classpath "androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version"
    }
}

buildscript {
    repositories {
        google()
    }
    dependencies {
        val nav_version = "2.5.3"
        classpath("androidx.navigation:navigation-safe-args-gradle-plugin:$nav_version")
    }
}

Anda juga harus menerapkan salah satu dari dua plugin yang tersedia.

Untuk menghasilkan kode bahasa Java yang sesuai bagi modul Java atau modul campuran Java dan Kotlin, tambahkan baris berikut ke file build.gradle aplikasi atau modul Anda:

plugins {
  id 'androidx.navigation.safeargs'
}

plugins {
    id("androidx.navigation.safeargs")
}

Atau, untuk menghasilkan kode Kotlin yang sesuai bagi modul khusus Kotlin, tambahkan:

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

plugins {
    id("androidx.navigation.safeargs.kotlin")
}

Anda harus memiliki android.useAndroidX=true dalam file gradle.properties seperti yang dijelaskan dalam Bermigrasi ke AndroidX.

Setelah Anda mengaktifkan Safe Args, plugin tersebut akan menghasilkan kode yang berisi class dan metode untuk setiap tindakan yang telah Anda tentukan. Untuk setiap tindakan, Safe Args juga menghasilkan class untuk setiap tujuan asal, yang merupakan tujuan di mana tindakan tersebut berasal. Nama class yang dihasilkan adalah kombinasi nama class tujuan asal dan kata "Directions". Misalnya, jika tujuan diberi nama SpecifyAmountFragment, class yang dihasilkan akan diberi nama SpecifyAmountFragmentDirections. Class yang dihasilkan berisi metode statis untuk setiap tindakan yang ditentukan pada tujuan awal. Metode ini menggunakan parameter tindakan yang ditentukan sebagai argumen dan menampilkan sebuah objek NavDirections yang dapat Anda teruskan ke navigate().

Sebagai contoh, asumsikan kita memiliki grafik navigasi dengan satu tindakan yang menghubungkan tujuan asal, SpecifyAmountFragment, ke tujuan penerima, ConfirmationFragment.

Safe Args akan menghasilkan class SpecifyAmountFragmentDirections dengan satu metode, actionSpecifyAmountFragmentToConfirmationFragment() yang menampilkan objek NavDirections. Objek NavDirections yang ditampilkan ini nantinya dapat langsung diteruskan ke navigate(), seperti yang ditunjukkan dalam contoh berikut:

override fun onClick(view: View) {
    val action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment()
    view.findNavController().navigate(action)
}

@Override
public void onClick(View view) {
    NavDirections action =
        SpecifyAmountFragmentDirections
            .actionSpecifyAmountFragmentToConfirmationFragment();
    Navigation.findNavController(view).navigate(action);
}

Untuk informasi selengkapnya tentang meneruskan data antartujuan dengan Safe Args, lihat Menggunakan Safe Args untuk meneruskan data dengan keamanan jenis.

Informasi selengkapnya

• Ringkasan Navigation
• Membuat tujuan
• Menavigasi ke tujuan
• Mengupdate komponen UI dengan NavigationUI
• Meneruskan data antartujuan
• Tindakan global
• Tujuan bersyarat
• Jenis tujuan kustom
• Android Jetpack: mengelola navigasi UI dengan Pengontrol Navigasi (Google I/O 2018)
• Memigrasikan project yang ada ke Komponen Arsitektur Navigasi
• Codelab Navigasi

Jika Anda mengalami masalah dengan Navigation, harap kirimkan masukan melalui salah satu saluran berikut:

• Melaporkan bug Navigation editor
• Melaporkan bug Navigation library
• Memberikan tag pada masalah di StackOverflow

Untuk informasi tentang cara memberikan informasi yang paling berguna dalam laporan bug, lihat link berikut:

• Melaporkan Bug (platform Android)
• Melaporkan bug (Android Studio)