此页面由 Cloud Translation API 翻译。

使用场景创建自定义布局

Navigation 3 引入了一个强大而灵活的系统，用于通过场景管理应用的界面流程。借助场景，您可以创建高度自定义的布局，适应不同的屏幕尺寸，并无缝管理复杂的多窗格体验。

了解场景

在 Navigation 3 中，Scene 是渲染一个或多个 NavEntry 实例的基本单元。您可以将 Scene 视为界面的一个独特的视觉状态或部分，它可以包含并管理来自返回堆栈的内容的显示。

每个 Scene 实例都由其 key 和 Scene 本身的类唯一标识。此唯一标识符至关重要，因为当 Scene 发生变化时，它会驱动顶级动画。

Scene 接口具有以下属性：

key: Any：相应特定 Scene 实例的唯一标识符。此键与 Scene 的类相结合，可确保唯一性，主要用于动画。
entries: List<NavEntry<T>>：这是 Scene 负责显示的 NavEntry 对象的列表。重要的是，如果在过渡期间（例如在共享元素过渡中）同一 NavEntry 显示在多个 Scenes 中，则其内容将仅由显示它的最新目标 Scene 呈现。
previousEntries: List<NavEntry<T>>：此属性定义了如果从当前 Scene 执行“返回”操作，将会产生的 NavEntry。这对于计算正确的预测性返回状态至关重要，可让 NavDisplay 预测并过渡到正确的上一个状态，该状态可能是具有不同类和/或键的场景。
content: @Composable () -> Unit：您可以在此可组合函数中定义 Scene 如何渲染其 entries 以及特定于该 Scene 的任何周围界面元素。

了解场景策略

SceneStrategy 是一种机制，用于确定如何排列后退堆栈中的给定 NavEntry 列表并将其过渡到 Scene。从本质上讲，当呈现当前返回堆栈条目时，SceneStrategy 会自问两个关键问题：

我可以从这些条目中创建 Scene 吗？如果 SceneStrategy 确定它可以处理给定的 NavEntry 并形成有意义的 Scene（例如对话框或多窗格布局），则继续。否则，它会返回 null，让其他策略有机会创建 Scene。
如果是，我应该如何将这些条目安排到 Scene? 中？一旦 SceneStrategy 提交处理条目，它就会负责构建 Scene 并定义指定的 NavEntry 将如何显示在该 Scene 中。

SceneStrategy 的核心是其 calculateScene 方法：

@Composable
public fun calculateScene(
    entries: List<NavEntry<T>>,
    onBack: (count: Int) -> Unit,
): Scene<T>?ScenesSnippets.kt

此方法是 SceneStrategyScope 上的扩展函数，它会从返回堆栈中获取当前的 List<NavEntry<T>>。如果能够成功从提供的条目中形成一个 Scene<T>，则应返回该 Scene<T>；如果不能，则应返回 null。

SceneStrategyScope 负责维护 SceneStrategy 可能需要的任何可选实参，例如 onBack 回调。

SceneStrategy 还提供了一个便捷的 then 中缀函数，可让您将多个策略链接在一起。这会创建一个灵活的决策流水线，其中每种策略都可以尝试计算 Scene，如果无法计算，则委托给链中的下一个策略。

场景和场景策略如何协同运作

NavDisplay 是一个中心可组合项，用于观察返回堆栈并使用 SceneStrategy 来确定和渲染相应的 Scene。

NavDisplay's sceneStrategy 参数需要一个负责计算要显示的 Scene 的 SceneStrategy。如果所提供的策略（或策略链）未计算出任何 Scene，NavDisplay 会自动默认回退到使用 SinglePaneSceneStrategy。

以下是互动流程：

当您从返回堆栈中添加或移除键（例如，使用 backStack.add() 或 backStack.removeLastOrNull()）时，NavDisplay 会观察到这些变化。
NavDisplay 会将当前的 NavEntrys 列表（从返回堆栈键派生）传递给配置的 SceneStrategy's calculateScene 方法。
如果 SceneStrategy 成功返回 Scene，则 NavDisplay 会呈现相应 Scene 的 content。NavDisplay 还根据 Scene 的属性管理动画和预测性返回。

示例：单窗格布局（默认行为）

最简单的自定义布局是单窗格显示，如果没有任何其他 SceneStrategy 优先，则这是默认行为。

data class SinglePaneScene<T : Any>(
    override val key: Any,
    val entry: NavEntry<T>,
    override val previousEntries: List<NavEntry<T>>,
) : Scene<T> {
    override val entries: List<NavEntry<T>> = listOf(entry)
    override val content: @Composable () -> Unit = { entry.Content() }
}

/**
 * A [SceneStrategy] that always creates a 1-entry [Scene] simply displaying the last entry in the
 * list.
 */
public class SinglePaneSceneStrategy<T : Any> : SceneStrategy<T> {
    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? =
        SinglePaneScene(
            key = entries.last().contentKey,
            entry = entries.last(),
            previousEntries = entries.dropLast(1)
        )
}ScenesSnippets.kt

示例：基本列表-详情布局（自定义场景和策略）

此示例演示了如何创建基于以下两个条件激活的简单列表-详情布局：

窗口宽度足够宽，可以支持两个窗格（即至少 WIDTH_DP_MEDIUM_LOWER_BOUND）。
返回堆栈包含已声明其支持使用特定元数据在列表-详情布局中显示的条目。

以下代码段是 ListDetailScene.kt 的源代码，其中包含 ListDetailScene 和 ListDetailSceneStrategy：

// --- ListDetailScene ---
/**
 * A [Scene] that displays a list and a detail [NavEntry] side-by-side in a 40/60 split.
 *
 */
class ListDetailScene<T : Any>(
    override val key: Any,
    override val previousEntries: List<NavEntry<T>>,
    val listEntry: NavEntry<T>,
    val detailEntry: NavEntry<T>,
) : Scene<T> {
    override val entries: List<NavEntry<T>> = listOf(listEntry, detailEntry)
    override val content: @Composable (() -> Unit) = {
        Row(modifier = Modifier.fillMaxSize()) {
            Column(modifier = Modifier.weight(0.4f)) {
                listEntry.Content()
            }
            Column(modifier = Modifier.weight(0.6f)) {
                detailEntry.Content()
            }
        }
    }
}

@Composable
fun <T : Any> rememberListDetailSceneStrategy(): ListDetailSceneStrategy<T> {
    val windowSizeClass = currentWindowAdaptiveInfo().windowSizeClass

    return remember(windowSizeClass) {
        ListDetailSceneStrategy(windowSizeClass)
    }
}

// --- ListDetailSceneStrategy ---
/**
 * A [SceneStrategy] that returns a [ListDetailScene] if the window is wide enough, the last item
 * is the backstack is a detail, and before it, at any point in the backstack is a list.
 */
class ListDetailSceneStrategy<T : Any>(val windowSizeClass: WindowSizeClass) : SceneStrategy<T> {

    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? {

        if (!windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND)) {
            return null
        }

        val detailEntry =
            entries.lastOrNull()?.takeIf { it.metadata.containsKey(DETAIL_KEY) } ?: return null
        val listEntry = entries.findLast { it.metadata.containsKey(LIST_KEY) } ?: return null

        // We use the list's contentKey to uniquely identify the scene.
        // This allows the detail panes to be displayed instantly through recomposition, rather than
        // having NavDisplay animate the whole scene out when the selected detail item changes.
        val sceneKey = listEntry.contentKey

        return ListDetailScene(
            key = sceneKey,
            previousEntries = entries.dropLast(1),
            listEntry = listEntry,
            detailEntry = detailEntry
        )
    }

    companion object {
        internal const val LIST_KEY = "ListDetailScene-List"
        internal const val DETAIL_KEY = "ListDetailScene-Detail"

        /**
         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
         * as a list in the [ListDetailScene].
         */
        fun listPane() = mapOf(LIST_KEY to true)

        /**
         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
         * as a list in the [ListDetailScene].
         */
        fun detailPane() = mapOf(DETAIL_KEY to true)
    }
}ScenesSnippets.kt

如需在 NavDisplay 中使用此 ListDetailSceneStrategy，请修改 entryProvider 调用，以针对您打算显示为列表布局的条目添加 ListDetailScene.listPane() 元数据，并针对您想要显示为详情布局的条目添加 ListDetailScene.detailPane()。然后，提供 ListDetailSceneStrategy() 作为 sceneStrategy，依靠单窗格场景的默认回退：

// Define your navigation keys
@Serializable
data object ConversationList : NavKey

@Serializable
data class ConversationDetail(val id: String) : NavKey

@Composable
fun MyAppContent() {
    val backStack = rememberNavBackStack(ConversationList)
    val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>()

    NavDisplay(
        backStack = backStack,
        onBack = { backStack.removeLastOrNull() },
        sceneStrategy = listDetailStrategy,
        entryProvider = entryProvider {
            entry<ConversationList>(
                metadata = ListDetailSceneStrategy.listPane()
            ) {
                Column(modifier = Modifier.fillMaxSize()) {
                    Text(text = "I'm a Conversation List")
                    Button(onClick = { backStack.addDetail(ConversationDetail("123")) }) {
                        Text(text = "Open detail")
                    }
                }
            }
            entry<ConversationDetail>(
                metadata = ListDetailSceneStrategy.detailPane()
            ) {
                Text(text = "I'm a Conversation Detail")
            }
        }
    )
}

private fun NavBackStack<NavKey>.addDetail(detailRoute: ConversationDetail) {

    // Remove any existing detail routes, then add the new detail route
    removeIf { it is ConversationDetail }
    add(detailRoute)
}ScenesSnippets.kt

如果您不想创建自己的列表-详情场景，可以使用 Material 列表-详情场景，该场景附带合理的详情并支持占位符，如下一部分所示。

在 Material 自适应场景中显示列表-详情内容

对于列表-详情使用情形，androidx.compose.material3.adaptive:adaptive-navigation3 制品提供了一个 ListDetailSceneStrategy，用于创建列表-详情 Scene。此 Scene 可自动处理复杂的多窗格布局（列表、详情和其他窗格），并根据窗口大小和设备状态调整这些布局。

如需创建 Material 列表-详情 Scene，请按以下步骤操作：

添加依赖项：在项目的 build.gradle.kts 文件中添加 androidx.compose.material3.adaptive:adaptive-navigation3。
使用 ListDetailSceneStrategy 元数据定义条目：使用 listPane(), detailPane() 和 extraPane() 标记 NavEntrys 以便在相应窗格中显示。借助 listPane() 辅助函数，您还可以在未选择任何项时指定 detailPlaceholder。
使用 rememberListDetailSceneStrategy()：此可组合函数提供了一个预配置的 ListDetailSceneStrategy，可供 NavDisplay 使用。

以下代码段是一个示例 Activity，演示了 ListDetailSceneStrategy 的用法：

@Serializable
object ProductList : NavKey

@Serializable
data class ProductDetail(val id: String) : NavKey

@Serializable
data object Profile : NavKey

class MaterialListDetailActivity : ComponentActivity() {

    @OptIn(ExperimentalMaterial3AdaptiveApi::class)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            Scaffold { paddingValues ->
                val backStack = rememberNavBackStack(ProductList)
                val listDetailStrategy = rememberListDetailSceneStrategy<NavKey>()

                NavDisplay(
                    backStack = backStack,
                    modifier = Modifier.padding(paddingValues),
                    onBack = { backStack.removeLastOrNull() },
                    sceneStrategy = listDetailStrategy,
                    entryProvider = entryProvider {
                        entry<ProductList>(
                            metadata = ListDetailSceneStrategy.listPane(
                                detailPlaceholder = {
                                    ContentYellow("Choose a product from the list")
                                }
                            )
                        ) {
                            ContentRed("Welcome to Nav3") {
                                Button(onClick = {
                                    backStack.add(ProductDetail("ABC"))
                                }) {
                                    Text("View product")
                                }
                            }
                        }
                        entry<ProductDetail>(
                            metadata = ListDetailSceneStrategy.detailPane()
                        ) { product ->
                            ContentBlue("Product ${product.id} ", Modifier.background(PastelBlue)) {
                                Column(horizontalAlignment = Alignment.CenterHorizontally) {
                                    Button(onClick = {
                                        backStack.add(Profile)
                                    }) {
                                        Text("View profile")
                                    }
                                }
                            }
                        }
                        entry<Profile>(
                            metadata = ListDetailSceneStrategy.extraPane()
                        ) {
                            ContentGreen("Profile")
                        }
                    }
                )
            }
        }
    }
}MaterialScenesSnippets.kt

图 1. 在 Material 列表-详情场景中运行的示例内容。

使用场景创建自定义布局 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。