Créer une mise en page de volet secondaire

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

La mise en page du volet secondaire permet de maintenir l'attention de l'utilisateur sur le contenu principal de l'application tout en affichant des informations complémentaires pertinentes. Par exemple, le volet principal peut afficher des informations sur un film, tandis que le volet secondaire liste des films similaires, des films du même réalisateur ou des œuvres mettant en vedette les mêmes acteurs.

Pour en savoir plus, consultez les Consignes concernant le volet secondaire Material 3.

Implémenter un volet secondaire avec NavigableSupportingPaneScaffold

NavigableSupportingPaneScaffold est un composable qui simplifie l'implémentation d'une mise en page de volet secondaire dans Jetpack Compose. Il encapsule SupportingPaneScaffold et ajoute la navigation intégrée et la gestion de la prévisualisation du Retour.

Un échafaudage de volet secondaire peut contenir jusqu'à trois volets:

• Volet principal: affiche le contenu principal.
• Volet secondaire: fournit du contexte ou des outils supplémentaires liés au volet principal.
• Volet supplémentaire (facultatif): utilisé pour le contenu supplémentaire, le cas échéant.

L'échafaudage s'adapte en fonction de la taille de la fenêtre:

• Dans les grandes fenêtres, les volets principal et secondaire s'affichent côte à côte.

• Dans les petites fenêtres, un seul volet est visible à la fois, et change à mesure que les utilisateurs naviguent.

  

Ajouter des dépendances

NavigableSupportingPaneScaffold fait partie de la bibliothèque de mise en page adaptative Material 3.

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

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'

• adaptative: éléments de base de bas niveau tels que HingeInfo et Posture
• adaptive-layout: mises en page adaptatives telles que ListDetailPaneScaffold et SupportingPaneScaffold
• adaptive-navigation: composables permettant de naviguer dans et entre les volets, ainsi que des mises en page adaptatives compatibles avec la navigation par défaut, telles que NavigableListDetailPaneScaffold et NavigableSupportingPaneScaffold

Assurez-vous que votre projet inclut la version compose-material3-adaptive 1.1.0-beta1 ou ultérieure.

Activer la prévisualisation du geste Retour

Pour activer les animations de prévisualisation du Retour sous Android 15 ou version antérieure, vous devez activer la prise en charge du geste Retour prévisualisé. Pour l'activer, ajoutez android:enableOnBackInvokedCallback="true" à la balise <application> ou android:enableOnBackInvokedCallback="true" à la balise <application> ou aux balises <activity> individuelles dans votre fichier AndroidManifest.xml.

Une fois que votre application cible Android 16 (niveau d'API 36) ou une version ultérieure, la prévisualisation du Retour est activée par défaut.

Créer un navigateur

Dans les petites fenêtres, un seul volet s'affiche à la fois. Utilisez donc un ThreePaneScaffoldNavigator pour passer d'un volet à un autre. Créez une instance du navigateur avec rememberSupportingPaneScaffoldNavigator.

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

Transmettre le navigateur à l'échafaudage

L'échafaudage nécessite un ThreePaneScaffoldNavigator, qui est une interface représentant l'état de l'échafaudage, le ThreePaneScaffoldValue et un PaneScaffoldDirective.

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

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

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

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 de volets d'extraction

Extrayez les volets individuels d'un SupportingPaneScaffold dans leurs propres composables pour les rendre réutilisables et testables. Utilisez ThreePaneScaffoldScope pour accéder à AnimatedPane si vous souhaitez utiliser les animations par défaut:

@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

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

Si vous avez besoin de plus de contrôle sur des aspects spécifiques de l'échafaudage, envisagez d'utiliser SupportingPaneScaffold au lieu de NavigableSupportingPaneScaffold. Cette méthode accepte PaneScaffoldDirective et ThreePaneScaffoldValue ou ThreePaneScaffoldState séparément. Cette flexibilité vous permet d'implémenter une logique personnalisée pour l'espacement des volets et de déterminer le nombre de volets à afficher simultanément. Vous pouvez également activer la prévisualisation du Retour en ajoutant ThreePaneScaffoldPredictiveBackHandler.

Ajouter ThreePaneScaffoldPredictiveBackHandler

Associez le gestionnaire de prévisualisation du Retour qui reçoit une instance de navigateur d'échafaudage et spécifiez le backBehavior. Ce paramètre détermine comment les destinations sont supprimées de la pile "Retour" lors de la navigation "Retour". Transmettez ensuite scaffoldDirective et scaffoldState à SupportingPaneScaffold. Utilisez la surcharge qui accepte un ThreePaneScaffoldState, en transmettant scaffoldNavigator.scaffoldState.

Définissez les volets principaux et secondaires dans SupportingPaneScaffold. Utilisez AnimatedPane pour les animations de volet par défaut.

Une fois ces étapes effectuées, votre code doit se présenter comme suit:

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