建構輔助窗格版面配置

輔助窗格標準版面配置會將使用者的注意力集中在應用程式的主要內容上，同時顯示相關的輔助內容。舉例來說，主內容窗格可能會顯示近期電影的相關資訊，而輔助窗格則會列出其他主題相似的電影，或由相同導演或主演演員執導的電影。如要進一步瞭解輔助窗格標準版面配置，請參閱 Material 3 支援窗格指南。

實作輔助窗格

SupportingPaneScaffold 最多可包含三個窗格：主要窗格、輔助窗格和選用的額外窗格。架構會處理所有計算作業，將視窗空間分配給三個窗格。在大型螢幕上，結構體會顯示主要窗格，並在側邊顯示輔助窗格。在小螢幕上，結構體會顯示主要或輔助窗格全螢幕畫面。

圖 1. 支援窗格版面配置。

新增依附元件

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