Temel bilgileri anlama ve uygulama

Gezinme, kullanıcıların uygulamanızda nasıl hareket ettiğini açıklar. Kullanıcılar, genellikle kullanıcı arayüzü öğelerine dokunarak veya tıklayarak bu öğelerle etkileşim kurar ve uygulama, yeni içerik göstererek yanıt verir. Kullanıcı önceki içeriğe dönmek isterse geri hareketini kullanır veya geri düğmesine dokunur.

Gezinme durumunu modelleme

Bu davranışı modellemenin kolay bir yolu, içerik yığını kullanmaktır. Kullanıcı yeni içeriğe ileri doğru gittiğinde bu içerik yığının en üstüne eklenir. Kullanıcı bu içerikten geri gittiğinde içerik yığından çıkarılır ve önceki içerik gösterilir. Gezinme terimleriyle ifade etmek gerekirse bu yığın, kullanıcının geri dönebileceği içeriği temsil ettiği için genellikle eski yığın olarak adlandırılır.

Eski yığın oluşturma

Navigation 3'te eski yığın aslında içerik barındırmaz. Bunun yerine, anahtar olarak bilinen içerik referansları barındırır. Anahtarlar herhangi bir türde olabilir ancak genellikle basit, serileştirilebilir veri sınıflarıdır. İçerik yerine referans kullanmanın aşağıdaki avantajları vardır:

• Tuşları eski yığına göndererek gezinmek kolaydır.
• Anahtarlar serileştirilebilir olduğu sürece eski yığın, kalıcı depolama alanına kaydedilebilir. Böylece yapılandırma değişiklikleri ve işlem sonlandırma sırasında korunabilir. Bu önemlidir, çünkü kullanıcılar uygulamanızdan ayrılıp daha sonra geri döndüklerinde aynı içeriğin gösterilmesini ve kaldıkları yerden devam etmeyi beklerler. Daha fazla bilgi için Eski yığınınızı kaydetme başlıklı makaleyi inceleyin.

Navigation 3 API'deki önemli bir kavram, eski yığının size ait olmasıdır. Kitaplık:

• Eski yığınınızın, anlık görüntü durumu destekli bir List<T> olmasını bekler. Burada T, eski yığınınızın keys türüdür. Any kullanabilir veya kendi daha güçlü türde anahtarlarınızı sağlayabilirsiniz. "Push" veya "pop" terimlerini gördüğünüzde, temel uygulama bir listenin sonuna öğe eklemek veya kaldırmaktır.
• Eski yığınınızı gözlemler ve durumunu NavDisplay kullanarak kullanıcı arayüzüne yansıtır.

Aşağıdaki örnekte, anahtarların ve eski yığının nasıl oluşturulacağı ve kullanıcı gezinme etkinliklerine yanıt olarak eski yığının nasıl değiştirileceği gösterilmektedir:

// Define keys that will identify content
data object ProductList
data class ProductDetail(val id: String)

@Composable
fun MyApp() {

    // Create a back stack, specifying the key the app should start with
    val backStack = remember { mutableStateListOf<Any>(ProductList) }

    // Supply your back stack to a NavDisplay so it can reflect changes in the UI
    // ...more on this below...

    // Push a key onto the back stack (navigate forward), the navigation library will reflect the change in state
    backStack.add(ProductDetail(id = "ABC"))

    // Pop a key off the back stack (navigate back), the navigation library will reflect the change in state
    backStack.removeLastOrNull()
}
BasicSnippets.kt

Anahtarları içeriğe çözümleme

İçerik, Navigation 3'te composable işlev içeren bir sınıf olan NavEntry kullanılarak modellenir. Kullanıcının ileri ve geri gidebileceği tek bir içerik parçası olan hedefi temsil eder.

NavEntry, içerikle ilgili bilgileri barındıran meta veriler de içerebilir. Bu meta veriler, NavDisplay gibi kapsayıcı nesneler tarafından okunarak NavEntry içeriğinin nasıl gösterileceğine karar vermelerine yardımcı olabilir. Örneğin, meta veriler belirli bir NavEntry için varsayılan animasyonları geçersiz kılmak amacıyla kullanılabilir. NavEntry metadata, String anahtarlarını Any değerleriyle eşleyerek çok yönlü veri depolama imkanı sunar.

key öğesini NavEntry öğesine dönüştürmek için bir giriş sağlayıcı oluşturun. Bu işlev, key kabul eder ve bu key için bir NavEntry döndürür. Genellikle NavDisplay oluşturulurken lambda parametresi olarak tanımlanır.

Giriş sağlayıcı oluşturmanın iki yolu vardır: Doğrudan lambda işlevi oluşturarak veya entryProvider DSL'yi kullanarak.

Doğrudan giriş sağlayıcı işlevi oluşturma

Genellikle her anahtarınız için bir dal içeren when ifadesini kullanarak bir giriş sağlayıcı işlevi oluşturursunuz.

entryProvider = { key ->
    when (key) {
        is ProductList -> NavEntry(key) { Text("Product List") }
        is ProductDetail -> NavEntry(
            key,
            metadata = mapOf("extraDataKey" to "extraDataValue")
        ) { Text("Product ${key.id} ") }

        else -> {
            NavEntry(Unit) { Text(text = "Invalid Key: $it") }
        }
    }
}
BasicSnippets.kt

entryProvider DSL'sini kullanma

entryProvider DSL, her bir anahtar türünüz için test yapma ve her biri için NavEntry oluşturma ihtiyacını ortadan kaldırarak lambda işlevinizi basitleştirebilir. Bunun için entryProvider oluşturucu işlevini kullanın. Ayrıca, anahtar bulunamazsa varsayılan yedek davranışı (hata döndürme) içerir.

entryProvider = entryProvider {
    entry<ProductList> { Text("Product List") }
    entry<ProductDetail>(
        metadata = mapOf("extraDataKey" to "extraDataValue")
    ) { key -> Text("Product ${key.id} ") }
}
BasicSnippets.kt

Snippet'te şunlara dikkat edin:

• entry, belirli bir tür ve composable içerikle NavEntry tanımlamak için kullanılır.
• entry, NavEntry.metadata değerini ayarlamak için bir metadata parametresi kabul eder.

Eski yığını görüntüleme

Eski yığın, uygulamanızın gezinme durumunu temsil eder. Eski yığın her değiştiğinde uygulama kullanıcı arayüzü, yeni eski yığın durumunu yansıtmalıdır. Navigation 3'te NavDisplay, eski yığınınızı gözlemler ve kullanıcı arayüzünü buna göre günceller. Aşağıdaki parametrelerle oluşturun:

• Eski yığınınız: Bu, SnapshotStateList<T> türünde olmalıdır. Burada T, eski yığın anahtarlarınızın türüdür. Bu, gözlemlenebilir bir List olduğundan değiştiğinde NavDisplay öğesinin yeniden oluşturulmasını tetikler.
• Eski yığınınızdaki anahtarları NavEntry nesnelerine dönüştürmek için bir entryProvider.
• İsteğe bağlı olarak onBack parametresine bir lambda sağlayın. Bu yöntem, kullanıcı bir geri etkinliği tetiklediğinde çağrılır.

Aşağıdaki örnekte NavDisplay oluşturma işlemi gösterilmektedir.

data object Home
data class Product(val id: String)

@Composable
fun NavExample() {

    val backStack = remember { mutableStateListOf<Any>(Home) }

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        entryProvider = { key ->
            when (key) {
                is Home -> NavEntry(key) {
                    ContentGreen("Welcome to Nav3") {
                        Button(onClick = {
                            backStack.add(Product("123"))
                        }) {
                            Text("Click to navigate")
                        }
                    }
                }

                is Product -> NavEntry(key) {
                    ContentBlue("Product ${key.id} ")
                }

                else -> NavEntry(Unit) { Text("Unknown route") }
            }
        }
    )
}
BasicSnippets.kt

Varsayılan olarak NavDisplay, tek bölmeli bir düzende eski yığının en üstündeki NavEntry öğesini gösterir. Aşağıdaki kayıtta bu uygulamanın çalıştığı gösterilmektedir:

Hedef yaşam döngüsü

NavDisplay, hem Scene düzeyindeki kısıtlamalara hem de giriş düzeyindeki kısıtlamalara göre bir NavEntry öğesinin yaşam döngüsü durumunu sınırlamak için özel LifecycleOwner'ler kullanır.

Compose'daki yaşam döngüleri hakkında daha fazla bilgi için Jetpack Compose'da yaşam döngüsü başlıklı makaleyi inceleyin.

Sahne düzeyinde yaşam döngüsü kısıtlamaları

NavDisplay, etkin Scene'lerin yaşam döngüsünü yönetir. Sahne düzeyindeki sınırlar şu şekilde belirlenir:

Yer paylaşımı olmayan sahneler için:

• RESUMED: Yalnızca sahne geçişi tamamlandığında ve üzerinde etkin bir yer paylaşımı sahnesi gösterilmediğinde izin verilir.
• STARTED: İleri veya geri gitme gibi sahne geçişleri sırasında ya da bir yer paylaşımla kaplandığında STARTED ile sınırlıdır.

İletişim kutuları veya alt sayfalar gibi yer paylaşımlı sahneler için:

• RESUMED: Yalnızca en üstteki, şu anda etkin olan yer paylaşımı sahnesi için izin verilir.
• STARTED: Daha yeni bir yer paylaşımıyla kapsanan tüm temel yer paylaşımı sahneleri için STARTED ile sınırlıdır.

Başlangıç düzeyi yaşam döngüsü durumu

Kitaplık, her bir NavEntry öğesinin maksimum yaşam döngüsü durumunu, eski yığındaki varlığına göre yönetir:

• RESUMED: Giriş, mevcut eski yığında varsa yaşam döngüsünün RESUMED değerine kadar çıkmasına izin verilir (sahne düzeyindeki sınıra tabidir).
• CREATED: Giriş artık eski yığında değilse (ör. çıkarılmış ancak animasyonla çıkarken ekranda hâlâ oluşturuluyorsa) kitaplık, yaşam döngüsünü kesin olarak CREATED ile sınırlandırır. Bu sınır, arka plandaki veya çıkış yapan girişlerin, çıkış geçişlerini tamamlarken akışları toplama ya da RESUMED veya STARTED durumlarına bağlı eş yordamları başlatma gibi etkin işleri yürütmeyi durdurmasını sağlar.

Nasıl birleştirilirler?

Örneğin, bir NavEntry öğesinin nihai yaşam döngüsü durumu şu şekilde çözümlenir:

Özet

Aşağıdaki şemada, verilerin Navigation 3'teki çeşitli nesneler arasında nasıl aktığı gösterilmektedir:

1. Gezinme etkinlikleri değişiklikleri başlatır. Anahtarlar, kullanıcı etkileşimlerine yanıt olarak eski yığına eklenir veya eski yığından kaldırılır.

2. Eski yığın durumundaki değişiklik, içerik alma işlemini tetikler. NavDisplay (eski yığın oluşturan bir composable), eski yığını gözlemler. Varsayılan yapılandırmasında, en üstteki eski yığın girişini tek bölmeli bir düzende gösterir. Eski yığındaki en üstteki anahtar değiştiğinde NavDisplay, giriş sağlayıcıdan ilgili içeriği istemek için bu anahtarı kullanır.

3. Giriş sağlayıcı, içerik sağlar. Giriş sağlayıcı, bir anahtarı NavEntry değerine çözümleyen bir işlevdir. NavDisplay anahtarını alan giriş sağlayıcı, hem anahtarı hem de içeriği barındıran ilişkili NavEntry değerini sağlar.

4. İçerik gösterilir. NavDisplay, NavEntry değerini alır ve içeriği gösterir.