跳至主要内容

Grid 控制項介紹

Grid 用來把頁面劃分成穩定、可重複使用的響應式區域。它適合儀表板、詳細頁、主要內容加側欄，以及等寬卡片群組。每個區域仍可放入 Form、Common Panel、ProTable、DataList 或其他內容控制項。

1. 範例：活動營運看板​

Spark Sample 的 Grid 頁面展示三種常用配置：

列欄跨度用途
Equal Thirds8 + 8 + 8三個等寬指標卡
Main and Sidebar16 + 8活動詳細資料與發佈檢查側欄
Equal Halves12 + 12時程與受眾兩個等寬區域
Screen
└── Grid
    ├── Row → 8/24 + 8/24 + 8/24
    ├── Row → 16/24 + 8/24
    └── Row → 12/24 + 12/24

此範例使用欄位初始值，只示範版面配置，不需要後端 Sample API。若要載入真實資料，可在欄中放入 Data Form、DataList 或 ProTable。

2. 三層結構​

  1. Grid：控制所有列的水平排列與垂直對齊。
  2. Grid Row：代表一列，控制欄間距與換行後的列間距。
  3. Grid Column：占用 24 欄中的若干格，並承載業務控制項。

請依照以下順序配置：

Grid → Grid Row → Grid Column → Common Panel / Form / 資料控制項

3. 新增 Grid​

  1. 在 Page Designer 開啟頁面並選取 Screen。
  2. 在 Screen 的 Grid 子元素區域新增 Grid。
  3. 在 Grid 的 Rows 新增 Grid Row。
  4. 在 Row 的 Columns 新增一個或多個 Grid Column。
  5. 設定每個欄的 Span Columns。
  6. 在欄的 Panels 加入 Common Panel、Form、ProTable 或其他控制項。
  7. 儲存後同時檢查設計預覽與執行頁面。

新建 Grid Column 預設占 24/24，加入後會立即以整列寬度顯示。

4. 24 欄格線​

Span Columns 的有效範圍是 1～24。

版面數值
單欄整列24
兩個等寬區域12 + 12
三個等寬區域8 + 8 + 8
四個等寬區域6 + 6 + 6 + 6
主要內容加側欄16 + 8 或 18 + 6

同一列的跨度總和通常應為 24。小於 24 時會留下空白，位置由 Horizontal Alignment 決定；大於 24 時，後面的欄會自動換行。Column Gap 是視覺間距，不需要從 24 扣除。

5. 間距與對齊​

選取 Grid Row 可設定：

屬性範圍說明
Column Gap0～64相鄰欄之間的水平間距，單位為像素
Row Gap0～64欄換行後，上下兩排的垂直間距，單位為像素

選取外層 Grid 可設定：

  • Horizontal Alignment：start、end、center、space-between、space-around
  • Vertical Alignment：top、middle、bottom

當跨度總和等於 24 時沒有額外水平空間，幾種水平排列看起來可能相同。可暫時改成 8 + 8 比較差異。垂直對齊只有在同列各欄高度不同時才明顯。

6. 欄最小高度​

Minimum Column Height 可設定 0～1200 像素：

  • 0：高度隨內容自動成長，這是最安全的預設值。
  • 大於 0：保留指定的最低高度；內容更多時仍會繼續長高，不會被裁切。

同列卡片需要視覺平衡時，可設定相同的最小高度。此屬性不是最大高度。

7. 在欄中組織內容​

  • Common Panel + Form：有標題的詳細卡片或指標卡。
  • Form：不需要額外卡片標題的輸入區。
  • ProTable / DataList：主要列表、篩選區或側欄。
  • Tree：通常應使用 Screen 的 Navigation Tree 區域；只有作為一般內容時才放入 Grid Column。

Grid 決定外層區域寬度。Form 的 Controls Per Row 與 Form Grid Split 會在該區域內重新計算，不是以整個頁面的 24 欄計算。

8. 重現範例​

  1. 新增 Grid，設定 start 與 top。
  2. 新增 Column Gap、Row Gap 都為 16 的 Row。
  3. 建立 8 + 8 + 8 三欄，最小高度皆為 156。
  4. 建立 16 + 8 一列，最小高度為 228。
  5. 建立 12 + 12 一列，最小高度為 176。
  6. 每欄放入 Common Panel 與唯讀 Form。
  7. 儲存並縮窄瀏覽器，確認行動版會依設定順序堆疊。

9. 響應式行為​

PC 寬度下依照 24 欄跨度顯示。手機或窄螢幕下，各欄會依配置順序改成單欄堆疊，避免 Form 和卡片被擠得過窄。Page JSON 與 Span Columns 不會改變，畫面變寬後會恢復原配置。

10. 後端與互動​

Grid 是純版面控制項，本身不會發出請求。只有欄內資料控制項或 Interaction 需要業務資料時，才需要 Java 後端。頁面請求會自動帶上環境與渲染模式；請參閱頁面請求內容與後端除錯。

互動應設定在真正執行動作的按鈕、欄位、卡片或資料控制項上，不要用 Grid Row 或 Grid Column 代替業務控制項。

11. 常見問題​

  • 欄自動換行：檢查 Span Columns 總和是否超過 24。
  • Horizontal Alignment 沒有差異：用 8 + 8 留出空間後再比較。
  • Vertical Alignment 沒有差異：使用高度不同的兩個欄。
  • Form 標籤比例不正確：先確定 Grid Column 寬度，再設定 Form 內部分欄。
  • 設計預覽與執行頁面不同：先儲存頁面，並確認使用目前的 versionId。
最後於 更新