Công thức giao diện người dùng phổ biến

Công thức này minh hoạ cách triển khai một mẫu giao diện người dùng điều hướng phổ biến bằng thanh điều hướng dưới cùng và nhiều ngăn xếp lui, trong đó mỗi thẻ trong thanh điều hướng có nhật ký điều hướng riêng.

Cách hoạt động

Ví dụ này có 3 đích đến cấp cao nhất: Home, ChatList và Camera. Đích đến ChatList cũng có một tuyến đường phụ là ChatDetail.

TopLevelBackStack

Cốt lõi của công thức này là lớp TopLevelBackStack, chịu trách nhiệm quản lý trạng thái điều hướng. Cách thức hoạt động như sau:

  • Nó duy trì một ngăn xếp lui riêng cho từng đích đến cấp cao nhất (thẻ).
  • Nó theo dõi đích đến cấp cao nhất hiện được chọn.
  • Thư viện này cung cấp một ngăn xếp lui duy nhất, được làm phẳng mà thành phần kết hợp NavDisplay có thể dùng. Ngăn xếp lui được làm phẳng này là sự kết hợp của các ngăn xếp lui riêng lẻ của tất cả các thẻ.

Cấu trúc giao diện người dùng

Giao diện người dùng được tạo bằng thành phần kết hợp Scaffold, với NavigationBar là bottomBar.

  • NavigationBar hiển thị một mục cho mỗi điểm đến cấp cao nhất. Khi một mục được nhấp vào, mục đó sẽ gọi topLevelBackStack.addTopLevel để chuyển sang thẻ tương ứng, duy trì nhật ký điều hướng của từng thẻ.
  • Thành phần kết hợp NavDisplay được đặt trong vùng nội dung của Scaffold. Thành phần này chịu trách nhiệm hiển thị màn hình hiện tại dựa trên ngăn xếp lui được rút gọn do TopLevelBackStack cung cấp.

Phương pháp này cho phép tạo một mẫu điều hướng chung, trong đó người dùng có thể chuyển đổi giữa các phần khác nhau của ứng dụng và mỗi phần duy trì nhật ký điều hướng riêng.

Lưu giữ trạng thái

Điều quan trọng là bạn phải lưu ý cách trạng thái điều hướng được quản lý trong công thức này. Khi người dùng rời khỏi một đích đến cấp cao nhất (ví dụ: bằng cách nhấn nút quay lại cho đến khi họ quay lại thẻ trước đó), toàn bộ nhật ký điều hướng cho đích đến đó sẽ bị xoá. Trạng thái không được lưu. Khi quay lại thẻ đó sau này, người dùng sẽ bắt đầu từ màn hình ban đầu của thẻ.

Lưu ý: Trong ví dụ này, tuyến đường Home có thể di chuyển lên trên các tuyến đường ChatList và Camera, nghĩa là việc điều hướng quay lại từ Home không nhất thiết phải rời khỏi ứng dụng. Ứng dụng sẽ thoát khi người dùng quay lại từ một tuyến đường cấp cao nhất còn lại duy nhất trong ngăn xếp lui.

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