构建辅助窗格布局

辅助窗格规范布局可将用户的注意力集中在应用的主要内容上，同时显示相关的辅助内容。例如，主内容窗格可能会显示近期一部电影的相关信息，而辅助窗格则会显示具有类似主题或同一导演或主演的其他电影的列表。如需详细了解辅助窗格规范布局，请参阅 Material 3 辅助窗格准则。

实现辅助窗格

SupportingPaneScaffold 最多包含三个窗格：主窗格、辅助窗格和可选的额外窗格。基架会处理将窗口空间分配给三个窗格的所有计算。在大屏幕上，基架会显示主窗格，其侧面是辅助窗格。在小屏幕上，基架会全屏显示主窗格或辅助窗格。

图 1. 辅助窗格布局。

添加依赖项

注意 ：自适应导航套件库目前处于 Alpha 版阶段，可能会发生变化。

SupportingPaneScaffold 是 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 - 自适应布局，例如 SupportingPaneScaffold
• adaptive-navigation - 用于在窗格内和窗格之间导航的可组合项

创建导航器和基架

在小窗口中，一次只能显示一个窗格，因此请使用 ThreePaneScaffoldNavigator 在窗格之间来回移动。使用 rememberSupportingPaneScaffoldNavigator 创建导航器实例。如需处理返回手势，请使用 BackHandler，用于检查 canNavigateBack() 并调用 navigateBack()：

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}
SampleSupportingPaneScaffold.kt

基架需要一个 PaneScaffoldDirective（用于控制如何拆分屏幕以及要使用的间距）和一个 ThreePaneScaffoldValue（它用于提供窗格的当前状态，例如它们是展开还是隐藏）。对于默认行为，请分别使用导航器的 scaffoldDirective 和 scaffoldValue：

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = { /*...*/ },
    supportingPane = { /*...*/ },
)
SampleSupportingPaneScaffold.kt

主窗格和辅助窗格是包含您的内容的可组合项。使用 AnimatedPane 在导航期间应用默认窗格动画。使用基架值检查辅助窗格是否处于隐藏状态；如果是，则显示调用 navigateTo(ThreePaneScaffoldRole.Secondary) 的按钮以显示辅助窗格。

下面是该基架的完整实现：

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            // Main pane content
            if (navigator.scaffoldValue[SupportingPaneScaffoldRole.Supporting] == PaneAdaptedValue.Hidden) {
                Button(
                    modifier = Modifier.wrapContentSize(),
                    onClick = {
                        navigator.navigateTo(SupportingPaneScaffoldRole.Supporting)
                    }
                ) {
                    Text("Show supporting pane")
                }
            } else {
                Text("Supporting pane is shown")
            }
        }
    },
    supportingPane = {
        AnimatedPane(modifier = Modifier.safeContentPadding()) {
            // Supporting pane content
            Text("Supporting pane")
        }
    },
)
SampleSupportingPaneScaffold.kt

提取窗格可组合项

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

@Composable
fun ThreePaneScaffoldScope.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")
        }
    }
}

@Composable
fun ThreePaneScaffoldScope.SupportingPane(
    modifier: Modifier = Modifier,
) {
    AnimatedPane(modifier = modifier.safeContentPadding()) {
        // Supporting pane content
        Text("This is the supporting pane")
    }
}
SampleSupportingPaneScaffold.kt

将窗格提取到可组合项中可简化 SupportingPaneScaffold 的使用（将以下内容与上一部分中基架的完整实现进行比较）：

val navigator = rememberSupportingPaneScaffoldNavigator()

BackHandler(navigator.canNavigateBack()) {
    navigator.navigateBack()
}

SupportingPaneScaffold(
    directive = navigator.scaffoldDirective,
    value = navigator.scaffoldValue,
    mainPane = {
        MainPane(
            shouldShowSupportingPaneButton = navigator.scaffoldValue.secondary == PaneAdaptedValue.Hidden,
            onNavigateToSupportingPane = { navigator.navigateTo(ThreePaneScaffoldRole.Secondary) }
        )
    },
    supportingPane = { SupportingPane() },
)
SampleSupportingPaneScaffold.kt