Liste ayrıntısı düzeni oluşturma

Liste-ayrıntı, bir bölmenin öğelerin listesini, diğer bölmenin ise listeden seçilen öğelerin ayrıntılarını gösterdiği çift bölmeli bir düzenden oluşan bir kullanıcı arayüzü kalıbıdır.

Bu model özellikle büyük koleksiyonlardaki öğeler hakkında ayrıntılı bilgi sağlayan uygulamalar için kullanışlıdır. Örneğin, e-posta listesini ve her e-posta mesajının ayrıntılı içeriğini içeren bir e-posta istemcisi. Liste-ayrıntı, uygulama tercihlerini ayrıntı bölmesinde her kategorinin tercihlerinin yer aldığı bir kategori listesine ayırma gibi daha az kritik yollar için de kullanılabilir.

Liste sayfasının yanında gösterilen ayrıntılar bölmesi.
Şekil 1. Yeterli ekran boyutu olduğunda ayrıntılar bölmesi, liste bölmesinin yanında gösterilir.
Bir öğe seçildikten sonra ayrıntı bölmesi ekranın tamamını kaplar.
Şekil 2. Ekran boyutu sınırlı olduğunda, ayrıntı bölmesi (bir öğe seçildiğinden) tüm alanı kaplar.

NavigableListDetailPaneScaffold ile liste-ayrıntı düzenini uygulama

NavigableListDetailPaneScaffold, Jetpack Compose'da liste ayrıntısı düzenini uygulamayı basitleştiren bir kompozisyondur. ListDetailPaneScaffold öğesini sarmalayarak yerleşik gezinme ve tahmine dayalı geri animasyonlar ekler.

Liste ayrıntıları iskeleti en fazla üç bölmeyi destekler:

  1. Liste bölmesi: Bir öğe koleksiyonunu gösterir.
  2. Ayrıntı bölmesi: Seçilen öğenin ayrıntılarını gösterir.
  3. Ek bölme (isteğe bağlı): Gerekirse ek bağlam sağlar.

İskele, pencere boyutuna göre uyarlanır:

  • Büyük pencerelerde liste ve ayrıntı bölmeleri yan yana görünür.
  • Küçük pencerelerde aynı anda yalnızca bir bölme görünür ve kullanıcılar gezindikçe bölme değiştirilir.

Bağımlılıkları bildirme

NavigableListDetailPaneScaffold, Material 3 uyarlanabilir gezinme kitaplığının bir parçasıdır.

Uygulamanızın veya modülünüzün build.gradle dosyasına aşağıdaki üç ilgili bağımlılığı ekleyin:

Kotlin

implementation("androidx.compose.material3.adaptive:adaptive")
implementation("androidx.compose.material3.adaptive:adaptive-layout")
implementation("androidx.compose.material3.adaptive:adaptive-navigation")

Groovy

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'
  • Uyarlanabilir: HingeInfo ve Posture gibi düşük düzey yapı taşları
  • adaptive-layout: ListDetailPaneScaffold ve SupportingPaneScaffold gibi uyarlanabilir düzenler
  • adaptive-navigation: Paneller içinde ve paneller arasında gezinmek için kullanılan bileşenler ve NavigableListDetailPaneScaffold ile NavigableSupportingPaneScaffold gibi varsayılan olarak gezinmeyi destekleyen uyarlanabilir düzenler

Projenizde compose-material3-adaptive 1.1.0-beta1 sürümü veya daha yeni bir sürüm bulunduğundan emin olun.

Tahmini geri gitme hareketini etkinleştirme

Android 15 veya önceki sürümlerde tahmine dayalı geri animasyonlarını etkinleştirmek için tahmine dayalı geri hareketini desteklemeyi etkinleştirmeniz gerekir. Bu özelliği etkinleştirmek için AndroidManifest.xml dosyanızdaki <application> etiketine veya ayrı <activity> etiketlerine android:enableOnBackInvokedCallback="true" ekleyin. Daha fazla bilgi için Tahmini geri hareketini etkinleştirme başlıklı makaleyi inceleyin.

Uygulamanız Android 16 (API düzeyi 36) veya sonraki sürümleri hedeflediğinde tahmini geri düğmesi varsayılan olarak etkinleştirilir.

Temel kullanım

NavigableListDetailPaneScaffold'ü aşağıdaki gibi uygulayın:

  1. Seçilen içeriği temsil eden bir sınıf kullanın. Seçilen liste öğesinin kaydedilmesini ve geri yüklenmesini desteklemek için bir Parcelable sınıfı kullanın. Kodu sizin için oluşturmak üzere kotlin-parcelize eklentisini kullanın.
  2. rememberListDetailPaneScaffoldNavigator ile ThreePaneScaffoldNavigator oluşturun.

Bu gezgin, liste, ayrıntı ve ekstra paneller arasında geçiş yapmak için kullanılır. Gezgin, genel bir tür bildirerek iskelenin durumunu (yani hangi MyItem'nin görüntülendiğini) de izler. Bu tür paketlenebilir olduğundan, yapılandırma değişikliklerini otomatik olarak işlemek için gezgin tarafından durum kaydedilip geri yüklenebilir.

  1. Gezgin öğesini NavigableListDetailPaneScaffold bileşenine iletin.

  2. Liste bölmesi uygulamanızı NavigableListDetailPaneScaffold'e gönderin. Gezinme sırasında varsayılan bölme animasyonları uygulamak için AnimatedPane simgesini kullanın. Ardından, ayrıntılar bölmesine ThreePaneScaffoldNavigator, ListDetailPaneScaffoldRole.Detail gitmek ve iletilen öğeyi görüntülemek için ThreePaneScaffoldNavigator tuşunu kullanın.

  3. Ayrıntı bölmesi uygulamanızı NavigableListDetailPaneScaffold içine ekleyin.

Gezinme tamamlandığında currentDestination, uygulamanızın gittiği bölmeyi (bölmede gösterilen içerik dahil) içerir. contentKey mülkü, orijinal çağrıda belirtilen türle aynıdır. Böylece, görüntülemeniz gereken tüm verilere erişebilirsiniz.

  1. İsteğe bağlı olarak NavigableListDetailPaneScaffold içindeki defaultBackBehavior değerini değiştirin. Varsayılan olarak NavigableListDetailPaneScaffold, defaultBackBehavior için PopUntilScaffoldValueChange kullanır.

Uygulamanız için farklı bir geri gezinme modeli gerekiyorsa başka bir BackNavigationBehavior seçeneği belirterek bu davranışı geçersiz kılabilirsiniz.

BackNavigationBehavior seçeneği

Aşağıdaki bölümde, bir bölmede e-postaların listesinin, diğerinde ise ayrıntılı görünümün bulunduğu bir e-posta uygulaması örneği kullanılmaktadır.

Bu davranış, genel düzen yapısındaki değişikliklere odaklanır. Çok bölmeli bir kurulumda, ayrıntılı bölmede e-posta içeriği değiştirildiğinde temel düzen yapısı değişmez. Bu nedenle, mevcut bağlamda geri dönülecek bir düzen değişikliği olmadığından geri düğmesi uygulamadan veya mevcut gezinme grafiğinden çıkabilir. Tek bölmeli düzende geri tuşuna basıldığında, ayrıntı görünümündeki içerik değişiklikleri atlanır ve net bir düzen değişikliği olduğu için liste görünümüne dönülür.

Aşağıdaki örnekleri inceleyin:

  • Çok bölmeli: Ayrıntı bölmesinde bir e-postayı (1. Öğe) görüntülüyorsunuz. Başka bir e-postayı (2. Öğe) tıkladığınızda ayrıntı bölmesi güncellenir ancak liste ve ayrıntı bölmelerinin görünürlüğü değişmez. Geri tuşuna basıldığında uygulamadan veya mevcut gezinme akışından çıkılabilir.
  • Tek bölmeli: 1. Öğeyi, ardından 2. Öğeyi görüntülersiniz. Geri tuşuna bastığınızda doğrudan e-posta listesi bölmesine dönersiniz.

Kullanıcıların her geri işlemle farklı bir düzen geçişi algılamasını istediğinizde bunu kullanın.

Gezinme değeri değişikliği.
PopUntilContentChange

Bu davranış, görüntülenen içeriğe öncelik verir. 1. Öğe'yi görüntüleyip ardından 2. Öğe'yi görüntülerseniz geri tuşuna bastığınızda düzenden bağımsız olarak 1. Öğe'ye geri dönersiniz.

Aşağıdaki örnekleri inceleyin:

  • Çok bölmeli: Ayrıntı bölmesinde 1. Öğe'yi görüntüleyip listeden 2. Öğe'yi tıklayın. Ayrıntılar bölmesi güncellenir. Geri tuşuna basıldığında ayrıntı bölmesi 1. Öğe'ye geri yüklenir.
  • Tek panel: Aynı içerik geri yüklenir.

Kullanıcınız geri düğmesiyle daha önce görüntülenen içeriğe dönmeyi beklediğinde bunu kullanın.

iki ayrıntı bölmesi arasındaki geçiş
PopUntilCurrentDestinationChange

Bu davranış, mevcut navigasyon hedefi değişene kadar arka yığını gösterir. Bu durum, tek ve çok bölmeli düzenler için eşit şekilde geçerlidir.

Aşağıdaki örnekleri inceleyin:

Tek veya çok bölmeli düzende olmanız fark etmeksizin Geri tuşuna bastığınızda odak her zaman vurgulanan gezinme öğesinden önceki hedefe taşınır. E-posta uygulamamızda bu, seçili bölmenin görsel göstergesinin kayacağı anlamına gelir.

Mevcut gezinme durumunun net bir görsel göstergesi kullanıcı deneyimi açısından önemli olduğunda bunu kullanın.

Ayrıntı ve liste bölmeleri arasında gezinme
PopLatest

Bu seçenek, yalnızca en son hedefi arka yığıntan kaldırır. Ara durumları atlamadan geri gitmek için bu seçeneği kullanın.

Bu adımları uyguladıktan sonra kodunuz aşağıdaki gibi görünmelidir:

val scaffoldNavigator = rememberListDetailPaneScaffoldNavigator<MyItem>()
val scope = rememberCoroutineScope()

NavigableListDetailPaneScaffold(
    navigator = scaffoldNavigator,
    listPane = {
        AnimatedPane {
            MyList(
                onItemClick = { item ->
                    // Navigate to the detail pane with the passed item
                    scope.launch {
                        scaffoldNavigator.navigateTo(
                            ListDetailPaneScaffoldRole.Detail,
                            item
                        )
                    }
                },
            )
        }
    },
    detailPane = {
        AnimatedPane {
            // Show the detail pane content if selected item is available
            scaffoldNavigator.currentDestination?.contentKey?.let {
                MyDetails(it)
            }
        }
    },
)
SampleListDetailPaneScaffold.kt

Önceki
Uyarlanabilir gezinme oluşturma
Sonraki
Destekleyici bölme düzeni oluşturma