Sahneleri kullanarak özel düzenler oluşturma

Navigation 3, uygulamanızın kullanıcı arayüzü akışını Sahneler aracılığıyla yönetmek için güçlü ve esnek bir sistem sunar. Sahneler, son derece özelleştirilmiş düzenler oluşturmanıza, farklı ekran boyutlarına uyum sağlamanıza ve karmaşık çok bölmeli deneyimleri sorunsuz bir şekilde yönetmenize olanak tanır.

Sahneleri Anlama

Navigation 3'te Scene, bir veya daha fazla NavEntry örneğini oluşturmak için kullanılan temel birimdir. Scene, eski yığınınızdaki içeriklerin gösterimini içerebilen ve yönetebilen, kullanıcı arayüzünüzün ayrı bir görsel durumu veya bölümü olarak düşünülebilir.

Her Scene örneği, key ve Scene sınıfı ile benzersiz şekilde tanımlanır. Bu benzersiz tanımlayıcı, Scene değiştiğinde üst düzey animasyonu yönlendirdiği için çok önemlidir.

Scene arayüzü aşağıdaki özelliklere sahiptir:

  • key: Any: Bu belirli Scene örneği için benzersiz bir tanımlayıcı. Bu anahtar, Scene sınıfıyla birlikte özellikle animasyon amacıyla ayırt ediciliği sağlar.
  • entries: List<NavEntry<T>>: Bu, Scene öğesinin görüntülemekten sorumlu olduğu NavEntry nesnelerinin listesidir. Önemli olarak, aynı NavEntry bir geçiş sırasında (ör. paylaşılan bir öğe geçişinde) birden fazla Scenes içinde gösteriliyorsa içeriği yalnızca bunu görüntüleyen en son hedef Scene tarafından oluşturulur.
  • previousEntries: List<NavEntry<T>>: Bu özellik, mevcut Scene konumundan "geri" işlemi yapılması durumunda ortaya çıkacak NavEntry'leri tanımlar. Doğru tahmin edilen geri gitme durumunu hesaplamak için gereklidir. NavDisplay, farklı bir sınıfa ve/veya anahtara sahip bir Sahne olabilecek doğru önceki durumu tahmin edip bu duruma geçiş yapabilir.
  • content: @Composable () -> Unit: Bu, Scene öğesinin entries öğesini ve bu Scene öğesine özgü tüm çevreleyen kullanıcı arayüzü öğelerini nasıl oluşturduğunu tanımladığınız composable işlevdir.
  • metadata: Map<String, Any>: NavDisplay gibi diğer kitaplık bileşenlerine sahneye özgü bilgiler sağlar. Varsayılan olarak, entries içindeki son NavEntry değerinin metadata değerini döndürür.

Sahne stratejilerini anlama

SceneStrategy, geri yığındaki belirli bir NavEntry listesinin nasıl düzenleneceğini ve Scene'ye nasıl geçeceğini belirleyen mekanizmadır. Temel olarak, mevcut geri yığın girişleri sunulduğunda bir SceneStrategy kendisiyle ilgili iki temel soru sorar:

  1. Bu girişlerden Scene oluşturabilir miyim? SceneStrategy, verilen NavEntry'leri işleyebileceğini ve anlamlı bir Scene oluşturabileceğini (ör. iletişim kutusu veya çok bölmeli düzen) belirlerse işleme devam eder. Aksi takdirde, diğer stratejilerin Scene oluşturmasına olanak tanımak için null değerini döndürür.
  2. Bu durumda, bu girişleri Scene? Bir SceneStrategy, girişleri işlemeyi kabul ettiğinde Scene oluşturma ve belirtilen NavEntry'ların bu Scene içinde nasıl görüntüleneceğini tanımlama sorumluluğunu üstlenir.

SceneStrategy'nın temelinde calculateScene yöntemi bulunur:

@Composable
public fun calculateScene(
    entries: List<NavEntry<T>>,
    onBack: (count: Int) -> Unit,
): Scene<T>?
ScenesSnippets.kt

Bu yöntem, eski yığında geçerli List<NavEntry<T>> öğesini alan bir SceneStrategyScope üzerindeki uzantı işlevidir. Sağlanan girişlerden başarılı bir şekilde oluşturabiliyorsa Scene<T>, oluşturamıyorsa null değerini döndürmelidir.

SceneStrategyScope, SceneStrategy'nin ihtiyaç duyabileceği isteğe bağlı bağımsız değişkenleri (ör. onBack geri çağırma) korumakla sorumludur.

Sahneler ve sahne stratejileri birlikte nasıl çalışır?

NavDisplay, eski yığını gözlemleyen ve uygun Scene'ı belirleyip oluşturmak için SceneStrategy kullanan merkezi birleştirilebilir öğedir.

NavDisplay's sceneStrategy parametresi, görüntülenecek Scene değerini hesaplamaktan sorumlu bir SceneStrategy bekler. Sağlanan strateji (veya strateji zinciri) tarafından Scene hesaplanmazsa NavDisplay varsayılan olarak otomatik olarak SinglePaneSceneStrategy kullanmaya geri döner.

Etkileşimin dökümü:

  • Geri yığında anahtar eklediğinizde veya kaldırdığınızda (ör. backStack.add() veya backStack.removeLastOrNull() kullanarak) NavDisplay bu değişiklikleri gözlemler.
  • NavDisplay, yapılandırılmış SceneStrategy's calculateScene yöntemine NavEntrys öğelerinin mevcut listesini (arka yığın anahtarlarından türetilmiştir) iletir.
  • SceneStrategy, Scene değerini başarıyla döndürürse NavDisplay, Scene değerinin content değerini oluşturur. NavDisplay ayrıca Scene özelliklerine göre animasyonları ve tahmin edilen geri gitme özelliğini de yönetir.

Örnek: Tek bölmeli düzen (varsayılan davranış)

En basit özel düzen, tek bölmeli bir ekrandır. Başka bir SceneStrategy öncelikli değilse varsayılan davranış budur.

data class SinglePaneScene<T : Any>(
    override val key: Any,
    val entry: NavEntry<T>,
    override val previousEntries: List<NavEntry<T>>,
) : Scene<T> {
    override val entries: List<NavEntry<T>> = listOf(entry)
    override val content: @Composable () -> Unit = { entry.Content() }
}

/**
 * A [SceneStrategy] that always creates a 1-entry [Scene] simply displaying the last entry in the
 * list.
 */
public class SinglePaneSceneStrategy<T : Any> : SceneStrategy<T> {
    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? =
        SinglePaneScene(
            key = entries.last().contentKey,
            entry = entries.last(),
            previousEntries = entries.dropLast(1)
        )
}
ScenesSnippets.kt

Örnek: Temel liste-ayrıntı düzeni (özel sahne ve strateji)

Bu örnekte, iki koşula göre etkinleştirilen basit bir liste-ayrıntı düzeninin nasıl oluşturulacağı gösterilmektedir:

  1. Pencere genişliği, iki bölmeyi destekleyecek kadar geniştir (ör. en az WIDTH_DP_MEDIUM_LOWER_BOUND).
  2. Geri yığında, belirli meta veriler kullanılarak liste-ayrıntı düzeninde gösterilme desteği beyan edilmiş girişler bulunur.

Aşağıdaki snippet, ListDetailScene.kt için kaynak kodudur ve hem ListDetailScene hem de ListDetailSceneStrategy içerir:

// --- ListDetailScene ---
/**
 * A [Scene] that displays a list and a detail [NavEntry] side-by-side in a 40/60 split.
 *
 */
class ListDetailScene<T : Any>(
    override val key: Any,
    override val previousEntries: List<NavEntry<T>>,
    val listEntry: NavEntry<T>,
    val detailEntry: NavEntry<T>,
) : Scene<T> {
    override val entries: List<NavEntry<T>> = listOf(listEntry, detailEntry)
    override val content: @Composable (() -> Unit) = {
        Row(modifier = Modifier.fillMaxSize()) {
            Column(modifier = Modifier.weight(0.4f)) {
                listEntry.Content()
            }
            Column(modifier = Modifier.weight(0.6f)) {
                detailEntry.Content()
            }
        }
    }
}

@Composable
fun <T : Any> rememberListDetailSceneStrategy(): ListDetailSceneStrategy<T> {
    val windowSizeClass = currentWindowAdaptiveInfo().windowSizeClass

    return remember(windowSizeClass) {
        ListDetailSceneStrategy(windowSizeClass)
    }
}

// --- ListDetailSceneStrategy ---
/**
 * A [SceneStrategy] that returns a [ListDetailScene] if the window is wide enough, the last item
 * is the backstack is a detail, and before it, at any point in the backstack is a list.
 */
class ListDetailSceneStrategy<T : Any>(val windowSizeClass: WindowSizeClass) : SceneStrategy<T> {

    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? {

        if (!windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND)) {
            return null
        }

        val detailEntry =
            entries.lastOrNull()?.takeIf { it.metadata.contains(DetailKey) } ?: return null
        val listEntry = entries.findLast { it.metadata.contains(ListKey) } ?: return null

        // We use the list's contentKey to uniquely identify the scene.
        // This allows the detail panes to be displayed instantly through recomposition, rather than
        // having NavDisplay animate the whole scene out when the selected detail item changes.
        val sceneKey = listEntry.contentKey

        return ListDetailScene(
            key = sceneKey,
            previousEntries = entries.dropLast(1),
            listEntry = listEntry,
            detailEntry = detailEntry
        )
    }

    object ListKey : NavMetadataKey<Boolean>
    object DetailKey : NavMetadataKey<Boolean>
    companion object {

        /**
         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
         * as a list in the [ListDetailScene].
         */
        fun listPane() = metadata {
            put(ListKey, true)
        }

        /**
         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
         * as a list in the [ListDetailScene].
         */
        fun detailPane() = metadata {
            put(DetailKey, true)
        }
    }
}
ScenesSnippets.kt

Bu ListDetailSceneStrategy öğesini NavDisplay içinde kullanmak için entryProvider çağrılarınızı, liste düzeni olarak göstermek istediğiniz giriş için ListDetailScene.listPane() meta verilerini ve ayrıntı düzeni olarak göstermek istediğiniz giriş için ListDetailScene.detailPane() öğesini içerecek şekilde değiştirin. Ardından, tek pencereli senaryolarda varsayılan geri dönüşü kullanarak ListDetailSceneStrategy() değerini sceneStrategy olarak sağlayın:

// Define your navigation keys
@Serializable
data object ConversationList : NavKey

@Serializable
data class ConversationDetail(val id: String) : NavKey

@Composable
fun MyAppContent() {
    val backStack = rememberNavBackStack(ConversationList)
    val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>()

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        sceneStrategies = listOf(listDetailStrategy),
        entryProvider = entryProvider {
            entry<ConversationList>(
                metadata = ListDetailSceneStrategy.listPane()
            ) {
                Column(modifier = Modifier.fillMaxSize()) {
                    Text(text = "I'm a Conversation List")
                    Button(onClick = { backStack.addDetail(ConversationDetail("123")) }) {
                        Text(text = "Open detail")
                    }
                }
            }
            entry<ConversationDetail>(
                metadata = ListDetailSceneStrategy.detailPane()
            ) {
                Text(text = "I'm a Conversation Detail")
            }
        }
    )
}

private fun NavBackStack<NavKey>.addDetail(detailRoute: ConversationDetail) {

    // Remove any existing detail routes, then add the new detail route
    removeIf { it is ConversationDetail }
    add(detailRoute)
}
ScenesSnippets.kt

Kendi liste-ayrıntı sahnenizi oluşturmak istemiyorsanız sonraki bölümde gösterildiği gibi, anlamlı ayrıntılar ve yer tutucular için destek içeren Material liste-ayrıntı sahnesini kullanabilirsiniz.

Liste-ayrıntı içeriğini Material uyarlanabilir sahnesinde görüntüleme

Liste-ayrıntı düzeni kullanım alanında, androidx.compose.material3.adaptive:adaptive-navigation3 yapısı, liste-ayrıntı düzeni Scene oluşturan bir ListDetailSceneStrategy sağlar. Bu Scene karmaşık çok panelli düzenlemeleri (liste, ayrıntı ve ek paneller) otomatik olarak yönetir ve pencere boyutuna ve cihaz durumuna göre uyarlar.

Bir Materyal liste-ayrıntı düzeni Scene oluşturmak için aşağıdaki adımları uygulayın:

  1. Bağımlılığı ekleyin: Projenizin build.gradle.kts dosyasına androidx.compose.material3.adaptive:adaptive-navigation3 öğesini ekleyin.
  2. Girişlerinizi ListDetailSceneStrategy meta verileriyle tanımlayın: NavEntrys öğenizi uygun bölme gösterimi için işaretlemek üzere listPane(), detailPane() ve extraPane() kullanın. listPane() yardımcı aracı, öğe seçilmediğinde detailPlaceholder belirtmenize de olanak tanır.
  3. rememberListDetailSceneStrategy() işlevini kullanın: Bu composable işlev, NavDisplay tarafından kullanılabilen önceden yapılandırılmış bir ListDetailSceneStrategy sağlar.

Aşağıdaki snippet, Activity kullanımını gösteren örnek bir ListDetailSceneStrategy'dir:

@Serializable
object ProductList : NavKey

@Serializable
data class ProductDetail(val id: String) : NavKey

@Serializable
data object Profile : NavKey

class MaterialListDetailActivity : ComponentActivity() {

    @OptIn(ExperimentalMaterial3AdaptiveApi::class)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            Scaffold { paddingValues ->
                val backStack = rememberNavBackStack(ProductList)
                val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>()

                NavDisplay(
                    backStack = backStack,
                    modifier = Modifier.padding(paddingValues),
                    onBack = { backStack.removeLastOrNull() },
                    sceneStrategies = listOf(listDetailStrategy),
                    entryProvider = entryProvider {
                        entry<ProductList>(
                            metadata = ListDetailSceneStrategy.listPane(
                                detailPlaceholder = {
                                    ContentYellow("Choose a product from the list")
                                }
                            )
                        ) {
                            ContentRed("Welcome to Nav3") {
                                Button(onClick = {
                                    backStack.add(ProductDetail("ABC"))
                                }) {
                                    Text("View product")
                                }
                            }
                        }
                        entry<ProductDetail>(
                            metadata = ListDetailSceneStrategy.detailPane()
                        ) { product ->
                            ContentBlue("Product ${product.id} ", Modifier.background(PastelBlue)) {
                                Column(horizontalAlignment = Alignment.CenterHorizontally) {
                                    Button(onClick = {
                                        backStack.add(Profile)
                                    }) {
                                        Text("View profile")
                                    }
                                }
                            }
                        }
                        entry<Profile>(
                            metadata = ListDetailSceneStrategy.extraPane()
                        ) {
                            ContentGreen("Profile")
                        }
                    }
                )
            }
        }
    }
}
MaterialScenesSnippets.kt

Şekil 1. Materyal liste-ayrıntı düzeninde çalışan örnek içerik.