格線重疊的 UI 元素

四星級評等圖示

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

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

最佳做法

  • 宣告順序: Grid 遵循標準 zIndex 排序,依據 Grid 區塊內的宣告順序。在 Grid 內容區塊中,較晚宣告的項目會顯示在較早宣告的項目上方。
  • 明確控制 z-index:如需明確控制或覆寫重疊元素的預設繪製順序,請使用 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)
}

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

結果

UI 元素會以可預測的方式疊加在 2D 格狀結構中。只要採用標準宣告順序,就能避免複雜的巢狀容器,同時維持簡潔、回應式的版面配置程式碼。

顯示重疊 UI 元素的格狀版面配置
圖 1. Compose 格線中的 UI 元素重疊。