Recette d'UI courante

Cette recette montre comment implémenter un modèle d'UI de navigation courant avec une barre de navigation inférieure et plusieurs piles "Retour", où chaque onglet de la barre de navigation possède son propre historique de navigation.

Fonctionnement

Cet exemple comporte trois destinations de premier niveau : Home, ChatList et Camera. La destination ChatList comporte également une sous-route, ChatDetail.

TopLevelBackStack

Le cœur de cette recette est la classe TopLevelBackStack, qui est responsable de la gestion de l'état de navigation. Voici comment cela fonctionne :

  • Elle conserve une pile "Retour" distincte pour chaque destination de premier niveau (onglet).
  • Elle permet de suivre la destination de premier niveau actuellement sélectionnée.
  • Il fournit une seule pile "Retour" aplatie qui peut être utilisée par le composable NavDisplay. Cette pile "Retour" aplatie est une combinaison des piles "Retour" individuelles de tous les onglets.

Structure de l'UI

L'UI est créée à l'aide d'un composable Scaffold, avec un NavigationBar comme bottomBar.

  • Le NavigationBar affiche un élément pour chaque destination de premier niveau. Lorsqu'un élément est sélectionné, il appelle topLevelBackStack.addTopLevel pour passer à l'onglet correspondant, en conservant l'historique de navigation de chaque onglet.
  • Le composable NavDisplay est placé dans la zone de contenu de Scaffold. Il est chargé d'afficher l'écran actuel en fonction de la pile "Retour" aplatie fournie par TopLevelBackStack.

Cette approche permet un modèle de navigation commun dans lequel les utilisateurs peuvent basculer entre différentes sections de l'application, chaque section conservant son propre historique de navigation.

Conservation de l'état

Il est important de noter comment l'état de navigation est géré dans cette recette. Lorsqu'un utilisateur quitte une destination de premier niveau (par exemple, en appuyant sur le bouton "Retour" jusqu'à ce qu'il revienne à un onglet précédent), l'intégralité de l'historique de navigation pour cette destination est effacée. L'état n'est pas enregistré. Lorsque l'utilisateur revient sur cet onglet plus tard, il recommence à partir de son écran initial.

Remarque : Dans cet exemple, la route Home peut se déplacer au-dessus des routes ChatList et Camera, ce qui signifie que la navigation vers l'arrière à partir de Home ne quitte pas nécessairement l'application. L'application se fermera lorsque l'utilisateur reviendra en arrière à partir d'une seule route de niveau supérieur restante dans la pile "Retour".

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