Типичный рецепт пользовательского интерфейса
В этом примере показано, как реализовать распространенный шаблон навигации в пользовательском интерфейсе с нижней панелью навигации и несколькими стеками «назад», где каждая вкладка в панели навигации имеет свою собственную историю навигации.
Как это работает
В этом примере три основных целевого объекта: Home , ChatList и Camera . Целевой объект ChatList также имеет подмаршрут ChatDetail .
TopLevelBackStack
В основе этого рецепта лежит класс TopLevelBackStack , отвечающий за управление состоянием навигации. Он работает следующим образом:
- Для каждой вкладки верхнего уровня поддерживается отдельный стек возврата.
- Она отслеживает текущий выбранный пункт назначения верхнего уровня.
- Он предоставляет единый, плоский стек вкладок, который может использоваться компонентом
NavDisplay . Этот плоский стек вкладок представляет собой комбинацию отдельных стеков вкладок всех вкладок.
Структура пользовательского интерфейса
Пользовательский интерфейс создан с использованием компонента Scaffold , в качестве bottomBar используется NavigationBar .
-
NavigationBar отображает элемент для каждого элемента верхнего уровня. При щелчке по элементу вызывается метод topLevelBackStack.addTopLevel для переключения на соответствующую вкладку, сохраняя историю навигации каждой вкладки. - Компонент
NavDisplay размещается в области содержимого Scaffold . Он отвечает за отображение текущего экрана на основе сглаженного стека возврата, предоставляемого компонентом TopLevelBackStack .
Такой подход позволяет использовать единую схему навигации, при которой пользователи могут переключаться между различными разделами приложения, и каждый раздел сохраняет свою собственную историю навигации.
Государственная охрана
Важно отметить, как в этом примере управляется состояние навигации. Когда пользователь покидает вкладку верхнего уровня (например, нажимая кнопку «Назад» до возврата к предыдущей вкладке), вся история навигации для этой вкладки очищается. Состояние не сохраняется. Когда пользователь вернется к этой вкладке позже, он начнет с ее начального экрана.
Примечание : В этом примере маршрут Home может перемещаться выше маршрутов ChatList и Camera , а это значит, что возврат с Home не обязательно означает выход из приложения. Приложение закроется, когда пользователь вернется с единственного оставшегося маршрута верхнего уровня в стеке возврата.
Исследовать
Полный рецепт можно посмотреть на GitHub.
/*
* 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()
}
}
