使用 Grid 和 mediaQuery 調整桌上型電腦的姿勢版面配置

4 星級評等圖示

摺疊式裝置的桌面模式會將單一螢幕分割成兩個功能性顯示區域,並以實體摺疊處 (或轉軸) 分隔。在桌面模式下,您可以將應用程式的主要內容 (例如影片播放器或遊戲畫面) 放在上半部,並將互動元素 (例如媒體遙控器或控制台) 放在下半部。

摺疊式裝置處於桌面模式,上螢幕顯示影片內容,下螢幕顯示播放控制項。
圖 1. 桌面模式會將內容和互動控制項分開,分別顯示在實體摺疊線的兩側。

最佳做法

如要在應用程式中新增桌面模式支援,請使用 Grid API 定義兩列一欄的版面配置,並套用桌面模式視窗姿勢媒體查詢。

  • 被動偵測桌面模式:使用 mediaQuery 可組合函式觀察裝置狀態。當裝置折疊成桌面模式 (windowPosture == Posture.Tabletop) 時,系統會動態調整版面配置,不必重新啟動活動或處理複雜的生命週期。
  • 使用 Grid 建立版面配置結構:在桌面模式下,使用 Grid API (2 rows、1 column) 將主要視覺內容清楚分隔到不需捲動位置的頂端列,並將互動式控制項分隔到需捲動位置的底部列。
  • 運用疊加層的隱含 Z 索引:在標準 (非桌面) 狀態下,將多個區域 ID 指派給同一個儲存格,即可在播放器上疊加控制項。Grid 會自動按照宣告順序,由後往前算繪項目。
  • 提供流暢的轉換效果:確保在標準全螢幕版面配置和桌面模式之間轉換時,狀態和捲動位置能保持不變。

要件

  • Grid:自動調整版面配置容器,可讓您將項目置於可設定的列和欄中,適合將內容分割至不同的螢幕區域。
  • mediaQuery:Jetpack Compose API,用於直接在可組合函式中查詢應用程式目前的視窗姿勢、大小類別和硬體特性。

步驟

使用 mediaQuery() 查詢裝置狀態。裝置處於桌面模式時,請將應用程式內容排列成兩列一欄的垂直格線,確保主要內容位於頂端,控制項則位於底部,方便使用者操作。

1. 定義免手持模式的格線設定

在可組合函式中,使用列舉定義版面配置區域 ID,並為預設和桌面模式設定 GridConfigurationScope 區塊。

在 defaultConfig 中,這兩個區域會指派給同一個儲存格 (row = 1, column = 1)。Grid 會使用隱含的 Z 索引,在版面配置中較晚宣告的可組合項會顯示在較早宣告的可組合項上方,讓控制器可以疊加在播放器上,而不需要額外的容器巢狀結構 (詳情請參閱「使用 Grid 疊加 UI 元素」)。

enum class VideoPlayerArea { Player, Controller }

object PlayerGridConfig {
    // Default: Single area layout with overlay (controls on top of player)
    val defaultConfig: GridConfigurationScope.() -> Unit = {
        row(1f)
        column(1f)
        area(areaId = VideoPlayerArea.Player, row = 1, column = 1)
        area(areaId = VideoPlayerArea.Controller, row = 1, column = 1)
    }

    // Tabletop: Two rows splitting content across the fold
    val tabletopConfig: GridConfigurationScope.() -> Unit = {
        row(0.5f)
        row(0.5f)
        column(1f)
        area(areaId = VideoPlayerArea.Player, row = 1, column = 1) // Top half above fold
        area(areaId = VideoPlayerArea.Controller, row = 2, column = 1) // Bottom half below fold
    }
}

2. 偵測桌面模式並套用至 Grid

使用 mediaQuery 根據 windowPosture 選取有效設定,將 config 傳遞至 Grid,並將可組合內容繫結至區域 ID。在 VideoPlayerArea.Controller 之前宣告 VideoPlayerArea.Player,可確保兩者在 defaultConfig 中共用同一個儲存格時,控制項會顯示在播放器上方:

val config = mediaQuery {
    when (windowPosture) {
        Posture.Tabletop -> PlayerGridConfig.tabletopConfig
        else -> PlayerGridConfig.defaultConfig
    }
}

Grid(config = config) {
    Box(
        modifier = Modifier
            .gridItem(areaId = VideoPlayerArea.Player)
    ) {
        // VideoPlayerContent
    }

    Box(
        modifier = Modifier
            .gridItem(areaId = VideoPlayerArea.Controller)
    ) {
        // PlaybackControlsContent
    }
}

結果

結合 mediaQuery 和 Grid 後,應用程式就能動態偵測摺疊式裝置何時部分摺疊成桌面模式,並自動將 UI 調整為兩個功能顯示區域,並以摺疊處分隔。

其他資源