TopAppBar : ce que c'est, configuration et utilisation dans Jetpack Compose

Qu'est-ce que TopAppBar dans Jetpack Compose ?

TopAppBar est une fonction composable de la bibliothèque Material Design pour Jetpack Compose qui implémente la barre supérieure de l'application. Le composant affiche le titre de l'écran actuel, un bouton de navigation à gauche et des actions supplémentaires à droite.

Contrairement au système View classique, la version Compose de TopAppBar est entièrement déclarative : la barre est redessinée lorsque l'état change, plutôt que d'être gérée via findViewById. TopAppBar utilise le concept de slot API, où title, navigationIcon et actions sont passés comme lambdas composables. Cela permet de personnaliser n'importe quel élément de la barre sans héritage.

Selon Google Material Design (2025), TopAppBar dans Compose se décline en trois types : CenterAlignedTopAppBar (titre centré), SmallTopAppBar (standard) et MediumTopAppBar (étendu). Chaque type définit la hauteur de la barre, la taille de police du titre et le comportement de défilement. La variante centrée est plus utilisée sur les écrans principaux, tandis que MediumTopAppBar est utilisé pour les pages de contenu où le titre se réduit progressivement lors du défilement.

Pour le bon fonctionnement de TopAppBar, il est nécessaire de prendre en compte les marges système : Insets de WindowInsetsCompat. Selon la recommandation d'Android Developers (2025), l'appel à Modifier.statusBarsPadding() ou windowInsetsPadding(WindowInsets.systemBars) empêche la barre de chevaucher la barre d'état.

Paramètres de TopAppBar : configuration du titre et des modificateurs

Le composant TopAppBar accepte plusieurs paramètres obligatoires et facultatifs. Le principal est title, où un bloc composable avec le texte du titre est passé. Comme title est une lambda @Composable, vous pouvez insérer non seulement du texte, mais aussi une icône avec du texte, créer un champ de recherche ou afficher une progression.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AppTopBar() {
    TopAppBar(
        title = { Text("Main") },
        navigationIcon = {
            IconButton(onClick = { /* open drawer */ }) {
                Icon(
                    Icons.Filled.Menu,
                    contentDescription = "Menu"
                )
            }
        },
        actions = {
            IconButton(onClick = { /* search */ }) {
                Icon(Icons.Filled.Search, contentDescription = "Search")
            }
        }
    )
}

Le paramètre Modifier permet de définir le remplissage, la taille et l'alignement de toute la barre. Via Modifier.heightIn, vous pouvez limiter la hauteur minimale et maximale. Le paramètre colors accepte un objet TopAppBarColors pour remplacer les couleurs d'arrière-plan, de titre et d'icônes.

Par défaut, TopAppBar utilise le schéma de couleurs du MaterialTheme actuel. Si une palette personnalisée est nécessaire, utilisez TopAppBarDefaults.smallTopAppBarColors(). Dans Material3, la couleur d'arrière-plan s'adapte automatiquement à surfaceColor dans les thèmes clair et sombre, éliminant le besoin de configuration manuelle.

Bouton de navigation dans TopAppBar

NavigationIcon est un bloc composable dans la partie gauche de TopAppBar à travers lequel la navigation est implémentée. Scénarios typiques : ouvrir un Navigation Drawer (icône Menu), revenir à l'écran précédent (icône FlècheRetour) ou fermer l'écran actuel (icône Fermer).

Le choix de l'icône dépend de la position de l'écran dans la pile de navigation. Si l'écran est racine, l'icône Menu est affichée pour ouvrir le Drawer. Si l'écran est imbriqué, l'icône FlècheRetour est affichée pour revenir. Dans Compose, cette logique est implémentée via NavController : l'entrée actuelle de la pile arrière détermine quelle icône afficher.

Selon les recommandations de Material Design (2025), la largeur de la zone de navigation est de 48 dp — la cible standard pour l'interaction tactile. L'icône doit être cliquable avec un retour visuel (ripple). Dans Compose, cela est assuré en l'enveloppant dans IconButton avec un callback onClick qui déclenche la navigation.

Lors de l'utilisation de Scaffold, le bouton de navigation peut dupliquer le DrawerState, qui est passé à Scaffold plutôt que directement à TopAppBar. Dans ce cas, navigationIcon fait référence à l'état du Drawer via rememberDrawerState.

Ajouter des actions et un menu déroulant

Le paramètre actions dans TopAppBar accepte un bloc composable avec le contexte RowScope, permettant de placer plusieurs icônes ou boutons à droite du titre. Chaque action doit être un élément iconographique cliquable : recherche, notifications, paramètres, favoris.

Pour les actions en overflow, un menu déroulant est utilisé via DropdownMenu. Si le nombre d'actions dépasse trois, les actions supplémentaires sont placées dans un OverflowMenu avec l'icône MoreVert. Au clic, une liste d'actions cachées s'ouvre. DropdownMenu est automatiquement positionné par rapport à l'icône.

@Composable
fun TopBarWithOverflow() {
    var menuExpanded by remember { mutableStateOf(false) }
    TopAppBar(
        title = { Text("Profile") },
        actions = {
            IconButton(onClick = { /* share */ }) {
                Icon(Icons.Filled.Share, contentDescription = "Share")
            }
            Box {
                IconButton(onClick = { menuExpanded = true }) {
                    Icon(Icons.Filled.MoreVert, contentDescription = "More")
                }
                DropdownMenu(
                    expanded = menuExpanded,
                    onDismissRequest = { menuExpanded = false }
                ) {
                    DropdownMenuItem(text = { Text("Settings") }, onClick = { /* navigate */ })
                    DropdownMenuItem(text = { Text("About") }, onClick = { /* navigate */ })
                }
            }
        }
    )
}

Il est important de définir contentDescription pour chaque icône — c'est une exigence d'accessibilité. Sans description, TalkBack n'annoncera pas le bouton. Pour les éléments purement décoratifs, utilisez contentDescription = null.

TopAppBar dans Material3 : Couleur dynamique et adaptation

Material3 (M3) est la version actuelle de Material Design, recommandée par Google pour les nouveaux projets. TopAppBar dans M3 est implémenté via TopAppBar, CenterAlignedTopAppBar et MediumTopAppBar. La différence clé avec Material2 est la prise en charge intégrée de la couleur dynamique, de la hauteur adaptative et du comportement de défilement.

La Couleur Dynamique sélectionne automatiquement les couleurs de la barre en fonction du fond d'écran de l'appareil (Android 12+). TopAppBar dans M3 utilise surfaceColor pour l'arrière-plan et primary pour le titre. Si la couleur dynamique n'est pas disponible, une palette de secours de MaterialTheme est appliquée. Selon Google Material Design (2025), 63% des utilisateurs d'Android 12+ utilisent la couleur dynamique dans les applications.

MediumTopAppBar est une variante étendue avec un grand titre (32 sp), qui se réduit progressivement à 20 sp lors du défilement, se transformant en SmallTopAppBar. Cet effet est implémenté via TopAppBarDefaults.mediumTopAppBarColors() et le paramètre scrollBehavior. L'animation de transition est contrôlée via TopAppBarState, qui suit l'effondrement du titre.

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MediumTopBarExample() {
    val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
    Scaffold(
        topBar = {
            MediumTopAppBar(
                title = { Text("Library") },
                navigationIcon = {
                    IconButton(onClick = { }) {
                        Icon(Icons.Filled.Menu, contentDescription = "Menu")
                    }
                },
                scrollBehavior = scrollBehavior
            )
        }
    ) { padding ->
        LazyColumn(contentPadding = padding) { /* content */ }
    }
}

Pour TopAppBar de Material3, vous devez utiliser @OptIn(ExperimentalMaterial3Api::class) — l'annotation indique que l'API peut changer dans les versions futures. En 2025, TopAppBar dans M3 reste expérimental, mais Google le recommande pour la production avec les tests appropriés.

ScrollBehavior : masquer la barre lors du défilement

ScrollBehavior est un mécanisme qui contrôle la visibilité de TopAppBar lors du défilement vertical du contenu. Dans Jetpack Compose, scrollBehavior permet de masquer ou réduire la barre pour libérer de l'espace, ce qui est particulièrement utile sur les écrans avec de grandes listes de contenu.

Material3 propose trois stratégies : enterAlways (la barre apparaît en défilant vers le haut et se masque en défilant vers le bas), exitUntilCollapsed (la barre ne se masque qu'après l'effondrement complet du titre) et personnalisée via l'implémentation de l'interface TopAppBarScrollBehavior. La première option convient aux flux de contenu, la seconde aux écrans avec MediumTopAppBar.

ScrollBehavior nécessite une coordination avec LazyColumn ou LazyRow via rememberLazyListState(). L'état de défilement est passé à TopAppBar via le paramètre scrollBehavior. Le composant s'abonne automatiquement aux événements de défilement et anime la visibilité de la barre. Selon Android Developers (2025), enterAlwaysScrollBehavior est la stratégie la plus populaire, utilisée dans 75% des applications avec TopAppBar défilable.

Configuration d'un ScrollBehavior personnalisé

Pour créer un comportement personnalisé, étendez TopAppBarScrollBehavior et remplacez les méthodes onScroll et onDrag. Le comportement personnalisé est utile lorsque les scénarios standard ne couvrent pas les exigences de conception — par exemple, lorsque la barre doit se masquer seulement après avoir dépassé un certain seuil de défilement.

Par défaut, scrollBehavior n'ajoute pas de remplissage au contenu — paddingTop doit être défini manuellement via contentPadding dans Scaffold ou via Modifier.padding dans LazyColumn. Dans MediumTopAppBar, les marges sont calculées automatiquement via TopAppBarState.collapsedFraction.

val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
Scaffold(
    topBar = {
        MediumTopAppBar(
            title = { Text("Content") },
            scrollBehavior = scrollBehavior
        )
    }
) { padding ->
    LazyColumn(contentPadding = padding) { /* items */ }
}

ScrollBehavior est disponible uniquement dans Material3. TopAppBar de Material2 n'a pas de prise en charge intégrée pour le masquage au défilement — pour un comportement similaire, une implémentation manuelle via NestedScrollConnection est nécessaire.