格線重疊的 UI 元素

Jetpack Compose Grid API 專為結構性二維螢幕版面配置而設計。與針對大型資料集最佳化的延遲格線不同，Grid 可讓您使用軌道 (資料列和資料欄)、間距和格線區域，定義固定或回應式版面配置結構。您可以使用 Modifier.gridItem 將項目放入這個結構中，明確控管格狀容器中的定位和跨度。

如果 UI 需要在同一個格線區域中顯示多個項目，或是重疊區域 (例如徽章重疊、狀態指標或分層卡片)，則座標模糊可能會導致版面配置行為無法預測。管理重疊元件的深度，而不必使用複雜的 Box 巢狀結構或手動座標偏移，對於維護乾淨易讀的版面配置程式碼至關重要。

最佳做法

• 宣告順序： Grid 遵循標準 zIndex 排序方式，以 Grid 區塊內的宣告順序為準。在 Grid 內容區塊中稍後宣告的項目，會顯示在先前宣告的項目上方。
• 明確的 z 索引控制項：如要明確控制或覆寫重疊元素的預設繪製順序，請使用 Modifier.zIndex。
• 具名區域與項目重疊：使用 Grid 和具名區域定義版面配置結構，但如果重疊在邏輯上與該格線儲存格相關聯，請將複雜的重疊邏輯保留在特定 gridItem 內。
• 重疊的刻意跨度：重疊時，請確保 rowSpan 和 columnSpan 參數是刻意為重疊元素設定，以控制遮蔽的基礎內容量。

要件

• Grid：結構性二維版面配置容器
• GridConfigurationScope.area：範圍函式，用於定義格線軌道中的具名區域和重疊區域
• Modifier.gridItem：修飾符，用於在格線軌道中放置可組合函式並跨越這些函式，或將函式放入具名的格線區域
• Modifier.zIndex：用於明確控制繪圖和圖層高度順序的修飾符

步驟

設定格線版面配置和具名區域，將基礎層內容放置在目標格線座標內，並將重疊元素放在共用格線儲存格或重疊區域中。

1. 定義格線設定

建立 Grid 可組合函式設定，指定列和欄軌，以及跨儲存格的具名區域，定義重疊區域：

enum class Areas { BASE, OVERLAY }

val gridConfig: GridConfigurationScope.() -> Unit = {
    repeat(3) {
        column(GridTrackSize.Fixed(100.dp))
    }
    row(GridTrackSize.Fixed(100.dp))

    area(areaId = Areas.BASE, row = 1, column = 1, columnSpan = 2)
    // Define a named area spanning multiple columns that overlaps other cells
    area(areaId = Areas.OVERLAY, row = 1, column = 2, columnSpan = 2)
}
GridByExamples.kt

2. 放置基本內容並宣告疊加層

使用 Modifier.gridItem 將基本可組合函式放在格線儲存格中。Grid 會根據組合順序遵循標準 zIndex 排序，因此在 Grid 區塊中稍後宣告的項目會繪製在較早項目的頂端。在同一個儲存格或重疊區域中放置疊加層時，請在基本元素後宣告疊加層可組合項，或參照具名區域。如要明確控制或覆寫這項預設繪圖順序，可以使用 Modifier.zIndex。

Grid(
    config = gridConfig,
) {
    // Base Layer
    TextCard("BASE", Modifier.gridItem(areaId = Areas.BASE))
    // Overlay Layer
    TextCard(
        "OVERLAY",
        Modifier.gridItem(areaId = Areas.OVERLAY),
        color = Color(0xDD4B608D)
    )
}
GridByExamples.kt

結果

UI 元素會以可預測的方式疊加在 2D 格線結構中。只要依賴標準宣告順序，就能避免複雜的巢狀容器，同時維持乾淨的彈性版面配置程式碼。