Créer une mise en page de volet secondaire

La mise en page canonique du volet secondaire attire l'attention de l'utilisateur sur la page principale du contenu tout en affichant des contenus d'accompagnement pertinents. Par exemple, le principal le volet de contenu peut afficher des informations sur un film récent, tandis que les volet affiche une liste de films ayant un thème ou le même thème un réalisateur ou des acteurs. Pour en savoir plus sur le volet secondaire la mise en page standard, consultez la Consignes concernant les volets secondaires Material 3

Implémenter un volet secondaire

SupportingPaneScaffold se compose de trois volets maximum : un volet principal, un volet secondaire et un volet supplémentaire facultatif. L'échafaudage gère tous les calculs d'allocation de l'espace de fenêtre aux trois volets. Activé grands écrans, l'échafaudage affiche le volet principal avec le volet secondaire sur sur le côté. Sur les petits écrans, l'échafaudage affiche la partie principale ou volet en plein écran.

Le contenu principal occupe la majeure partie de l'écran, avec des contenus complémentaires à côté.
Figure 1 : Mise en page du volet secondaire.

Ajouter des dépendances

SupportingPaneScaffold fait partie de Bibliothèque de mises en page adaptatives Material 3.

Ajoutez les trois dépendances connexes suivantes au fichier build.gradle de votre application ou module:

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'
  • adaptatif : éléments de base de bas niveau tels que HingeInfo et Posture
  • adaptive-layout : mises en page adaptatives, telles que SupportingPaneScaffold
  • adaptive-navigation : composables permettant de naviguer dans et entre les volets

Créer un navigateur et un échafaudage

Dans les petites fenêtres, un seul volet s'affiche à la fois. Utilisez donc une ThreePaneScaffoldNavigator pour passer d'un élément à l'autre volets. Créer une instance du navigateur avec rememberSupportingPaneScaffoldNavigator Pour gérer les gestes Retour, utilisez un BackHandler qui vérifie canNavigateBack() et appelle navigateBack() :

val navigator = rememberSupportingPaneScaffoldNavigator()

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

L'échafaudage nécessite un élément PaneScaffoldDirective, qui contrôle comment diviser l'écran et l'espacement à utiliser, et un ThreePaneScaffoldValue, qui fournit la valeur actuelle l'état des volets (par exemple, s'ils sont développés ou masqués). Par défaut, utilisez les paramètres scaffoldDirective du navigateur et scaffoldValue respectivement:

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

Le volet principal et le volet secondaire sont des composables contenant votre contenu. Utilisez AnimatedPane pour appliquer les animations de volet par défaut pendant la navigation. Utilisez la valeur d'échafaudage pour vérifier si le volet secondaire masqué ; Si c'est le cas, affichez un bouton qui appelle navigateTo(ThreePaneScaffoldRole.Secondary) pour afficher volet secondaire.

Voici une implémentation complète de l'échafaudage:

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

Extraire les composables de volet

Extraire les volets individuels d'un élément SupportingPaneScaffold dans leur propre volet composables afin de les rendre réutilisables et testables. Utilisez ThreePaneScaffoldScope pour accéder à AnimatedPane si vous voulez les animations par défaut:

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

L'extraction des volets en composables simplifie l'utilisation de SupportingPaneScaffold (comparez ce qui suit à l'implémentation complète de l'échafaudage dans la section précédente) :

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