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.

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.

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.

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.

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)

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.

İ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.

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.

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.

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.