Adaptive Navigation erstellen

Die meisten Apps haben einige übergeordnete Ziele, die über die primäre Navigations-UI der App zugänglich sind. In kompakten Fenstern, z. B. auf einem Standard-Smartphone-Display, werden die Ziele normalerweise in einer Navigationsleiste am unteren Rand des Fensters angezeigt. In einem maximierten Fenster, z. B. einer Vollbild-App auf einem Tablet, ist eine Navigationsleiste neben der App in der Regel die bessere Wahl, da die Navigationssteuerelemente leichter zu erreichen sind, wenn das Gerät links und rechts gehalten wird.

NavigationSuiteScaffold vereinfacht den Wechsel zwischen Navigations-UIs, indem das entsprechende Navigations-UI-Composable basierend auf WindowSizeClass angezeigt wird. Dazu gehört auch die dynamische Änderung der Benutzeroberfläche, wenn sich die Fenstergröße während der Laufzeit ändert. Das Standardverhalten ist, eine der folgenden UI-Komponenten anzuzeigen:

  • Navigationsleiste, wenn die Breite oder Höhe kompakt ist oder sich das Gerät im Tischmodus befindet
  • Navigationsstreifen für alles andere
Abbildung 1. NavigationSuiteScaffold zeigt eine Navigationsleiste in kompakten Fenstern an.
Abbildung 2. NavigationSuiteScaffold zeigt eine Navigationsleiste in maximierten Fenstern an.

Abhängigkeiten hinzufügen

NavigationSuiteScaffold ist Teil der Bibliothek Material3 Adaptive Navigation Suite. Fügen Sie in der Datei build.gradle Ihrer App oder Ihres Moduls eine Abhängigkeit für die Bibliothek hinzu:

Kotlin

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

Groovy

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

Gerüst erstellen

Die beiden Hauptteile von NavigationSuiteScaffold sind die Elemente der Navigationsleiste und der Inhalt für das ausgewählte Ziel. Sie können die Elemente der Navigations-Suite direkt in einer zusammensetzbaren Funktion definieren. Es ist jedoch üblich, sie an anderer Stelle zu definieren, z. B. in einer Aufzählung:

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

Wenn Sie NavigationSuiteScaffold verwenden möchten, müssen Sie das aktuelle Ziel im Blick behalten. Dazu können Sie rememberSaveable verwenden:

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

Im folgenden Beispiel wird der Parameter navigationSuiteItems (Typ NavigationSuiteScope) mit der Funktion item verwendet, um die Navigations-UI für ein einzelnes Ziel zu definieren. Die Ziel-UI wird in Navigationsleisten, ‑leisten und ‑leisten verwendet. Wenn Sie Navigationselemente erstellen möchten, durchlaufen Sie die AppDestinations-Elemente (im vorherigen Snippet definiert):

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

Verwenden Sie im Lambda-Ausdruck für den Zielinhalt den Wert currentDestination, um zu entscheiden, welche Benutzeroberfläche angezeigt werden soll. Wenn Sie in Ihrer App eine Navigationsbibliothek verwenden, können Sie sie hier verwenden, um das entsprechende Ziel anzuzeigen. Eine when-Anweisung kann ausreichen:

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

Farben ändern

NavigationSuiteScaffold erstellt einen Surface über den gesamten Bereich, den das Scaffold einnimmt, in der Regel das gesamte Fenster. Außerdem zeichnet das Scaffold die jeweilige Navigations-UI, z. B. eine NavigationBar. Sowohl die Oberfläche als auch die Navigations-UI verwenden die im Design Ihrer App angegebenen Werte. Sie können die Designwerte jedoch überschreiben.

Der Parameter containerColor gibt die Farbe der Oberfläche an. Die Standardeinstellung ist die Hintergrundfarbe Ihres Farbschemas. Der Parameter contentColor gibt die Farbe des Inhalts auf dieser Oberfläche an. Die Standardeinstellung ist die „on“-Farbe des für containerColor angegebenen Elements. Wenn containerColor beispielsweise die Farbe background verwendet, verwendet contentColor die Farbe onBackground. Weitere Informationen zur Funktionsweise des Farbsystems findest du unter Material Design 3-Theming in Compose. Wenn Sie diese Werte überschreiben, verwenden Sie Werte, die in Ihrem Design definiert sind, damit Ihre App den dunklen und hellen Anzeigemodus unterstützt:

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

Die Navigations-UI wird vor der NavigationSuiteScaffold-Oberfläche dargestellt. Die Standardwerte für die UI-Farben werden von NavigationSuiteDefaults.colors() bereitgestellt. Sie können diese Werte jedoch auch überschreiben. Wenn Sie beispielsweise möchten, dass der Hintergrund der Navigationsleiste transparent ist, die anderen Werte aber die Standardwerte sind, überschreiben Sie navigationBarContainerColor:

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

Letztendlich können Sie jedes Element in der Navigations-UI anpassen. Beim Aufrufen der Funktion item können Sie eine Instanz von NavigationSuiteItemColors übergeben. Die Klasse gibt die Farben für Elemente in einer Navigationsleiste, einem Navigationsstreifen und einer Navigationsleiste an. Das bedeutet, dass Sie für jeden Navigations-UI-Typ identische Farben verwenden oder die Farben je nach Bedarf variieren können. Definieren Sie die Farben auf der Ebene NavigationSuiteScaffold, um für alle Elemente dieselbe Objektinstanz zu verwenden, und rufen Sie die Funktion NavigationSuiteDefaults.itemColors() auf, um nur die Farben zu überschreiben, die Sie ändern möchten:

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

Bedienungstypen anpassen

Das Standardverhalten von NavigationSuiteScaffold ändert die Navigations-UI basierend auf den Fenstergrößenklassen. Möglicherweise möchten Sie dieses Verhalten jedoch überschreiben. Wenn Ihre App beispielsweise einen einzelnen großen Inhaltsbereich für einen Feed anzeigt, könnte die App eine permanente Navigationsleiste für maximierte Fenster verwenden, aber dennoch auf das Standardverhalten für kompakte und mittelgroße Fenstergrößenklassen zurückgreifen:

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

Zusätzliche Ressourcen

Zurück
Layout mit unterstützendem Bereich erstellen
Weiter
App-Verfügbarkeit erhöhen