Utwórz układ panelu pomocniczego

Układ kanoniczny panelu pomocniczego przyciąga uwagę użytkowników na główną treść aplikacji, a jednocześnie wyświetla odpowiednie treści pomocnicze. Na przykład w głównym panelu treści mogą być widoczne informacje o najnowszym filmie, a w panelu pomocniczym – lista innych filmów o podobnej tematyce, filmów o tym samym reżyserze lub aktorów. Więcej informacji o układzie kanonicznym panelu pomocniczego znajdziesz we wskazówkach dotyczących panelu pomocniczego Material 3.

Wdrażanie panelu pomocniczego

SupportingPaneScaffold składa się z maksymalnie 3 paneli: głównego, panelu pomocy i opcjonalnego panelu dodatkowego. Platforma obsługuje wszystkie obliczenia związane z przydzielaniem przestrzeni okien do 3 paneli. Na dużych ekranach scaffold wyświetla panel główny z panelem pomocniczym z boku. Na małych ekranach rusztownik wyświetla pełny ekran główny lub panel pomocniczy.

Dodaj zależności

SupportingPaneScaffold jest częścią biblioteki układu adaptacyjnego Material 3.

Dodaj te 3 powiązane zależności do pliku build.gradle aplikacji lub modułu:

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'

• adaptacyjne – elementy składowe niskiego poziomu, takie jak HingeInfo i Posture.
• adaptive-layout – układy adaptacyjne, np. SupportingPaneScaffold
• nawigacja adaptacyjna – elementy kompozycyjne umożliwiające nawigację w panelach i między nimi.

Tworzenie nawigatora i rusztowania

W małych oknach w danym momencie wyświetla się tylko 1 panel. Aby przechodzić między nimi, użyj ThreePaneScaffoldNavigator. Utwórz instancję nawigatora za pomocą rememberSupportingPaneScaffoldNavigator. Aby obsługiwać gesty wsteczne, użyj elementu BackHandler, który sprawdza canNavigateBack() i wywołuje navigateBack():

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}
SampleSupportingPaneScaffold.kt

Platforma wymaga elementu PaneScaffoldDirective, który kontroluje podział ekranu i odstępów, oraz elementu ThreePaneScaffoldValue, który podaje bieżący stan paneli (np. rozwinięty czy ukryty). Aby określić działanie domyślne, użyj odpowiednio elementów scaffoldDirective i scaffoldValue nawigatora:

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = { /*...*/ },
    supportingPane = { /*...*/ },
)
SampleSupportingPaneScaffold.kt

Panel główny i panel pomocniczy to obiekty kompozycyjne zawierające Twoją treść. Kliknij AnimatedPane, aby zastosować domyślne animacje paneli podczas nawigacji. Użyj wartości scaffold, aby sprawdzić, czy panel pomocniczy jest ukryty. Jeśli tak, wyświetl przycisk wywołujący navigateTo(ThreePaneScaffoldRole.Secondary), aby wyświetlić panel pomocniczy.

Oto pełna implementacja rusztowania:

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            // Main pane content
            if (navigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Hidden) {
                Button(
                    modifier = Modifier.wrapContentSize(),
                    onClick = {
                        navigator.navigateTo(SupportingPaneScaffoldRole.Supporting)
                    }
                ) {
                    Text("Show supporting pane")
                }
            } else {
                Text("Supporting pane is shown")
            }
        }
    },
    supportingPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            // Supporting pane content
            Text("Supporting pane")
        }
    },
)
SampleSupportingPaneScaffold.kt

Wyodrębnij elementy kompozycyjne panelu

Wyodrębnij poszczególne panele elementu SupportingPaneScaffold do jego własnych elementów kompozycyjnych, aby umożliwić ich wielokrotne używanie i testowanie. Użyj ThreePaneScaffoldScope, aby otworzyć AnimatedPane, jeśli chcesz korzystać z animacji domyślnych:

@Composable
fun ThreePaneScaffoldScope.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")
        }
    }
}

@Composable
fun ThreePaneScaffoldScope.SupportingPane(
    modifier: Modifier = Modifier,
) {
    AnimatedPane(modifier = modifier.safeContentPadding()) {
        // Supporting pane content
        Text("This is the supporting pane")
    }
}
SampleSupportingPaneScaffold.kt

Wyodrębnianie paneli do funkcji kompozycyjnych upraszcza korzystanie z funkcji SupportingPaneScaffold (porównaj te informacje z pełną implementacją rusztowania z poprzedniej sekcji):

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

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