Destekleyici bölme düzeni oluşturma

Destekleyici bölme düzeni, kullanıcının uygulamanın ana içeriğine odaklanmasını sağlarken 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ığı eserler listelenebilir.

Daha fazla bilgi için Material 3 destekleyici bölme yönergelerine bakın.

Scaffold ile destekleyici panel 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.
• Destekleyici bölme: Ana bölmeyle ilgili ek bağlam veya araçlar sağlar.
• Ek panel (isteğe bağlı): Gerektiğinde ek içerik için kullanılır.

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

• Büyük pencerelerde ana ve destekleyici bölmeler 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ölmeler arasında geçiş yapılır.

  

  Ş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.

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")

Modern

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 alt düzey yapı taşları

• adaptive-layout: ListDetailPaneScaffold ve SupportingPaneScaffold gibi uyarlanabilir düzenler

• adaptive-navigation: Bölmeler içinde ve arasında gezinmek için composable'lar ve 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 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ı zorunlu kılar. Yeniden oluşturma sırasında, destekleyici bölmenin gösterilip gösterilmeyeceğini belirlemek için ThreePaneScaffoldNavigator.currentDestination özelliğini kontrol edin.

İskeletin tam bir uygulamasını aşağıda görebilirsiniz:

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

Not: NavigableSupportingPaneScaffold, varsayılan olarak defaultBackBehavior için PopUntilScaffoldValueChange kullanır. Uygulamanız farklı bir geri gezinme deseni gerektiriyorsa başka bir BackNavigationBehavior seçeneği belirterek bu davranışı geçersiz kılabilirsiniz.

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

SupportingPaneScaffold öğesinin ayrı bölmelerini kendi composable'larına ayırarak yeniden kullanılabilir ve test edilebilir hale getirin. Varsayılan animasyonları kullanmak istiyorsanız AnimatedPane'e erişmek için ThreePaneScaffoldScope kullanın:

@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

Bölmeleri composable'lara ayırmak, SupportingPaneScaffold kullanımını basitleştirir (aşağıdakini ö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.

Not: Özel geri gezinme mantığına ihtiyacınız varsa ThreePaneScaffoldPredictiveBackHandler yerine doğrudan PredictiveBackHandler kullanın.

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ğıdakine benzer:

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