Allgemeines UI-Rezept

In diesem Rezept wird gezeigt, wie Sie ein gängiges Navigations-UI-Muster mit einer unteren Navigationsleiste und mehreren Backstacks implementieren, wobei jeder Tab in der Navigationsleiste einen eigenen Navigationsverlauf hat.

Funktionsweise

Dieses Beispiel enthält drei Ziele der obersten Ebene: Home, ChatList und Camera. Das Ziel ChatList hat auch eine untergeordnete Route: ChatDetail.

TopLevelBackStack

Das Herzstück dieses Rezepts ist die Klasse TopLevelBackStack, die für die Verwaltung des Navigationsstatus verantwortlich ist. So funktioniert es:

  • Für jedes Ziel der obersten Ebene (Tab) wird ein separater Backstack verwaltet.
  • Hier wird das aktuell ausgewählte Ziel auf oberster Ebene angezeigt.
  • Sie bietet einen einzelnen, vereinfachten Backstack, der vom NavDisplay-Composable verwendet werden kann. Dieser zusammengeführte Backstack ist eine Kombination aus den einzelnen Backstacks aller Tabs.

UI-Struktur

Die Benutzeroberfläche wird mit einer Scaffold-Composable erstellt, wobei NavigationBar als bottomBar verwendet wird.

  • Im NavigationBar wird ein Element für jedes Ziel der obersten Ebene angezeigt. Wenn auf ein Element geklickt wird, wird topLevelBackStack.addTopLevel aufgerufen, um zum entsprechenden Tab zu wechseln. Der Navigationsverlauf der einzelnen Tabs wird dabei beibehalten.
  • Die zusammensetzbare Funktion NavDisplay wird im Inhaltsbereich von Scaffold platziert. Sie ist dafür verantwortlich, den aktuellen Bildschirm basierend auf dem von TopLevelBackStack bereitgestellten vereinfachten Backstack anzuzeigen.

Dieser Ansatz ermöglicht ein gemeinsames Navigationsmuster, bei dem Nutzer zwischen verschiedenen Bereichen der App wechseln können und jeder Bereich seinen eigenen Navigationsverlauf beibehält.

Status beibehalten

Es ist wichtig zu wissen, wie der Navigationsstatus in diesem Rezept verwaltet wird. Wenn ein Nutzer eine Zielseite auf der obersten Ebene verlässt, z.B. indem er die Schaltfläche „Zurück“ drückt, bis er zu einem vorherigen Tab zurückkehrt, wird der gesamte Navigationsverlauf für diese Zielseite gelöscht. Der Status wird nicht gespeichert. Wenn der Nutzer später zu diesem Tab zurückkehrt, wird der ursprüngliche Bildschirm angezeigt.

Hinweis: In diesem Beispiel kann die Route Home über die Routen ChatList und Camera verschoben werden. Das bedeutet, dass die App nicht unbedingt geschlossen wird, wenn der Nutzer von Home zurückkehrt. Die App wird geschlossen, wenn der Nutzer von einer einzelnen verbleibenden Route der obersten Ebene im Backstack zurückkehrt.

/*
 * Copyright 2025 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.example.nav3recipes.commonui

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Face
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.PlayArrow
import androidx.compose.material3.Button
import androidx.compose.material3.Icon
import androidx.compose.material3.NavigationBar
import androidx.compose.material3.NavigationBarItem
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.runtime.snapshots.SnapshotStateList
import androidx.compose.ui.graphics.vector.ImageVector
import androidx.lifecycle.compose.dropUnlessResumed
import androidx.navigation3.runtime.entryProvider
import androidx.navigation3.ui.NavDisplay
import com.example.nav3recipes.content.ContentBlue
import com.example.nav3recipes.content.ContentGreen
import com.example.nav3recipes.content.ContentPurple
import com.example.nav3recipes.content.ContentRed
import com.example.nav3recipes.ui.setEdgeToEdgeConfig

private sealed interface TopLevelRoute {
    val icon: ImageVector
}
private data object Home : TopLevelRoute { override val icon = Icons.Default.Home }
private data object ChatList : TopLevelRoute { override val icon = Icons.Default.Face }
private data object ChatDetail
private data object Camera : TopLevelRoute { override val icon = Icons.Default.PlayArrow }

private val TOP_LEVEL_ROUTES : List<TopLevelRoute> = listOf(Home, ChatList, Camera)

class CommonUiActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        setEdgeToEdgeConfig()
        super.onCreate(savedInstanceState)
        setContent {
            val topLevelBackStack = remember { TopLevelBackStack<Any>(Home) }

            Scaffold(
                bottomBar = {
                    NavigationBar {
                        TOP_LEVEL_ROUTES.forEach { topLevelRoute ->

                            val isSelected = topLevelRoute == topLevelBackStack.topLevelKey
                            NavigationBarItem(
                                selected = isSelected,
                                onClick = {
                                    topLevelBackStack.addTopLevel(topLevelRoute)
                                },
                                icon = {
                                    Icon(
                                        imageVector = topLevelRoute.icon,
                                        contentDescription = null
                                    )
                                }
                            )
                        }
                    }
                }
            ) { _ ->
                NavDisplay(
                    backStack = topLevelBackStack.backStack,
                    onBack = { topLevelBackStack.removeLast() },
                    entryProvider = entryProvider {
                        entry<Home>{
                            ContentRed("Home screen")
                        }
                        entry<ChatList>{
                            ContentGreen("Chat list screen"){
                                Button(onClick = dropUnlessResumed {
                                    topLevelBackStack.add(ChatDetail)
                                }) {
                                    Text("Go to conversation")
                                }
                            }
                        }
                        entry<ChatDetail>{
                            ContentBlue("Chat detail screen")
                        }
                        entry<Camera>{
                            ContentPurple("Camera screen")
                        }
                    },
                )
            }
        }
    }
}

class TopLevelBackStack<T: Any>(startKey: T) {

    // Maintain a stack for each top level route
    private var topLevelStacks : LinkedHashMap<T, SnapshotStateList<T>> = linkedMapOf(
        startKey to mutableStateListOf(startKey)
    )

    // Expose the current top level route for consumers
    var topLevelKey by mutableStateOf(startKey)
        private set

    // Expose the back stack so it can be rendered by the NavDisplay
    val backStack = mutableStateListOf(startKey)

    private fun updateBackStack() =
        backStack.apply {
            clear()
            addAll(topLevelStacks.flatMap { it.value })
        }

    fun addTopLevel(key: T){

        // If the top level doesn't exist, add it
        if (topLevelStacks[key] == null){
            topLevelStacks.put(key, mutableStateListOf(key))
        } else {
            // Otherwise just move it to the end of the stacks
            topLevelStacks.apply {
                remove(key)?.let {
                    put(key, it)
                }
            }
        }
        topLevelKey = key
        updateBackStack()
    }

    fun add(key: T){
        topLevelStacks[topLevelKey]?.add(key)
        updateBackStack()
    }

    fun removeLast(){
        val removedKey = topLevelStacks[topLevelKey]?.removeLastOrNull()
        // If the removed key was a top level key, remove the associated top level stack
        topLevelStacks.remove(removedKey)
        topLevelKey = topLevelStacks.keys.last()
        updateBackStack()
    }
}