Layout mit unterstützendem Bereich erstellen

Durch das Layout des unterstützenden Bereichs wird der Fokus des Nutzers auf den Hauptinhalt der App gerichtet, während gleichzeitig relevante unterstützende Informationen angezeigt werden. Im Hauptbereich werden beispielsweise Details zu einem Film angezeigt, während im unterstützenden Bereich ähnliche Filme, Filme desselben Regisseurs oder Werke mit denselben Schauspielern aufgeführt werden.

Weitere Informationen finden Sie in den Richtlinien für Material 3-Unterstützungsbereiche.

Unterstützungsbereich mit einem Gerüst implementieren

NavigableSupportingPaneScaffold ist eine Composable, die die Implementierung eines unterstützenden Bereichslayouts in Jetpack Compose vereinfacht. Es umschließt SupportingPaneScaffold und bietet integrierte Navigations- und Vorhersagefunktionen für die Rücktaste.

Ein unterstützendes Bereichsgerüst unterstützt bis zu drei Bereiche:

• Hauptbereich: Hier werden die primären Inhalte angezeigt.
• Unterstützungsbereich: Bietet zusätzlichen Kontext oder Tools, die sich auf den Hauptbereich beziehen.
• Zusätzlicher Bereich (optional): Wird bei Bedarf für zusätzliche Inhalte verwendet.

Das Gerüst passt sich an die Fenstergröße an:

• In großen Fenstern werden die Haupt- und unterstützenden Bereiche nebeneinander angezeigt.

• In kleinen Fenstern ist jeweils nur ein Bereich sichtbar. Die Bereiche werden gewechselt, wenn Nutzer navigieren.

  

Abhängigkeiten hinzufügen

NavigableSupportingPaneScaffold ist Teil der adaptiven Layoutbibliothek für Material 3.

Fügen Sie der Datei build.gradle Ihrer App oder Ihres Moduls die folgenden drei zugehörigen Abhängigkeiten hinzu:

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

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'

• adaptiv: Bausteine auf niedriger Ebene wie HingeInfo und Posture

• adaptive-layout: Adaptive Layouts wie ListDetailPaneScaffold und SupportingPaneScaffold

• adaptive-navigation: Composables für die Navigation innerhalb und zwischen Bereichen sowie adaptive Layouts, die standardmäßig die Navigation unterstützen, z. B. NavigableListDetailPaneScaffold und NavigableSupportingPaneScaffold

Ihr Projekt muss compose-material3-adaptive Version 1.1.0-beta1 oder höher enthalten.

Intelligente „Zurück“-Touch-Geste aktivieren

Wenn Sie Animationen für die intelligente „Zurück“-Touchgeste in Android 15 oder niedriger aktivieren möchten, müssen Sie die Unterstützung für die intelligente „Zurück“-Touchgeste aktivieren. Fügen Sie zum Aktivieren android:enableOnBackInvokedCallback="true" dem Tag <application> oder einzelnen Tags <activity> in Ihrer AndroidManifest.xml-Datei hinzu.

Sobald Ihre App auf Android 16 (API‑Level 36) oder höher ausgerichtet ist, ist die Funktion „Vorhersagende Zurück-Geste“ standardmäßig aktiviert.

Navigator erstellen

In kleinen Fenstern wird immer nur ein Bereich angezeigt. Verwenden Sie daher ThreePaneScaffoldNavigator, um zwischen den Bereichen zu wechseln. Erstellen Sie eine Instanz des Navigators mit rememberSupportingPaneScaffoldNavigator.

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()
SampleSupportingPaneScaffold.kt

Navigator an das Scaffold übergeben

Für das Scaffold ist ein ThreePaneScaffoldNavigator erforderlich, das den Status des Scaffolds darstellt, sowie ein ThreePaneScaffoldValue und ein PaneScaffoldDirective.

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

Das Haupt- und das unterstützende Fenster sind Composables, die Ihre Inhalte enthalten. Verwenden Sie AnimatedPane, um die Standardanimationen für Bereiche während der Navigation anzuwenden. Verwenden Sie den Gerüstwert, um zu prüfen, ob der unterstützende Bereich ausgeblendet ist. Wenn ja, zeigen Sie eine Schaltfläche an, mit der navigateTo(SupportingPaneScaffoldRole.Supporting) aufgerufen wird, um den unterstützenden Bereich anzuzeigen.

Hier sehen Sie eine vollständige Implementierung des Gerüsts:

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

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()) {
            Text("Supporting pane")
        }
    }
)
SampleSupportingPaneScaffold.kt

Composables für den Bereich „Extrahieren“

Extrahieren Sie die einzelnen Bereiche eines SupportingPaneScaffold in eigene Composables, damit sie wiederverwendbar und testbar sind. Verwenden Sie ThreePaneScaffoldScope, um auf AnimatedPane zuzugreifen, wenn Sie die Standardanimationen verwenden möchten:

@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(
    modifier: Modifier = Modifier,
) {
    AnimatedPane(modifier = modifier.safeContentPadding()) {
        // Supporting pane content
        Text("This is the supporting pane")
    }
}
SampleSupportingPaneScaffold.kt

Durch das Extrahieren der Bereiche in Composables wird die Verwendung von SupportingPaneScaffold vereinfacht (vergleichen Sie das Folgende mit der vollständigen Implementierung des Gerüsts im vorherigen Abschnitt):

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() },
)
SampleSupportingPaneScaffold.kt

Wenn Sie mehr Kontrolle über bestimmte Aspekte des Gerüsts benötigen, sollten Sie SupportingPaneScaffold anstelle von NavigableSupportingPaneScaffold verwenden. Dabei werden PaneScaffoldDirective und ThreePaneScaffoldValue oder ThreePaneScaffoldState separat akzeptiert. So können Sie benutzerdefinierte Logik für den Abstand zwischen den Bereichen implementieren und festlegen, wie viele Bereiche gleichzeitig angezeigt werden sollen. Sie können auch die Unterstützung für die Vorhersage von „Zurück“-Gesten aktivieren, indem Sie ThreePaneScaffoldPredictiveBackHandler hinzufügen.

ThreePaneScaffoldPredictiveBackHandler hinzufügen

Hängen Sie den Handler für die Vorhersage der Zurück-Geste an, der eine Scaffold-Navigator-Instanz verwendet, und geben Sie die backBehavior an. Damit wird festgelegt, wie Ziele während der Rückwärtsnavigation aus dem Backstack entfernt werden. Übergeben Sie dann scaffoldDirective und scaffoldState an SupportingPaneScaffold. Verwenden Sie die Überladung, die ein ThreePaneScaffoldState akzeptiert, und übergeben Sie scaffoldNavigator.scaffoldState.

Definieren Sie die Haupt- und untergeordneten Bereiche in SupportingPaneScaffold. Verwenden Sie AnimatedPane für Standardanimationen für Bereiche.

Nachdem Sie diese Schritte ausgeführt haben, sollte Ihr Code in etwa so aussehen:

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() },
)
SampleSupportingPaneScaffold.kt