Destekleyici bölme düzeni oluşturma

Destekleyici bölme düzeni, kullanıcının odak noktasını uygulamanın ana içeriğinde tutarken alakalı destekleyici bilgileri gösterir. Örneğin, ana bölmede bir filmle ilgili ayrıntılar gösterilirken destekleyici bölmede benzer filmler, aynı yönetmenin filmleri veya aynı oyuncuların yer aldığı yapımlar listelenebilir.

Daha fazla bilgi için Material 3 destek bölmesi yönergeleri başlıklı makaleyi inceleyin.

İskele ile destekleyici bir bölme uygulama

NavigableSupportingPaneScaffold, Jetpack Compose'da destekleyici bölme düzeninin uygulanmasını kolaylaştıran bir composable'dır. SupportingPaneScaffold öğesini sarmalar ve yerleşik gezinme ile tahmin edilen geri gitme hareketi ekler.

Destek bölmesi iskeleti en fazla üç bölmeyi destekler:

  • Ana bölme: Birincil içeriği gösterir.
  • Destek bölmesi: Ana bölmeyle ilgili ek bağlam veya araçlar sağlar.
  • Ek bölme (isteğe bağlı): Gerekli olduğunda ek içerik için kullanılır.

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

  • Büyük pencerelerde ana ve destekleyici paneller yan yana görünür.

  • Küçük pencerelerde, kullanıcılar gezinirken yalnızca bir bölme görünür.

    Ana içerik, destekleyici içerikle birlikte ekranın büyük bir bölümünü kaplıyor.
    Şekil 1. Destek bölmesi düzeni.

Bağımlılık ekleme

NavigableSupportingPaneScaffold, Material 3 uyarlanabilir düzen kitaplığının bir parçasıdır.

Aşağıdaki üç ilgili bağımlılığı uygulamanızın veya modülünüzün build.gradle dosyasına 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'

  • adaptive: 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 varsayılan olarak gezinmeyi destekleyen uyarlanabilir düzenler (ör. NavigableListDetailPaneScaffold ve NavigableSupportingPaneScaffold)

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 tahmin edilen geri gitme animasyonlarını etkinleştirmek için tahmin edilen geri gitme hareketini desteklemeyi kabul etmeniz gerekir. Bu özelliği etkinleştirmek için AndroidManifest.xml dosyanızdaki <application> etiketine veya <activity> etiketlerine android:enableOnBackInvokedCallback="true" ekleyin.

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

Gezgin oluşturma

Küçük pencerelerde aynı anda yalnızca bir bölme gösterilir. Bu nedenle, bölmeler arasında geçiş yapmak için ThreePaneScaffoldNavigator tuşunu kullanın. rememberSupportingPaneScaffoldNavigator ile gezginin bir örneğini oluşturun.

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

SampleSupportingPaneScaffold.kt

Gezgini iskeleye iletme

İskele için iskelenin durumunu (ThreePaneScaffoldValue ve PaneScaffoldDirective) temsil eden bir arayüz olan ThreePaneScaffoldNavigator gerekir.

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = { /*...*/ },
    supportingPane = { /*...*/ },
)
SampleSupportingPaneScaffold.kt

Ana bölme ve destekleyici bölme, içeriğinizi içeren composable'lardır. Gezinme sırasında varsayılan bölme animasyonlarını uygulamak için AnimatedPane kodunu kullanın. Destekleyici bölmenin gizli olup olmadığını kontrol etmek için iskele değerini kullanın. Gizliyse destekleyici bölmeyi göstermek için navigateTo(SupportingPaneScaffoldRole.Supporting) işlevini çağıran bir düğme gösterin.

Büyük ekranlarda, destekleyici bölmeyi kapatmak için ThreePaneScaffoldNavigator.navigateBack() yöntemini kullanın ve BackNavigationBehavior.PopUntilScaffoldValueChange sabitini iletin. Bu yöntemin çağrılması, NavigableSupportingPaneScaffold öğesinin yeniden oluşturulmasını zorlar. Yeniden oluşturma sırasında, destekleyici bölmenin gösterilip gösterilmeyeceğini belirlemek için ThreePaneScaffoldNavigator.currentDestination özelliğini kontrol edin.

İskele için eksiksiz bir uygulama aşağıda verilmiştir:

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()
val backNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = {
        AnimatedPane(
            modifier = Modifier
                .safeContentPadding()
                .background(Color.Red)
        ) {
            if (scaffoldNavigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Hidden) {
                Button(
                    modifier = Modifier
                        .wrapContentSize(),
                    onClick = {
                        scope.launch {
                            scaffoldNavigator.navigateTo(SupportingPaneScaffoldRole.Supporting)
                        }
                    }
                ) {
                    Text("Show supporting pane")
                }
            } else {
                Text("Supporting pane is shown")
            }
        }
    },
    supportingPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            Column {
                // Allow users to dismiss the supporting pane. Use back navigation to
                // hide an expanded supporting pane.
                if (scaffoldNavigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Expanded) {
                    // Material design principles promote the usage of a right-aligned
                    // close (X) button.
                    IconButton(
                        modifier =  Modifier.align(Alignment.End).padding(16.dp),
                        onClick = {
                            scope.launch {
                                scaffoldNavigator.navigateBack(backNavigationBehavior)
                            }
                        }
                    ) {
                        Icon(Icons.Default.Close, contentDescription = "Close")
                    }
                }
                Text("Supporting pane")
            }

        }
    }
)
SampleSupportingPaneScaffold.kt

Bölme composable'larını ayıklama

Yeniden kullanılabilir ve test edilebilir hale getirmek için SupportingPaneScaffold öğesinin her bir bölmesini kendi composable'ına ayırın. Varsayılan animasyonları istiyorsanız ThreePaneScaffoldScope kullanarak AnimatedPane'e erişin:

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ThreePaneScaffoldPaneScope.MainPane(
    shouldShowSupportingPaneButton: Boolean,
    onNavigateToSupportingPane: () -> Unit,
    modifier: Modifier = Modifier,
) {
    AnimatedPane(
        modifier = modifier.safeContentPadding()
    ) {
        // Main pane content
        if (shouldShowSupportingPaneButton) {
            Button(onClick = onNavigateToSupportingPane) {
                Text("Show supporting pane")
            }
        } else {
            Text("Supporting pane is shown")
        }
    }
}

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ThreePaneScaffoldPaneScope.SupportingPane(
    scaffoldNavigator: ThreePaneScaffoldNavigator<Any>,
    modifier: Modifier = Modifier,
    backNavigationBehavior: BackNavigationBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange,
) {
    val scope = rememberCoroutineScope()
    AnimatedPane(modifier = Modifier.safeContentPadding()) {
        Column {
            // Allow users to dismiss the supporting pane. Use back navigation to
            // hide an expanded supporting pane.
            if (scaffoldNavigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Expanded) {
                // Material design principles promote the usage of a right-aligned
                // close (X) button.
                IconButton(
                    modifier =  modifier.align(Alignment.End).padding(16.dp),
                    onClick = {
                        scope.launch {
                            scaffoldNavigator.navigateBack(backNavigationBehavior)
                        }
                    }
                ) {
                    Icon(Icons.Default.Close, contentDescription = "Close")
                }
            }
            Text("Supporting pane")
        }

    }
}
SampleSupportingPaneScaffold.kt

Panelleri composable'lara ayırmak, SupportingPaneScaffold kullanımını kolaylaştırır (aşağıdakileri, önceki bölümdeki iskelenin tam uygulamasıyla karşılaştırın):

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = scaffoldNavigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = {
                scope.launch {
                    scaffoldNavigator.navigateTo(ThreePaneScaffoldRole.Secondary)
                }
            }
        )
    },
    supportingPane = { SupportingPane(scaffoldNavigator = scaffoldNavigator) },
)
SampleSupportingPaneScaffold.kt

İskeleyle ilgili belirli yönler üzerinde daha fazla kontrole ihtiyacınız varsa NavigableSupportingPaneScaffold yerine SupportingPaneScaffold kullanmayı deneyin. Bu, PaneScaffoldDirective ve ThreePaneScaffoldValue veya ThreePaneScaffoldState öğelerini ayrı ayrı kabul eder. Bu esneklik, bölme aralığı için özel mantık uygulamanıza ve aynı anda kaç bölmenin gösterilmesi gerektiğini belirlemenize olanak tanır. ThreePaneScaffoldPredictiveBackHandler ekleyerek de tahmin edilen geri gitme özelliğini etkinleştirebilirsiniz.

ThreePaneScaffoldPredictiveBackHandler ekleme

Bir iskele gezgini örneği alan ve backBehavior değerini belirten tahmin edilen geri gitme işleyiciyi ekleyin. Bu, geri gezinme sırasında hedeflerin arka yığından nasıl çıkarılacağını belirler. Ardından scaffoldDirective ve scaffoldState'i SupportingPaneScaffold'a geçirin. ThreePaneScaffoldState kabul eden aşırı yüklemeyi kullanın ve scaffoldNavigator.scaffoldState değerini iletin.

SupportingPaneScaffold içinde ana ve destekleyici bölmeleri tanımlayın. Varsayılan bölme animasyonları için AnimatedPane kodunu kullanın.

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

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

ThreePaneScaffoldPredictiveBackHandler(
    navigator = scaffoldNavigator,
    backBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
)

SupportingPaneScaffold(
    directive = scaffoldNavigator.scaffoldDirective,
    scaffoldState = scaffoldNavigator.scaffoldState,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = scaffoldNavigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = {
                scope.launch {
                    scaffoldNavigator.navigateTo(ThreePaneScaffoldRole.Secondary)
                }
            }
        )
    },
    supportingPane = { SupportingPane(scaffoldNavigator = scaffoldNavigator) },
)
SampleSupportingPaneScaffold.kt

Önceki
Liste ayrıntısı düzeni oluşturma
Sonraki
Uyarlamalı yapılması ve yapılmaması gerekenler