Gezinme grafiğinizi tasarlama

Gezinme bileşeni, uygulamanızın gezinmesini yönetmek için bir gezinme grafiği kullanır. Gezinme grafiği, uygulamanızdaki her hedefi ve aralarındaki bağlantıları içeren bir veri yapısıdır.

Not: Gezinme grafiği, NavController içindeki ve kullanıcının son ziyaret ettiği hedefleri barındıran bir yığın olan geri yığın'dan farklıdır.

Hedef türleri

Üç genel hedef türü vardır: barındırılan, iletişim kutusu ve etkinlik. Aşağıdaki tabloda bu üç hedef türü ve amaçları özetlenmiştir.

Tür	Açıklama	Kullanım örnekleri
Barındırılan	Gezinme ana makinesinin tamamını doldurur. Yani barındırılan bir hedefin boyutu, gezinme ana makinesinin boyutuyla aynıdır ve önceki hedefler görünmez.	Ana ve ayrıntı ekranları.
Dialog	Yer paylaşımlı kullanıcı arayüzü bileşenlerini gösterir. Bu kullanıcı arayüzü, gezinme ana makinesinin konumuna veya boyutuna bağlı değildir. Önceki varış noktaları, varış noktasının altında görünür.	Uyarılar, seçimler, formlar.
Etkinlik	Uygulamadaki benzersiz ekranları veya özellikleri temsil eder.	Gezinme bileşeninden ayrı olarak yönetilen yeni bir Android etkinliği başlatan gezinme grafiğinin çıkış noktası olarak kullanılır. Modern Android geliştirmede uygulamalar tek bir etkinlikten oluşur. Bu nedenle etkinlik hedefleri, üçüncü taraf etkinlikleriyle etkileşimde bulunurken veya taşıma işlemi kapsamında en iyi şekilde kullanılır.

Bu dokümanda, en yaygın ve temel hedefler olan barındırılan hedeflere ilişkin örnekler yer almaktadır. Diğer hedefler hakkında bilgi edinmek için aşağıdaki kılavuzları inceleyin:

• İletişim kutusu hedefleri
• Etkinlik hedefleri

Çerçeveler

Her durumda aynı genel iş akışı geçerli olsa da gezinme ana makinesini ve grafiğini nasıl oluşturacağınız kullandığınız kullanıcı arayüzü çerçevesine bağlıdır.

• Oluşturma: NavHost bileşenini kullanın. Kotlin DSL'yi kullanarak NavGraph ekleyin. Grafiği iki şekilde oluşturabilirsiniz:
  • NavHost'un bir parçası olarak: Gezinme grafiğini doğrudan NavHost ekleme işleminin bir parçası olarak oluşturun.
  • Programlı olarak: NavGraph oluşturmak ve doğrudan NavHost'e iletmek için NavController.createGraph() yöntemini kullanın.
• Parçalar: Parçaları görünümler kullanıcı arayüzü çerçevesiyle kullanırken ana makine olarak NavHostFragment kullanın. Gezinme grafiği oluşturmanın birkaç yolu vardır:
  • Programatik olarak: Kotlin DSL'yi kullanarak bir NavGraph oluşturun ve doğrudan NavHostFragment'a uygulayın.
    • Hem fragmanlar hem de Compose için Kotlin DSL ile kullanılan createGraph() işlevi aynıdır.
  • XML: Gezinme ana makinenizi ve grafiğinizi doğrudan XML olarak yazın.
  • Android Studio düzenleyicisi: Grafiğinizi XML kaynak dosyası olarak oluşturmak ve ayarlamak için Android Studio'daki GUI düzenleyiciyi kullanın.

Not: NavController aracılığıyla grafikle etkileşime geçme şekliniz, farklı çerçeveler arasında benzerdir. Daha fazla bilgi için Hedefe gitme kılavuzuna bakın.

Oluştur

Oluştur'da, rota tanımlamak için serileştirilebilir bir nesne veya sınıf kullanın. Rota, bir hedefe nasıl ulaşılacağını açıklar ve hedefin gerektirdiği tüm bilgileri içerir.

Rota türleriniz için gerekli serileştirme ve seri bozma yöntemlerini otomatik olarak oluşturmak üzere @Serializable ek açıklamasını kullanın. Bu ek açıklama, Kotlin Serileştirme eklentisi tarafından sağlanır. Bu eklentiyi eklemek için bu talimatları uygulayın.

Rotalarınızı tanımladıktan sonra gezinme grafiğinizi oluşturmak için NavHost bileşenini kullanın. Aşağıdaki örneği inceleyin:

@Serializable
object Profile
@Serializable
object FriendsList

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
    // Add more destinations similarly.
}

1. Serileştirilebilir nesne, Profile ve FriendsList olmak üzere iki rotanın her birini temsil eder.
2. NavHost bileşenine yapılan çağrı, başlangıç hedefi için bir NavController ve bir rota iletiyor.
3. NavHost işlevine iletilen lambda işlevi, nihayetinde NavController.createGraph() işlevini çağırır ve bir NavGraph döndürür.
4. Her rota, NavGraphBuilder.composable<T>() işlevine tür bağımsız değişkeni olarak sağlanır. Bu işlev, hedefi elde edilen NavGraph değerine ekler.
5. composable'e iletilen lambda, NavHost'un söz konusu hedef için gösterdiği değerdir.

Dikkat: composable()'e bir tür yerine bir route dizesini veya tam sayı id'ı iletebilirsiniz. Ancak bu, hedefe ek bağımsız değişkenler göndermeyi çok daha zor hale getirir.

Lambdayı anlama

NavGraph değerini oluşturan lambda işlevini daha iyi anlamak için, önceki snippet'tekiyle aynı grafiği oluşturmak için NavGraph değerini NavController.createGraph() kullanarak ayrı olarak oluşturabileceğinizi ve doğrudan NavHost değerine iletebileceğinizi unutmayın:

val navGraph by remember(navController) {
  navController.createGraph(startDestination = Profile)) {
    composable<Profile> { ProfileScreen( /* ... */ ) }
    composable<FriendsList> { FriendsListScreen( /* ... */ ) }
  }
}
NavHost(navController, navGraph)

Önemli: NavController, tek bir NavHost bileşeniyle ilişkilendirilir. NavHost, NavController'a gezinme grafiğine erişim sağlar. Bir hedefe gitmek için NavController'ü kullandığınızda NavController'ün ilişkili NavHost ile etkileşime girmesine neden olursunuz.

Bağımsız değişkenleri iletme

Bir hedefe veri iletmeniz gerekiyorsa rotayı parametreleri olan bir sınıfla tanımlayın. Örneğin, Profile rotası name parametresi içeren bir veri sınıfıdır.

@Serializable
data class Profile(val name: String)

Bu hedefe bağımsız değişken iletmeniz gerektiğinde, bağımsız değişkenleri sınıf kurucusuna ileterek rota sınıfınızın bir örneğini oluşturursunuz.

Not: Parametre içeren bir rota için data class, parametre içermeyen bir rota için object veya data object kullanın.

İsteğe bağlı bağımsız değişkenler için varsayılan değere sahip boş bırakılabilir alanlar oluşturun.

@Serializable
data class Profile(val nickname: String? = null)

Rota örneğini alma

Dönüşüm yolu örneğini NavBackStackEntry.toRoute() veya SavedStateHandle.toRoute() ile alabilirsiniz. composable() kullanarak bir hedef oluşturduğunuzda NavBackStackEntry parametre olarak kullanılabilir.

@Serializable
data class Profile(val name: String)

val navController = rememberNavController()

NavHost(navController = navController, startDestination = Profile(name="John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(name = profile.name) }
}

Bu snippet'te aşağıdakilere dikkat edin:

• Profile rotası, name için bağımsız değişken olarak "John Smith" ile birlikte navigasyon grafiğindeki başlangıç hedefini belirtir.
• Hedefin kendisi composable<Profile>{} bloğudur.
• ProfileScreen bileşeni, kendi name bağımsız değişkeni için profile.name değerini alır.
• Bu nedenle, "John Smith" değeri ProfileScreen'e iletilir.

Minimal örnek

NavController ve NavHost'un birlikte çalıştığına dair eksiksiz bir örnek:

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Define the ProfileScreen composable.
@Composable
fun ProfileScreen(
    profile: Profile
    onNavigateToFriendsList: () -> Unit,
  ) {
  Text("Profile for ${profile.name}")
  Button(onClick = { onNavigateToFriendsList() }) {
    Text("Go to Friends List")
  }
}

// Define the FriendsListScreen composable.
@Composable
fun FriendsListScreen(onNavigateToProfile: () -> Unit) {
  Text("Friends List")
  Button(onClick = { onNavigateToProfile() }) {
    Text("Go to Profile")
  }
}

// Define the MyApp composable, including the `NavController` and `NavHost`.
@Composable
fun MyApp() {
  val navController = rememberNavController()
  NavHost(navController, startDestination = Profile(name = "John Smith")) {
    composable<Profile> { backStackEntry ->
        val profile: Profile = backStackEntry.toRoute()
        ProfileScreen(
            profile = profile,
            onNavigateToFriendsList = {
                navController.navigate(route = FriendsList)
            }
        )
    }
    composable<FriendsList> {
      FriendsListScreen(
        onNavigateToProfile = {
          navController.navigate(
            route = Profile(name = "Aisha Devi")
          )
        }
      )
    }
  }
}

Snippet'te gösterildiği gibi, NavController öğesini bileşenlerinize iletmek yerine NavHost öğesine bir etkinlik gösterin. Yani, derlenebilir öğelerinizde NavHost'ın NavController.navigate()'yi çağıran bir lambda geçirdiği () -> Unit türüne sahip bir parametre olmalıdır.

Not: Rota sınıfının parametrelerini kullanarak verileri belirli bir hedefe tam tür güvenliğiyle iletebilirsiniz. Örneğin, önceki kodda Profile.name, name'un her zaman bir String olmasını sağlar.

Parçalar

Önceki bölümlerde belirtildiği gibi, parçaları kullanırken Kotlin DSL, XML veya Android Studio düzenleyiciyi kullanarak programatik olarak bir gezinme grafiği oluşturabilirsiniz.

Aşağıdaki bölümlerde bu farklı yaklaşımlar ayrıntılı olarak açıklanmıştır.

Not: Gezinme bileşeni, birden fazla parça hedefi olan tek bir ana etkinliğe sahip uygulamalar için tasarlanmıştır. Ana etkinlik bir gezinme grafiğiyle ilişkilendirilir ve hedefleri gerektiği gibi değiştirmekten sorumlu bir NavHostFragment içerir. Birden fazla etkinlik hedefi olan bir uygulamada her etkinliğin kendi gezinme grafiği vardır.

Programatik

Kotlin DSL, parçalar içeren bir gezinme grafiği oluşturmanın programatik bir yolunu sağlar. Bu yöntem, birçok açıdan XML kaynak dosyasını kullanmaktan daha düzenli ve moderndir.

İki ekranlı bir gezinme grafiği uygulayan aşağıdaki örneği inceleyin.

Öncelikle, app:navGraph öğesi içermeyen NavHostFragment öğesini oluşturmanız gerekir:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

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

Ardından, NavHostFragment öğesinin id değerini NavController.findNavController öğesine iletin. Bu işlem, NavController'ı NavHostFragment ile ilişkilendirir.

Ardından, NavController.createGraph() çağrısı grafiği NavController'a ve dolayısıyla NavHostFragment'a bağlar:

@Serializable
data class Profile(val name: String)

@Serializable
object FriendsList

// Retrieve the NavController.
val navController = findNavController(R.id.nav_host_fragment)

// Add the graph to the NavController with `createGraph()`.
navController.graph = navController.createGraph(
    startDestination = Profile(name = "John Smith")
) {
    // Associate each destination with one of the route constants.
    fragment<ProfileFragment, Profile> {
        label = "Profile"
    }

    fragment<FriendsListFragment, FriendsList>() {
        label = "Friends List"
    }

    // Add other fragment destinations similarly.
}

DSL'yi bu şekilde kullanmak, Oluşturma ile ilgili önceki bölümde açıklanan iş akışına çok benzer. Örneğin, hem orada hem de burada NavController.createGraph() işlevi NavGraph değerini oluşturur. Benzer şekilde, NavGraphBuilder.composable() grafiğe birleştirilebilir hedefler eklerken burada NavGraphBuilder.fragment() bir parça hedefi ekler.

Kotlin DSL'nin nasıl kullanılacağı hakkında daha fazla bilgi için NavGraphBuilder DSL ile grafik oluşturma başlıklı makaleyi inceleyin.

XML

XML'i doğrudan kendiniz yazabilirsiniz. Aşağıdaki örnek, önceki bölümdeki iki ekranlı örneği yansıtır ve ona eşdeğerdir.

Öncelikle bir NavHostFragment oluşturun. Bu, gerçek navigasyon grafiğini içeren navigasyon ana makinesi olarak kullanılır.

NavHostFragment'ün minimum uygulaması:

<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <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:navGraph="@navigation/nav_graph" />

</FrameLayout>

NavHostFragment, app:navGraph özelliğini içeriyor. Gezinme grafiğinizi gezinme ana makinesine bağlamak için bu özelliği kullanın. Aşağıda, grafiği nasıl uygulayabileceğinize dair bir örnek verilmiştir:

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

    <fragment
        android:id="@+id/profile"
        android:name="com.example.ProfileFragment"
        android:label="Profile">

        <!-- Action to navigate from Profile to Friends List. -->
        <action
            android:id="@+id/action_profile_to_friendslist"
            app:destination="@id/friendslist" />
    </fragment>

    <fragment
        android:id="@+id/friendslist"
        android:name="com.example.FriendsListFragment"
        android:label="Friends List" />

    <!-- Add other fragment destinations similarly. -->
</navigation>

Farklı hedefler arasındaki bağlantıları tanımlamak için işlemleri kullanırsınız. Bu örnekte, profile parçası friendslist'a giden bir işlem içerir. Daha fazla bilgi için Gezinme işlemlerini ve parçalarını kullanma başlıklı makaleyi inceleyin.

Not: DSL örneğinde, söz konusu bağlamda geçerli olmadıkları için işlemler tanımlanmaz. DSL'yi kullanırken doğrudan NavController.navigate() kullanın.

Düzenleyici

Android Studio'daki Gezinme Düzenleyici'yi kullanarak uygulamanızın gezinme grafiğini yönetebilirsiniz. Bu, önceki bölümde görüldüğü gibi NavigationFragment XML'inizi oluşturmak ve düzenlemek için kullanabileceğiniz bir kullanıcı arayüzüdür.

Daha fazla bilgi için Gezinme düzenleyici başlıklı makaleyi inceleyin.

İç içe yerleştirilmiş grafikler

İç içe yerleştirilmiş grafikleri de kullanabilirsiniz. Bu, navigasyon hedefi olarak bir grafik kullanmayı içerir. Daha fazla bilgi için İç içe yerleştirilmiş grafikler bölümüne bakın.

Daha fazla bilgi

Temel gezinme kavramları hakkında daha fazla bilgi için aşağıdaki kılavuzları inceleyin:

• Genel bakış: Gezinme bileşenine genel bakışı okuyun.
• Etkinlik hedefleri: Kullanıcıyı etkinliklere yönlendiren hedeflerin nasıl uygulanacağına dair örnekler.
• İletişim hedefleri: Kullanıcıyı bir iletişim kutusuna yönlendiren hedeflerin nasıl oluşturulacağına dair örnekler.
• Bir hedefe gitme: Bir hedeften diğerine nasıl gidileceğini kapsayan ayrıntılı bir kılavuz.
• İç içe yerleştirilmiş grafikler: Bir gezinme grafiğinin diğerine nasıl yerleştirileceğiyle ilgili ayrıntılı bir kılavuz.