一般的な UI レシピ

このレシピでは、ボトム ナビゲーション バーと複数のバックスタックを使用して一般的なナビゲーション UI パターンを実装する方法を示します。ナビゲーション バーの各タブには、独自のナビゲーション履歴があります。

仕組み

この例には、Home、ChatList、Camera の 3 つの最上位のデスティネーションがあります。ChatList の宛先には、ChatDetail というサブルートもあります。

TopLevelBackStack

このレシピの中核となるのは、ナビゲーションの状態を管理する TopLevelBackStack クラスです。機能は次のとおりです。

  • 最上位のデスティネーション（タブ）ごとに個別のバックスタックを保持します。
  • 現在選択されている最上位の宛先を追跡します。
  • NavDisplay コンポーザブルで使用できる単一のフラット化されたバックスタックを提供します。このフラット化されたバックスタックは、すべてのタブの個々のバックスタックを組み合わせたものです。

UI の構造

UI は Scaffold コンポーザブルを使用して作成され、NavigationBar が bottomBar として使用されます。

  • NavigationBar には、最上位の宛先ごとに 1 つのアイテムが表示されます。項目がクリックされると、topLevelBackStack.addTopLevel を呼び出して対応するタブに切り替え、各タブのナビゲーション履歴を保持します。
  • コンポーザブル NavDisplay は Scaffold のコンテンツ領域に配置されます。TopLevelBackStack から提供されたフラット化されたバックスタックに基づいて、現在の画面を表示する役割を担います。

このアプローチでは、ユーザーがアプリのさまざまなセクションを切り替えることができ、各セクションが独自のナビゲーション履歴を保持する共通のナビゲーション パターンが可能になります。

状態の保持

このレシピでは、ナビゲーションの状態がどのように管理されているかに注意することが重要です。ユーザーがトップレベルのデスティネーションから移動すると（たとえば、前のタブに戻るまで [戻る] ボタンを押すなど）、そのデスティネーションのナビゲーション履歴全体がクリアされます。状態は保存されません。ユーザーが後でそのタブに戻ると、最初の画面から開始されます。

注: この例では、Home ルートは ChatList ルートと Camera ルートの上に移動できます。つまり、Home から戻っても、必ずしもアプリが終了するとは限りません。アプリは、ユーザーがバックスタック内の残りの 1 つの最上位ルートから戻ったときに終了します。

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