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

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

Bu kalıp, özellikle büyük koleksiyonların öğeleri hakkında ayrıntılı bilgi sağlayan uygulamalar için kullanışlıdır. Örneğin, e-posta listesi ve her e-posta iletisinin ayrıntılı içeriğini içeren bir e-posta istemcisi. Liste-ayrıntı, uygulama tercihlerini kategori listesine bölme ve her kategorinin tercihlerini ayrıntı bölmesinde gösterme gibi daha az kritik yollar için de kullanılabilir.

Liste sayfasının yanında gösterilen bir ayrıntılar bölmesi.
1. şekil. Yeterli ekran boyutu olduğunda ayrıntı bölmesi, liste bölmesiyle birlikte gösterilir.
Bir öğe seçildikten sonra ayrıntı bölmesi tüm ekranı kaplar.
Şekil 2. Ekran boyutu sınırlı olduğunda, ayrıntılar 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ı düzeni uygulamayı kolaylaştıran bir composable'dır. ListDetailPaneScaffold ve yerleşik gezinme ile tahmine dayalı geri gitme animasyonları ekler.

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

  1. Liste bölmesi: Bir öğe koleksiyonunu gösterir.
  2. Ayrıntı bölmesi: Seçilen bir öğenin ayrıntılarını gösterir.
  3. Ek bölme (isteğe bağlı): Gerekli olduğunda 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 gezinirken bölmeler arasında geçiş yapılır.

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 seviyeli yapı taşları
  • adaptive-layout: ListDetailPaneScaffold ve SupportingPaneScaffold gibi uyarlanabilir düzenler
  • adaptive-navigation: Paneller içinde ve arasında gezinmeye yönelik composable'lar ile NavigableListDetailPaneScaffold ve NavigableSupportingPaneScaffold gibi varsayılan olarak gezinmeyi destekleyen uyarlanabilir düzenler

Projenizin compose-material3-adaptive 1.1.0-beta1 veya sonraki bir sürümü içerdiğinden emin olun.

Tahmin edilen geri gitme hareketini etkinleştirme

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

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

Temel kullanım

NavigableListDetailPaneScaffold işaretlemesini aşağıdaki şekilde 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 Parcelable sınıfını kullanın. Kodu sizin için oluşturmak üzere kotlin-parcelize eklentisini kullanın.
  2. ThreePaneScaffoldNavigator ile rememberListDetailPaneScaffoldNavigator oluşturun.

Bu gezinme aracı, liste, ayrıntı ve ek paneller arasında geçiş yapmak için kullanılır. Genel bir tür bildirilerek gezinme aracı, iskelenin durumunu (yani hangi MyItem öğesinin görüntülendiğini) da izler. Bu tür paketlenebilir olduğundan, yapılandırma değişikliklerinin otomatik olarak işlenmesi için durum, gezinme aracı tarafından kaydedilip geri yüklenebilir.

  1. Gezgini NavigableListDetailPaneScaffold composable'ına iletin.

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

  3. Ayrıntı bölmesi uygulamanızı NavigableListDetailPaneScaffold'ya ekleyin.

Gezinme tamamlandığında currentDestination, uygulamanızın gezindiği bölmeyi (bölmede gösterilen içerik de dahil) içerir. contentKey özelliği, orijinal çağrıda belirtilen türle aynıdır. Bu nedenle, göstermeniz gereken tüm verilere erişebilirsiniz.

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

Uygulamanız farklı bir geri gezinme kalıbı gerektiriyorsa 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-posta listesi, diğer bölmede ise ayrıntılı görünüm bulunan bir e-posta uygulaması örneği kullanılmaktadır.

Bu davranış, genel düzen yapısındaki değişikliklere odaklanır. Çok panelli bir kurulumda, ayrıntılar bölmesindeki e-posta içeriğinin değiştirilmesi temel düzen yapısını değiştirmez. 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 atlanarak liste görünümüne dönülür. Bunun nedeni, bu işlemin net bir düzen değişikliğini temsil etmesidir.

Aşağıdaki örnekleri inceleyin:

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

Kullanıcıların her geri gitme işleminde farklı düzen geçişleri algılamasını istediğinizde bu yöntemi kullanın.

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

Bu davranış, görüntülenen içeriğe öncelik verir. 1. Öğeyi ve ardından 2. Öğeyi görüntülerseniz düzenden bağımsız olarak geri düğmesine bastığınızda 1. Öğeye geri dönersiniz.

Aşağıdaki örnekleri inceleyin:

  • Çoklu Bölme: Ayrıntı bölmesinde 1. Öğeyi görüntüleyip listede 2. Öğeyi tıklarsınız. Ayrıntılar bölmesi güncellenir. Geri tuşuna basıldığında ayrıntı bölmesi 1. Öğeye geri yüklenir.
  • Tek bölmeli: Aynı içerik geri döndürme işlemi gerçekleşir.

Kullanıcınız, geri gitme işlemiyle daha önce görüntülenen içeriğe dönmeyi beklediğinde bu özelliği kullanın.

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

Bu davranış, mevcut gezinme hedefi değişene kadar geri yığını açar. Bu durum, tek ve çok panelli düzenler için geçerlidir.

Aşağıdaki örnekleri inceleyin:

Tek veya çok panelli düzende olmanızdan bağımsız olarak, geri tuşuna bastığınızda odak her zaman vurgulanan gezinme öğesinden önceki hedefe taşınır. E-posta uygulamamızda bu, seçilen bölmenin görsel göstergesinin değişeceği anlamına gelir.

Mevcut gezinmeyle ilgili net bir görsel göstergeyi korumanın kullanıcı deneyimi açısından çok önemli olduğu durumlarda bu yöntemi kullanın.

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

Bu seçenek, yalnızca en son hedefi geri yığından 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