建構輔助窗格版面配置

輔助窗格標準版面配置會將使用者註意力集中在應用程式的主要部分 同時顯示相關的輔助內容。舉例來說 內容窗格可能會顯示關於最新電影的資訊 窗格會顯示有類似或相同主題的其他電影清單 導演或演員進一步瞭解輔助窗格 標準版面配置,請參閱 Material 3 輔助窗格指南

實作輔助窗格

SupportingPaneScaffold 最多包含三個 窗格:主要窗格、輔助窗格和選用的額外窗格。鷹架 會處理所有計算作業,將視窗空間分配給三個窗格。啟用 在大螢幕上, Scaffold 會顯示主要窗格,而輔助窗格開啟 。在小螢幕上,鷹架會顯示主要或輔助元件 全螢幕窗格。

佔據大部分顯示畫面的主要內容,旁邊有補充內容。
圖 1. 支援窗格版面配置。

新增依附元件

SupportingPaneScaffoldMaterial 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'
  • Adaptive - 低階建構模塊,例如 HingeInfoPosture
  • 自動調整版面配置 — 自動調整式版面配置,例如 SupportingPaneScaffold
  • 自動調整導覽 - 可供瀏覽和瀏覽的可組合函式 窗格之間的

建立導覽器和 Scaffold

在小型視窗中,一次只會顯示一個窗格,因此請使用 移入和移出檔案的 ThreePaneScaffoldNavigator 窗格。使用以下程式碼建立導覽器的執行個體: rememberSupportingPaneScaffoldNavigator。 如要處理返回手勢,請使用 BackHandlercanNavigateBack() 和呼叫 navigateBack()

val navigator = rememberSupportingPaneScaffoldNavigator()

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

Scaffold 需要 PaneScaffoldDirective, 控制如何分割畫面、要使用多少間距,以及 ThreePaneScaffoldValue,可提供 窗格的狀態 (例如是否展開或隱藏)。預設值 行為,請使用導覽器的 scaffoldDirectivescaffoldValue 分別為:

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

主要窗格和輔助窗格是包含內容的可組合項。使用 AnimatedPane,可在以下期間套用預設窗格動畫 導覽。使用 Scaffold 值檢查輔助窗格是否 隱藏;如果有,請顯示會呼叫 navigateTo(ThreePaneScaffoldRole.Secondary) 以顯示 輔助窗格

以下是 Scaffold 的完整導入方式:

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")
        }
    },
)

擷取窗格可組合函式

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")
    }
}

將窗格擷取到可組合函式中,可簡化 SupportingPaneScaffold (將以下項目與完整導入程序比較 上一節所述的 Sscaffold):

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() },
)