Creare una navigazione adattiva

La maggior parte delle app ha alcune destinazioni di primo livello accessibili tramite la UI di navigazione principale dell'app. Nelle finestre compatte, ad esempio su uno schermo standard di uno smartphone, le destinazioni vengono in genere visualizzate in una barra di navigazione nella parte inferiore della finestra. In una finestra espansa, ad esempio un'app a schermo intero su un tablet, una barra di navigazione accanto all'app è in genere una scelta migliore, poiché i controlli di navigazione sono più facili da raggiungere tenendo i lati sinistro e destro del dispositivo.

NavigationSuiteScaffold semplifica il passaggio da una UI di navigazione all'altra visualizzando il composable della UI di navigazione appropriato in base a WindowSizeClass. Ciò include la modifica dinamica della UI durante le modifiche delle dimensioni della finestra in fase di runtime. Il comportamento predefinito consiste nel mostrare uno dei seguenti componenti della UI:

  • Barra di navigazione se la larghezza o l'altezza è compatta o se il dispositivo è in posizione orizzontale
  • Barra di spostamento per tutto il resto
Figura 1. NavigationSuiteScaffold mostra una barra di navigazione nelle finestre compatte.
Figura 2. NavigationSuiteScaffold mostra una barra di navigazione nelle finestre espanse.

Aggiungi dipendenze

NavigationSuiteScaffold fa parte della libreria della suite di navigazione adattiva Material3. Aggiungi una dipendenza per la libreria nel file build.gradle della tua app o del tuo modulo:

Kotlin

implementation("androidx.compose.material3:material3-adaptive-navigation-suite")

Groovy

implementation 'androidx.compose.material3:material3-adaptive-navigation-suite'

Crea uno scaffold

Le due parti principali di NavigationSuiteScaffold sono gli elementi della suite di navigazione e i contenuti per la destinazione selezionata. Puoi definire direttamente gli elementi della suite di navigazione in un composable, ma è comune che questi siano definiti altrove, ad esempio in un'enumerazione:

enum class AppDestinations(
    @StringRes val label: Int,
    val icon: ImageVector,
    @StringRes val contentDescription: Int
) {
    HOME(R.string.home, Icons.Default.Home, R.string.home),
    FAVORITES(R.string.favorites, Icons.Default.Favorite, R.string.favorites),
    SHOPPING(R.string.shopping, Icons.Default.ShoppingCart, R.string.shopping),
    PROFILE(R.string.profile, Icons.Default.AccountBox, R.string.profile),
}
SampleNavigationSuiteScaffold.kt

Per utilizzare NavigationSuiteScaffold, devi monitorare la destinazione corrente, cosa che puoi fare utilizzando rememberSaveable:

var currentDestination by rememberSaveable { mutableStateOf(AppDestinations.HOME) }
SampleNavigationSuiteScaffold.kt

Nell'esempio seguente, il parametro navigationSuiteItems (tipo NavigationSuiteScope) utilizza la relativa funzione item per definire la UI di navigazione per una singola destinazione. La UI della destinazione viene utilizzata in barre di navigazione, barre di spostamento e riquadri a scomparsa. Per creare elementi di navigazione, esegui un loop su AppDestinations (definito nello snippet precedente):

NavigationSuiteScaffold(
    navigationSuiteItems = {
        AppDestinations.entries.forEach {
            item(
                icon = {
                    Icon(
                        it.icon,
                        contentDescription = stringResource(it.contentDescription)
                    )
                },
                label = { Text(stringResource(it.label)) },
                selected = it == currentDestination,
                onClick = { currentDestination = it }
            )
        }
    }
) {
    // TODO: Destination content.
}
SampleNavigationSuiteScaffold.kt

All'interno della lambda dei contenuti della destinazione, utilizza il valore currentDestination per decidere quale UI visualizzare. Se utilizzi una libreria di navigazione nella tua app, usala qui per visualizzare la destinazione appropriata. Un'istruzione when può essere sufficiente:

NavigationSuiteScaffold(
    navigationSuiteItems = { /*...*/ }
) {
    // Destination content.
    when (currentDestination) {
        AppDestinations.HOME -> HomeDestination()
        AppDestinations.FAVORITES -> FavoritesDestination()
        AppDestinations.SHOPPING -> ShoppingDestination()
        AppDestinations.PROFILE -> ProfileDestination()
    }
}
SampleNavigationSuiteScaffold.kt

Cambia colori

NavigationSuiteScaffold crea una Surface sull'intera area occupata dallo scaffold, in genere l'intera finestra. Inoltre, lo scaffold disegna la UI di navigazione specifica, ad esempio una NavigationBar. Sia la superficie sia la UI di navigazione utilizzano i valori specificati nel tema dell'app, ma puoi sostituire i valori del tema.

Il parametro containerColor specifica il colore della superficie. Il valore predefinito è il colore di sfondo della combinazione di colori. Il parametro contentColor specifica il colore dei contenuti su quella superficie. Il valore predefinito è il colore "on" di qualsiasi valore specificato per containerColor. Ad esempio, se containerColor utilizza il colore background, contentColor utilizza il colore onBackground. Per maggiori dettagli sul funzionamento del sistema di colori, consulta la sezione Tematizzazione di Material Design 3 in Compose. Quando sostituisci questi valori, utilizza i valori definiti nel tema in modo che l'app supporti le modalità di visualizzazione scura e chiara:

NavigationSuiteScaffold(
    navigationSuiteItems = { /* ... */ },
    containerColor = MaterialTheme.colorScheme.primary,
    contentColor = MaterialTheme.colorScheme.onPrimary,
) {
    // Content...
}
SampleNavigationSuiteScaffold.kt

La UI di navigazione viene disegnata davanti alla superficie NavigationSuiteScaffold. I valori predefiniti per i colori della UI sono forniti da NavigationSuiteDefaults.colors(), ma puoi sostituire anche questi valori. Ad esempio, se vuoi che lo sfondo della barra di navigazione sia trasparente, ma che gli altri valori siano quelli predefiniti, sostituisci navigationBarContainerColor:

NavigationSuiteScaffold(
    navigationSuiteItems = { /* ... */ },
    navigationSuiteColors = NavigationSuiteDefaults.colors(
        navigationBarContainerColor = Color.Transparent,
    )
) {
    // Content...
}
SampleNavigationSuiteScaffold.kt

Infine, puoi personalizzare ogni elemento della UI di navigazione. Quando chiami la item funzione, puoi passare un'istanza di NavigationSuiteItemColors. La classe specifica i colori per gli elementi di una barra di navigazione, una barra di spostamento e un riquadro di navigazione a scomparsa. Ciò significa che puoi avere colori identici per ogni tipo di UI di navigazione oppure puoi variare i colori in base alle tue esigenze. Definisci i colori a livello di NavigationSuiteScaffold per utilizzare la stessa istanza dell'oggetto per tutti gli elementi e chiama la funzione NavigationSuiteDefaults.itemColors() per sostituire solo quelli che vuoi modificare:

val myNavigationSuiteItemColors = NavigationSuiteDefaults.itemColors(
    navigationBarItemColors = NavigationBarItemDefaults.colors(
        indicatorColor = MaterialTheme.colorScheme.primaryContainer,
        selectedIconColor = MaterialTheme.colorScheme.onPrimaryContainer
    ),
)

NavigationSuiteScaffold(
    navigationSuiteItems = {
        AppDestinations.entries.forEach {
            item(
                icon = {
                    Icon(
                        it.icon,
                        contentDescription = stringResource(it.contentDescription)
                    )
                },
                label = { Text(stringResource(it.label)) },
                selected = it == currentDestination,
                onClick = { currentDestination = it },
                colors = myNavigationSuiteItemColors,
            )
        }
    },
) {
    // Content...
}
SampleNavigationSuiteScaffold.kt

Personalizza i tipi di navigazione

Il comportamento predefinito di NavigationSuiteScaffold modifica la UI di navigazione in base alle classi di dimensioni della finestra. Tuttavia, potresti voler sostituire questo comportamento. Ad esempio, se la tua app mostra un singolo riquadro di contenuti di grandi dimensioni per un feed, l'app potrebbe utilizzare un riquadro di navigazione a scomparsa permanente per le finestre espanse, ma comunque tornare al comportamento predefinito per le classi di dimensioni delle finestre compatte e medie:

val adaptiveInfo = currentWindowAdaptiveInfo()
val customNavSuiteType = with(adaptiveInfo) {
    if (windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_EXPANDED_LOWER_BOUND)) {
        NavigationSuiteType.NavigationDrawer
    } else {
        NavigationSuiteScaffoldDefaults.calculateFromAdaptiveInfo(adaptiveInfo)
    }
}

NavigationSuiteScaffold(
    navigationSuiteItems = { /* ... */ },
    layoutType = customNavSuiteType,
) {
    // Content...
}
SampleNavigationSuiteScaffold.kt

Risorse aggiuntive

Indietro
Supportare la fotocamera su più fattori di forma
Avanti
Crea un layout elenco-dettagli