此页面由 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）。
返回堆栈上的前两个条目使用特定元数据明确声明它们支持以双窗格布局显示。

以下代码段是 TwoPaneScene.kt 和 TwoPaneSceneStrategy.kt 的组合源代码：

// --- TwoPaneScene ---
/**
 * A custom [Scene] that displays two [NavEntry]s side-by-side in a 50/50 split.
 */
class TwoPaneScene<T : Any>(
    override val key: Any,
    override val previousEntries: List<NavEntry<T>>,
    val firstEntry: NavEntry<T>,
    val secondEntry: NavEntry<T>
) : Scene<T> {
    override val entries: List<NavEntry<T>> = listOf(firstEntry, secondEntry)
    override val content: @Composable (() -> Unit) = {
        Row(modifier = Modifier.fillMaxSize()) {
            Column(modifier = Modifier.weight(0.5f)) {
                firstEntry.Content()
            }
            Column(modifier = Modifier.weight(0.5f)) {
                secondEntry.Content()
            }
        }
    }

    companion object {
        internal const val TWO_PANE_KEY = "TwoPane"
        /**
         * Helper function to add metadata to a [NavEntry] indicating it can be displayed
         * in a two-pane layout.
         */
        fun twoPane() = mapOf(TWO_PANE_KEY to true)
    }
}

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

    return remember(windowSizeClass) {
        TwoPaneSceneStrategy(windowSizeClass)
    }
}

// --- TwoPaneSceneStrategy ---
/**
 * A [SceneStrategy] that activates a [TwoPaneScene] if the window is wide enough
 * and the top two back stack entries declare support for two-pane display.
 */
class TwoPaneSceneStrategy<T : Any>(val windowSizeClass: WindowSizeClass) : SceneStrategy<T> {
    override fun SceneStrategyScope<T>.calculateScene(entries: List<NavEntry<T>>): Scene<T>? {
        // Condition 1: Only return a Scene if the window is sufficiently wide to render two panes.
        // We use isWidthAtLeastBreakpoint with WIDTH_DP_MEDIUM_LOWER_BOUND (600dp).
        if (!windowSizeClass.isWidthAtLeastBreakpoint(WIDTH_DP_MEDIUM_LOWER_BOUND)) {
            return null
        }

        val lastTwoEntries = entries.takeLast(2)

        // Condition 2: Only return a Scene if there are two entries, and both have declared
        // they can be displayed in a two pane scene.
        return if (lastTwoEntries.size == 2 &&
            lastTwoEntries.all { it.metadata.containsKey(TwoPaneScene.TWO_PANE_KEY) }
        ) {
            val firstEntry = lastTwoEntries.first()
            val secondEntry = lastTwoEntries.last()

            // The scene key must uniquely represent the state of the scene.
            val sceneKey = Pair(firstEntry.contentKey, secondEntry.contentKey)

            TwoPaneScene(
                key = sceneKey,
                // Where we go back to is a UX decision. In this case, we only remove the top
                // entry from the back stack, despite displaying two entries in this scene.
                // This is because in this app we only ever add one entry to the
                // back stack at a time. It would therefore be confusing to the user to add one
                // when navigating forward, but remove two when navigating back.
                previousEntries = entries.dropLast(1),
                firstEntry = firstEntry,
                secondEntry = secondEntry
            )
        } else {
            null
        }
    }
}ScenesSnippets.kt

如需在 NavDisplay 中使用此 TwoPaneSceneStrategy，请修改 entryProvider 调用，以包含您打算在双窗格布局中显示的条目的 TwoPaneScene.twoPane() 元数据。然后，将 TwoPaneSceneStrategy() 作为 sceneStrategy 提供，并依赖于单窗格场景的默认回退：

// Define your navigation keys
@Serializable
data object ProductList : NavKey
@Serializable
data class ProductDetail(val id: String) : NavKey

@Composable
fun MyAppContent() {
    val backStack = rememberNavBackStack(ProductList)

    NavDisplay(
        backStack = backStack,
        entryProvider = entryProvider {
            entry<ProductList>(
                // Mark this entry as eligible for two-pane display
                metadata = TwoPaneScene.twoPane()
            ) { key ->
                Column {
                    Text("Product List")
                    Button(onClick = { backStack.add(ProductDetail("ABC")) }) {
                        Text("View Details for ABC (Two-Pane Eligible)")
                    }
                }
            }

            entry<ProductDetail>(
                // Mark this entry as eligible for two-pane display
                metadata = TwoPaneScene.twoPane()
            ) { key ->
                Text("Product Detail: ${key.id} (Two-Pane Eligible)")
            }
            // ... other entries ...
        },
        // Simply provide your custom strategy. NavDisplay will fall back to SinglePaneSceneStrategy automatically.
        sceneStrategy = rememberTwoPaneSceneStrategy(),
        onBack = {
            if (backStack.isNotEmpty()) {
                backStack.removeLastOrNull()
            }
        }
    )
}ScenesSnippets.kt

在 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 列表-详情场景中运行的示例内容。

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