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 bir hedefi ve bunlar arasındaki bağlantıları içeren bir veri yapısıdır.

Not: Gezinme grafiği, NavController içinde kullanıcının son ziyaret ettiği hedefleri barındıran bir yığın olan geri yığından 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ı özetlenmektedir.

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 ekran ve ayrıntı ekranları.
Dialog	Yer paylaşımı kullanıcı arayüzü bileşenlerini sunar. Bu kullanıcı arayüzü, gezinme ana makinesinin konumuna veya boyutuna bağlı değildir. Önceki hedefler hedefin 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ğine çıkış noktası görevi verir. Modern Android geliştirmede uygulama tek bir etkinlikten oluşur. Bu nedenle, etkinlik hedeflerinin en iyi şekilde kullanılması, üçüncü taraf etkinlikleriyle etkileşim kurduğunuzda veya taşıma sürecinin bir parçası olarak gerçekleştirilir.

Bu dokümanda, en yaygın ve temel hedefler olan barındırılan hedef örnekleri bulunmaktadır. Diğer hedefler hakkında bilgi için aşağıdaki kılavuzlara göz atın:

• İletişim kutusu hedefleri
• Etkinlik hedefleri

Çerçeveler

Her durum için aynı genel iş akışı geçerli olsa da gezinme ana makinesi ve grafiği tam olarak nasıl oluşturacağınız, kullandığınız kullanıcı arayüzü çerçevesine bağlıdır.

• Oluştur: NavHost composable'ı kullanın. Kotlin DSL'yi kullanarak bir 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.
  • Programatik olarak: NavGraph oluşturmak ve bunu doğrudan NavHost öğesine iletmek için NavController.createGraph() yöntemini kullanın.
• Parçalar: Görünümler kullanıcı arayüzü çerçevesiyle parçaları kullanırken ana makine olarak bir NavHostFragment kullanın. Gezinme grafiği oluşturmanın birkaç yolu vardır:
  • Programatik olarak: Bir NavGraph oluşturmak ve bunu doğrudan NavHostFragment üzerinde uygulamak için Kotlin DSL'yi kullanın.
    • Hem parçalar hem de Oluştur için Kotlin DSL ile kullanılan createGraph() işlevi aynıdır.
  • XML: Gezinme ana makinenizi ve grafiğinizi doğrudan XML'e 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 üzerinden grafikle etkileşim kurma biçiminiz, iki çerçeve arasında da benzerdir. Daha fazla ayrıntı için Bir hedefe gitme rehberine bakın.

Oluştur

Compose'da yönlendirme tanımlamak için seri hale getirilebilir bir nesne veya sınıf kullanın. Rota, bir hedefe nasıl ulaşılacağını açıklar ve varış noktasının gerektirdiği tüm bilgileri içerir. Rotalarınızı tanımladıktan sonra, navigasyon grafiğinizi oluşturmak için NavHost composable'ı 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, iki rotanın her birini (Profile ve FriendsList) temsil eder.
2. NavHost composable'a yapılan çağrı, bir NavController ve başlangıç hedefi için bir rota iletir.
3. NavHost öğesine iletilen lambda, sonuçta NavController.createGraph() yöntemini çağırır ve NavGraph değeri döndürür.
4. Her rota, NavGraphBuilder.composable<T>() öğesine bir tür bağımsız değişkeni olarak sağlanır ve hedefi elde edilen NavGraph öğesine ekler.
5. composable parametresine iletilen lambda, NavHost tarafından bu hedef için gösterilir.

Dikkat: composable() öğesine bir tür iletmek yerine, bir route dizesi veya tam sayı id iletebilirsiniz. Ancak bu durum, hedefe ek bağımsız değişkenlerin iletilmesini yönetmeyi çok daha zorlaştırır.

Lambda'yı anlama

NavGraph öğesini oluşturan lambda'yı daha iyi anlamak için önceki snippet'tekiyle aynı grafiği oluşturmak isterseniz NavController.createGraph() kullanarak NavGraph öğesini ayrı olarak oluşturup doğrudan NavHost öğesine aktarabilirsiniz:

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

Önemli: NavController tek bir NavHost composable ile ilişkilendirilir. NavHost, gezinme grafiğine NavController erişimi sağlar. Bir hedefe gitmek için NavController öğesini kullandığınızda NavController öğesinin, ilişkilendirilmiş NavHost ile etkileşim kurmasına neden olursunuz.

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

Verileri bir hedefe iletmeniz gerekiyorsa rotayı parametre içeren bir sınıfla tanımlayın. Örneğin, Profile rotası, name parametresine sahip bir veri sınıfıdır.

@Serializable
data class Profile(val name: String)

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

Not: Bağımsız değişkenler içeren bir rota için data class; bağımsız değişken içermeyen bir rota için object veya data object kullanın.

Rota örneği alma

NavBackStackEntry.toRoute() veya SavedStateHandle.toRoute() ile rota örneğini alabilirsiniz. composable() işlevini kullanarak bir hedef oluşturduğunuzda parametre olarak NavBackStackEntry 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ı, gezinme grafiğinde başlangıç hedefini belirtir ve name için bağımsız değişken olarak "John Smith" kullanılır.
• Hedefin kendisi composable<Profile>{} bloku.
• ProfileScreen composable, kendi name bağımsız değişkeni için profile.name değerini alır.
• Dolayısıyla, "John Smith" değeri ProfileScreen öğesine iletilir.

Minimum örnek

NavController ve NavHost öğelerinin birlikte çalışmasına ilişkin tam 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 composable'larınıza iletmek yerine NavHost öğesine bir etkinlik sunun. Yani composable'larınızın () -> Unit türünde bir parametresi olmalıdır. Bu parametre için NavHost, NavController.navigate() çağıran bir lambda iletir.

Not: Rota sınıfının parametrelerini kullanarak verileri tam tür güvenlikle belirtilen hedefe aktarabilirsiniz. Örneğin, önceki kodda Profile.name, name değerinin her zaman 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üzenleyicisini kullanarak programatik olarak bir gezinme grafiği oluşturma seçeneğiniz vardır.

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

Not: Gezinme bileşeni, birden çok parça hedefine sahip tek bir ana etkinliği olan uygulamalar için tasarlanmıştır. Ana etkinlik, bir gezinme grafiğiyle ilişkilendirilir ve hedefleri gerektiğinde 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 olarak

Kotlin DSL, parçalardan oluşan bir gezinme grafiği oluşturmak için programatik bir yöntem sunar. Birçok açıdan, bu yöntem, XML kaynak dosyası kullanmaktan daha iyi ve moderndir.

İki ekranlı gezinme grafiğinin uygulandığı aşağıdaki örneği düşünün.

İlk olarak NavHostFragment öğesini oluşturmanız gerekir. Bu işlem, app:navGraph öğesi içermemelidir:

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

Sonra, NavHostFragment öğesinin id öğesini NavController.findNavController adlı kullanıcıya iletin. Bu işlem, NavController'ı NavHostFragment ile ilişkilendirir.

Ardından, NavController.createGraph() çağrısı, grafiği NavController etiketine ve bunun sonucunda da NavHostFragment öğesine 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'nin bu şekilde kullanılması, Oluşturma konusunda önceki bölümde açıklanan iş akışına çok benzer. Örneğin, NavController.createGraph() işlevi hem burada hem de orada NavGraph oluşturur. Benzer şekilde, NavGraphBuilder.composable() grafiğe derlenebilir hedefler eklerken NavGraphBuilder.fragment() parça hedefi ekler.

Kotlin DSL'nin nasıl kullanılacağı hakkında daha fazla bilgi için NavGraphBuilder DSL ile grafik oluşturma bölümüne bakın.

XML

XML dosyasını doğrudan kendiniz yazabilirsiniz. Aşağıdaki örnek, önceki bölümde yer alan iki ekran örneğini yansıtır ve eşdeğerdir.

İlk olarak bir NavHostFragment oluşturun. Bu, gerçek gezinme grafiğini içeren gezinme ana makinesi görevi görür.

Minimum bir NavHostFragment kullanımı:

<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şlemler kullanırsınız. Bu örnekte, profile parçası friendslist adresine giden bir işlem içeriyor. Daha fazla bilgi için Gezinme işlemlerini ve parçalarını kullanma bölümüne bakın.

Not: DSL örneğinde, işlemler söz konusu bağlamda geçerli olmadığından tanımlamaz. 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österildiği gibi, NavigationFragment XML dosyanızı oluşturmak ve düzenlemek için kullanabileceğiniz bir GUI'dir.

Daha fazla bilgi için Gezinme düzenleyici konusuna bakın.

İç içe yerleştirilmiş grafikler

İç içe yerleştirilmiş grafikleri de kullanabilirsiniz. Bu, bir grafiği gezinme hedefi olarak kullanmayı içerir. Daha fazla bilgi için İç içe yerleştirilmiş grafikler konusuna bakın.

Diğer Okumalar

Daha temel gezinme kavramları için aşağıdaki kılavuzlara bakın:

• Genel Bakış: Navigasyon bileşeninin genel bakışını okuduğunuzdan emin olun.
• Etkinlik hedefleri: Kullanıcıyı etkinliklere yönlendiren hedeflerin nasıl uygulanacağına dair örnekler.
• İletişim kutusu 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 ele alan ayrıntılı bir kılavuz.
• İç içe yerleştirilmiş grafikler: Bir gezinme grafiğini bir başkasının içine yerleştirmeyle ilgili ayrıntılı kılavuz.