辅助窗格布局可让用户专注于应用的主要内容,同时显示相关的辅助信息。例如,主窗格可能会显示电影的详细信息,而辅助窗格会列出类似电影、同一导演的电影或同一演员出演的作品。
如需了解详情,请参阅 Material 3 辅助窗格指南。
使用 NavigableSupportingPaneScaffold 实现辅助窗格
NavigableSupportingPaneScaffold
是一种可组合项,可简化在 Jetpack Compose 中实现辅助窗格布局。它封装了 SupportingPaneScaffold
,并添加了内置导航和预测性返回处理。
辅助窗格架构最多支持三个窗格:
- 主窗格:显示主要内容。
- 辅助窗格:提供与主窗格相关的其他背景信息或工具。
- 额外窗格(可选):用于在需要时显示补充内容。
该框架会根据窗口大小进行自适应:
- 在大窗口中,主窗格和辅助窗格会并排显示。
在小窗口中,一次只能显示一个窗格,并会随着用户浏览而切换。
图 1. 辅助窗格布局。
添加依赖项
NavigableSupportingPaneScaffold
是 Material 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'
- 自适应:低级构建块,例如
HingeInfo
和Posture
- adaptive-layout:
ListDetailPaneScaffold
和SupportingPaneScaffold
等自适应布局 - adaptive-navigation:用于在窗格内和窗格之间导航的 Compose 可组合项,以及默认支持导航的自适应布局,例如
NavigableListDetailPaneScaffold
和NavigableSupportingPaneScaffold
确保您的项目包含 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
,它是一个表示架构状态的接口、ThreePaneScaffoldValue
和 PaneScaffoldDirective
。
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
。此参数分别接受 PaneScaffoldDirective
和 ThreePaneScaffoldValue
或 ThreePaneScaffoldState
。这种灵活性可让您为窗格间距实现自定义逻辑,并确定应同时显示多少个窗格。您还可以通过添加 ThreePaneScaffoldPredictiveBackHandler
来启用预测性返回支持。
添加了 ThreePaneScaffoldPredictiveBackHandler
附加接受 Scaffold 导航器实例并指定 backBehavior
的预测性返回处理程序。这决定了在返回导航期间如何从返回堆栈中弹出目的地。然后,将 scaffoldDirective
和 scaffoldState
传递给 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() }, )