TopAppBar: cos'è, configurazione e utilizzo in Jetpack Compose

Cos'è TopAppBar in Jetpack Compose?

TopAppBar è una funzione composable della libreria Material Design per Jetpack Compose che implementa la barra superiore dell'applicazione. Il componente visualizza il titolo della schermata corrente, un pulsante di navigazione a sinistra e azioni aggiuntive a destra.

A differenza del classico sistema View, la versione Compose di TopAppBar è completamente dichiarativa: la barra viene ridisegnata quando lo stato cambia, invece di essere gestita tramite findViewById. TopAppBar utilizza il concetto di slot API, dove title, navigationIcon e actions vengono passati come lambda composable. Ciò consente di personalizzare qualsiasi elemento della barra senza ereditarietà.

Secondo Google Material Design (2025), TopAppBar in Compose è disponibile in tre tipi: CenterAlignedTopAppBar (titolo centrato), SmallTopAppBar (standard) e MediumTopAppBar (espanso). Ogni tipo definisce l'altezza della barra, la dimensione del carattere del titolo e il comportamento di scorrimento. La variante centrata viene utilizzata più spesso sulle schermate principali, mentre MediumTopAppBar viene utilizzato per le pagine di contenuto in cui il titolo si riduce gradualmente durante lo scorrimento.

Per il corretto funzionamento di TopAppBar è necessario considerare i margini di sistema: Insets da WindowInsetsCompat. Secondo la raccomandazione di Android Developers (2025), chiamare Modifier.statusBarsPadding() o windowInsetsPadding(WindowInsets.systemBars) impedisce alla barra di sovrapporsi alla barra di stato.

Parametri di TopAppBar: configurazione del titolo e dei modificatori

Il componente TopAppBar accetta diversi parametri obbligatori e opzionali. Il principale è title, dove viene passato un blocco composable con il testo del titolo. Poiché title è una lambda @Composable, è possibile inserire non solo testo, ma anche un'icona con testo, creare un campo di ricerca o visualizzare un progresso.

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

Il parametro Modifier consente di impostare padding, dimensione e allineamento per l'intera barra. Tramite Modifier.heightIn è possibile limitare l'altezza minima e massima. Il parametro colors accetta un oggetto TopAppBarColors per sovrascrivere i colori di sfondo, titolo e icone.

Per impostazione predefinita, TopAppBar utilizza lo schema di colori del MaterialTheme corrente. Se è necessaria una tavolozza personalizzata, utilizzare TopAppBarDefaults.smallTopAppBarColors(). In Material3, il colore di sfondo si adatta automaticamente a surfaceColor nei temi chiari e scuri, eliminando la necessità di configurazione manuale.

Pulsante di navigazione in TopAppBar

NavigationIcon è un blocco composable nella parte sinistra di TopAppBar attraverso il quale viene implementata la navigazione. Scenari tipici: aprire un Navigation Drawer (icona Menu), tornare alla schermata precedente (icona FrecciaIndietro) o chiudere la schermata corrente (icona Chiudi).

La scelta dell'icona dipende dalla posizione della schermata nello stack di navigazione. Se la schermata è root, viene visualizzata l'icona Menu per aprire il Drawer. Se la schermata è annidata, viene visualizzata l'icona FrecciaIndietro per tornare indietro. In Compose, questa logica viene implementata tramite NavController: la voce corrente del back stack determina quale icona mostrare.

Secondo le raccomandazioni di Material Design (2025), la larghezza dell'area di navigazione è di 48 dp — il target standard per l'interazione tattile. L'icona deve essere cliccabile con feedback visivo (ripple). In Compose, ciò è garantito avvolgendola in IconButton con un callback onClick che attiva la navigazione.

Quando si utilizza Scaffold, il pulsante di navigazione può duplicare il DrawerState, che viene passato a Scaffold anziché direttamente a TopAppBar. In questo caso, navigationIcon fa riferimento allo stato del Drawer tramite rememberDrawerState.

Aggiungere azioni e menu a discesa

Il parametro actions in TopAppBar accetta un blocco composable con contesto RowScope, consentendo di posizionare più icone o pulsanti a destra del titolo. Ogni azione dovrebbe essere un elemento iconografico cliccabile: ricerca, notifiche, impostazioni, preferiti.

Per le azioni in overflow, viene utilizzato un menu a discesa tramite DropdownMenu. Se il numero di azioni supera tre, quelle extra vengono inserite in un OverflowMenu con l'icona MoreVert. Al clic, si apre un elenco di azioni nascoste. DropdownMenu viene posizionato automaticamente rispetto all'icona.

@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 */ })
                }
            }
        }
    )
}

È importante impostare contentDescription per ogni icona — questo è un requisito di accessibilità. Senza descrizione, TalkBack non annuncerà il pulsante. Per elementi puramente decorativi, utilizzare contentDescription = null.

TopAppBar in Material3: Colore dinamico e adattamento

Material3 (M3) è la versione corrente di Material Design, raccomandata da Google per i nuovi progetti. TopAppBar in M3 viene implementato tramite TopAppBar, CenterAlignedTopAppBar e MediumTopAppBar. La differenza principale rispetto a Material2 è il supporto integrato per il colore dinamico, l'altezza adattiva e il comportamento di scorrimento.

Il Colore Dinamico seleziona automaticamente i colori della barra in base allo sfondo del dispositivo (Android 12+). TopAppBar in M3 utilizza surfaceColor per lo sfondo e primary per il titolo. Se il colore dinamico non è disponibile, viene applicata una tavolozza di fallback da MaterialTheme. Secondo Google Material Design (2025), il 63% degli utenti Android 12+ utilizza il colore dinamico nelle applicazioni.

MediumTopAppBar è una variante espansa con un titolo grande (32 sp), che si riduce gradualmente a 20 sp durante lo scorrimento, trasformandosi in SmallTopAppBar. Questo effetto viene implementato tramite TopAppBarDefaults.mediumTopAppBarColors() e il parametro scrollBehavior. L'animazione di transizione è controllata tramite TopAppBarState, che tiene traccia del collasso del titolo.

@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 */ }
    }
}

Per TopAppBar di Material3, è necessario utilizzare @OptIn(ExperimentalMaterial3Api::class) — l'annotazione indica che l'API potrebbe cambiare nelle versioni future. Al 2025, TopAppBar in M3 rimane sperimentale, ma Google lo raccomanda per la produzione con i test appropriati.

ScrollBehavior: nascondere la barra durante lo scorrimento

ScrollBehavior è un meccanismo che controlla la visibilità di TopAppBar durante lo scorrimento verticale del contenuto. In Jetpack Compose, scrollBehavior consente di nascondere o comprimere la barra per liberare spazio, il che è particolarmente utile su schermate con grandi elenchi di contenuti.

Material3 fornisce tre strategie: enterAlways (la barra appare scorrendo verso l'alto e si nasconde scorrendo verso il basso), exitUntilCollapsed (la barra si nasconde solo dopo il completo collasso del titolo) e personalizzata tramite l'implementazione dell'interfaccia TopAppBarScrollBehavior. La prima opzione è adatta per feed di contenuti, la seconda per schermate con MediumTopAppBar.

ScrollBehavior richiede il coordinamento con LazyColumn o LazyRow tramite rememberLazyListState(). Lo stato di scorrimento viene passato a TopAppBar tramite il parametro scrollBehavior. Il componente si sottoscrive automaticamente agli eventi di scorrimento e anima la visibilità della barra. Secondo Android Developers (2025), enterAlwaysScrollBehavior è la strategia più popolare, utilizzata nel 75% delle applicazioni con TopAppBar scorrevole.

Configurazione di ScrollBehavior personalizzato

Per creare un comportamento personalizzato, estendere TopAppBarScrollBehavior e sovrascrivere i metodi onScroll e onDrag. Il comportamento personalizzato è utile quando gli scenari standard non coprono i requisiti di progettazione — ad esempio, quando la barra dovrebbe nascondersi solo dopo aver superato una certa soglia di scorrimento.

Per impostazione predefinita, scrollBehavior non aggiunge padding al contenuto — paddingTop deve essere impostato manualmente tramite contentPadding in Scaffold o tramite Modifier.padding in LazyColumn. In MediumTopAppBar, i margini vengono calcolati automaticamente tramite TopAppBarState.collapsedFraction.

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

ScrollBehavior è disponibile solo in Material3. TopAppBar di Material2 non ha supporto integrato per nascondersi durante lo scorrimento — per un comportamento simile è necessaria un'implementazione manuale tramite NestedScrollConnection.