构建辅助窗格布局

辅助窗格布局可让用户专注于应用的主要内容,同时显示相关的辅助信息。例如,主窗格可能会显示电影的详细信息,而辅助窗格会列出类似电影、同一导演的电影或同一演员出演的作品。

如需了解详情,请参阅 Material 3 辅助窗格指南

使用 NavigableSupportingPaneScaffold 实现辅助窗格

NavigableSupportingPaneScaffold 是一种可组合项,可简化在 Jetpack Compose 中实现辅助窗格布局。它封装了 SupportingPaneScaffold,并添加了内置导航和预测性返回处理。

辅助窗格架构最多支持三个窗格:

  • 主窗格:显示主要内容。
  • 辅助窗格:提供与主窗格相关的其他背景信息或工具。
  • 额外窗格(可选):用于在需要时显示补充内容。

该框架会根据窗口大小进行自适应:

  • 在大窗口中,主窗格和辅助窗格会并排显示。
  • 在小窗口中,一次只能显示一个窗格,并会随着用户浏览而切换。

    主要内容占据显示屏的大部分区域,辅助内容则显示在旁边。
    图 1. 辅助窗格布局。

添加依赖项

NavigableSupportingPaneScaffoldMaterial 3 自适应布局库的一部分。

将以下三个相关依赖项添加到应用或模块的 build.gradle 文件中:

Kotlin

implementation("androidx.compose.material3.adaptive:adaptive")
implementation("androidx.compose.material3.adaptive:adaptive-layout")
implementation("androidx.compose.material3.adaptive:adaptive-navigation")

Groovy

implementation 'androidx.compose.material3.adaptive:adaptive'
implementation 'androidx.compose.material3.adaptive:adaptive-layout'
implementation 'androidx.compose.material3.adaptive:adaptive-navigation'
  • 自适应:低级构建块,例如 HingeInfoPosture
  • adaptive-layoutListDetailPaneScaffoldSupportingPaneScaffold 等自适应布局
  • adaptive-navigation:用于在窗格内和窗格之间导航的 Compose 可组合项,以及默认支持导航的自适应布局,例如 NavigableListDetailPaneScaffoldNavigableSupportingPaneScaffold

确保您的项目包含 compose-material3-adaptive 1.1.0-beta1 版或更高版本。

选择启用预测性返回手势

如需在 Android 15 或更低版本中启用预测性返回动画,您必须选择启用预测性返回手势。如需选择启用,请将 android:enableOnBackInvokedCallback="true" 添加到 <application> 标记 [或将 android:enableOnBackInvokedCallback="true" 添加到 <application> 标记或 AndroidManifest.xml 文件中的单个 <activity> 标记]。

当您的应用以 Android 16(API 级别 36)或更高版本为目标平台后,系统会默认启用预测性返回。

创建导航器

在小窗口中,一次只能显示一个窗格,因此请使用 ThreePaneScaffoldNavigator 在窗格之间移动。使用 rememberSupportingPaneScaffoldNavigator 创建导航器的实例。

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

将导航器传递给框架

该架构需要 ThreePaneScaffoldNavigator,它是一个表示架构状态的接口、ThreePaneScaffoldValuePaneScaffoldDirective

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = { /*...*/ },
    supportingPane = { /*...*/ },
)

主窗格和辅助窗格是包含内容的可组合项。使用 AnimatedPane 在导航期间应用默认窗格动画。使用 Scaffold 值检查辅助窗格是否处于隐藏状态;如果处于隐藏状态,则显示一个按钮,用于调用 navigateTo(SupportingPaneScaffoldRole.Supporting) 以显示辅助窗格。

下面是该架构的完整实现:

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = {
        AnimatedPane(
            modifier = Modifier
                .safeContentPadding()
                .background(Color.Red)
        ) {
            if (scaffoldNavigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Hidden) {
                Button(
                    modifier = Modifier
                        .wrapContentSize(),
                    onClick = {
                        scope.launch {
                            scaffoldNavigator.navigateTo(SupportingPaneScaffoldRole.Supporting)
                        }
                    }
                ) {
                    Text("Show supporting pane")
                }
            } else {
                Text("Supporting pane is shown")
            }
        }
    },
    supportingPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            Text("Supporting pane")
        }
    }
)

提取窗格可组合项

SupportingPaneScaffold 的各个窗格提取到各自的可组合项中,以使其可重复使用和测试。如果您想要使用默认动画,请使用 ThreePaneScaffoldScope 访问 AnimatedPane

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ThreePaneScaffoldPaneScope.MainPane(
    shouldShowSupportingPaneButton: Boolean,
    onNavigateToSupportingPane: () -> Unit,
    modifier: Modifier = Modifier,
) {
    AnimatedPane(
        modifier = modifier.safeContentPadding()
    ) {
        // Main pane content
        if (shouldShowSupportingPaneButton) {
            Button(onClick = onNavigateToSupportingPane) {
                Text("Show supporting pane")
            }
        } else {
            Text("Supporting pane is shown")
        }
    }
}

@OptIn(ExperimentalMaterial3AdaptiveApi::class)
@Composable
fun ThreePaneScaffoldPaneScope.SupportingPane(
    modifier: Modifier = Modifier,
) {
    AnimatedPane(modifier = modifier.safeContentPadding()) {
        // Supporting pane content
        Text("This is the supporting pane")
    }
}

将窗格提取为可组合项可简化 SupportingPaneScaffold 的使用(将以下内容与上一部分中的架构的完整实现进行比较):

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

NavigableSupportingPaneScaffold(
    navigator = scaffoldNavigator,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = scaffoldNavigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = {
                scope.launch {
                    scaffoldNavigator.navigateTo(ThreePaneScaffoldRole.Secondary)
                }
            }
        )
    },
    supportingPane = { SupportingPane() },
)

如果您需要更好地控制框架的特定方面,请考虑使用 SupportingPaneScaffold 而非 NavigableSupportingPaneScaffold。此参数分别接受 PaneScaffoldDirectiveThreePaneScaffoldValueThreePaneScaffoldState。这种灵活性可让您为窗格间距实现自定义逻辑,并确定应同时显示多少个窗格。您还可以通过添加 ThreePaneScaffoldPredictiveBackHandler 来启用预测性返回支持。

添加了 ThreePaneScaffoldPredictiveBackHandler

附加接受 Scaffold 导航器实例并指定 backBehavior 的预测性返回处理程序。这决定了在返回导航期间如何从返回堆栈中弹出目的地。然后,将 scaffoldDirectivescaffoldState 传递给 SupportingPaneScaffold。使用接受 ThreePaneScaffoldState 的过载,并传入 scaffoldNavigator.scaffoldState

SupportingPaneScaffold 中定义主窗格和辅助窗格。使用 AnimatedPane 实现默认窗格动画。

实现这些步骤后,您的代码应如下所示:

val scaffoldNavigator = rememberSupportingPaneScaffoldNavigator()
val scope = rememberCoroutineScope()

ThreePaneScaffoldPredictiveBackHandler(
    navigator = scaffoldNavigator,
    backBehavior = BackNavigationBehavior.PopUntilScaffoldValueChange
)

SupportingPaneScaffold(
    directive = scaffoldNavigator.scaffoldDirective,
    scaffoldState = scaffoldNavigator.scaffoldState,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = scaffoldNavigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = {
                scope.launch {
                    scaffoldNavigator.navigateTo(ThreePaneScaffoldRole.Secondary)
                }
            }
        )
    },
    supportingPane = { SupportingPane() },
)