CardSet 控制項介紹

CardSet 用於將相同資料來源中的多筆記錄渲染為響應式卡片集合。它適合商品目錄、應用程式清單、資產目錄和知識條目等需要快速瀏覽實體摘要的頁面。

閱讀本手冊後，你可以完成以下配置：

使用 Business Object 或 Custom URL 載入數據
為 Custom URL 定義或匯入可重複使用的 Response Fields
從可視模板庫選擇 Standard、Cover 或 Compact 卡片
將返回記錄欄位對應到標題、描述、圖片、狀態和元數據
配置 Fixed Filters、Query Fields 和 Query Form
設定桌面、平板和行動端列數
在 Pagination 與 Load More 之間選擇翻頁方式
使用 Current Record 配置整卡點擊和卡片操作

CardSet 是資料驅動的重複集合，不用於手動逐條維護靜態卡片。表格型資料請使用 DataList 或 ProTable。

1. 使用前準備

1.1 選擇資料來源

CardSet 支援以下資料來源：

資料來源	適用場景
Model Data Source	資料來自 Spark Business Object，並需要 DQL、模型欄位或 Query Form
Custom URL	資料來自應用程式 API、外部服務或自訂聚合介面

使用 Model Data Source 前，應先在 Objects Designer 中完成 Business Object、欄位、查詢和 QUERY 場景 Data Form。

Custom URL 應提供可分頁的記錄集合。推薦回應格式：

{
  "success": true,
  "data": {
    "current": 1,
    "pageSize": 12,
    "records": [],
    "total": 0
  }
}

1.2 本文範例

本文使用 Spark Sample 商品目錄介面：

POST https://spark.hiforce.ai/spark/api/sample/cardset/products

介面返回 23 條英文商品數據，包含：

字段	用途
`id`	記錄唯一鍵
`code`	卡片輔助標題
`name`	卡片標題
`description`	卡片描述
`imageUrl`	封面圖片
`status`	狀態標籤
`category`	商品分類
`price`	商品價格
`stock`	目前庫存
`updatedAt`	更新時間

2. 新增 CardSet

開啟目標頁面並進入 Page Designer。
在左側元件面板展開 Containers。
將 CardSet 拖曳到頁面容器。
選取 CardSet，在右側屬性面板先配置 Data Source，再配置 Card Template。
為控制項設定穩定名稱，例如 productCardSet。

CardSet 不會再要求先猜測一個 Java CardTemplate 類別名稱。模板外觀和欄位映射統一在視覺配置對話方塊中完成。

3. 設定 Data Source

3.1 Custom URL 範例

在 Data Source 中選擇 Custom URL，配置：

屬性	值
URL	`/spark/api/sample/cardset/products`
Request Method	`POST`
Rows Path	`data.records`
Total Path	`data.total`
Current Page Path	`data.current`
Page Size Path	`data.pageSize`

Custom URL 本身不能像 Business Object 一樣提供模型元數據，因此也需要在同一個 Data Source 對話框中配置 Response Fields。本文範例配置如下：

Field Path	Label	Data Type
`id`	ID	`NUMBER`
`code`	Code	`TEXT`
`name`	Name	`TEXT`
`description`	Description	`TEXT`
`imageUrl`	Image URL	`URL`
`status`	Status	`TEXT`
`category`	Category	`TEXT`
`price`	價格	`NUMBER`
`stock`	Stock	`NUMBER`
`updatedAt`	Updated At	`DATETIME`

Response Fields 有兩種配置方式：

點選加號手工新增 Field Path、Label 和 Data Type。
填寫 URL、請求方式和回應路徑後，點選 Test & Import 從真實回應中匯入。

Test & Import 最多讀取 20 筆記錄，並合併其中出現的欄位。巢狀物件會產生 owner.name 形式的點路徑；陣列只登記為 ARRAY，不會產生具有陣列下標的不穩定路徑。導入會保留已經手動修改的 Label、Data Type 和順序，只追加新字段，不會自動刪除舊字段。介面傳回空數組或請求失敗時，現有配置不會變更。

Response Fields 是儲存到頁面配置中的欄位契約，不保存介面回傳的範例值。開啟 Data Source 對話方塊也不會自動呼叫後台。

CardSet 會傳送目前頁、每頁數量、固定篩選、快速查詢和 Query Form 值。 POST 請求範例：

{
  "current": 1,
  "pageSize": 12,
  "conditions": [
    {"field": "status", "operator": "EQ", "value": "ACTIVE"}
  ],
  "queryFormValues": {}
}

Custom URL 請求也會自動攜帶統一的頁面上下文 Header：

Header	枚舉值	說明
`X-Spark-Page-Environment`	`DEV`、`TEST`、`PROD`	目前頁面環境；設計器內預覽固定使用 `DEV`
`X-Spark-Page-Render-Mode`	`DESIGN_PREVIEW`、`RUNTIME`	Page Designer、設計器開啟的 Preview 與真實記錄預覽為 `DESIGN_PREVIEW`；一般運作頁為 `RUNTIME`

例如，開發環境運行頁會傳送 DEV + RUNTIME，Card Template 對話方塊中的真實記錄預覽會傳送 DEV + DESIGN_PREVIEW。這是所有 Page Designer 和 Page Runtime 後端請求的統一規範，不限於 CardSet。後端應以穩定枚舉處理，不要透過 Referer 推斷場景；跨域 Custom URL 還需要在 CORS 的 Access-Control-Allow-Headers 中允許這兩個 Header。

3.2 Model Data Source

選擇 Model Data Source 後：

選擇 Business Object。
按需選擇 DQL Query。
在 Request Parameters 中綁定 DQL 參數。
Card Template 的欄位下拉清單會直接使用目前 Business Object 的字段元資料。

Model Data Source 的分頁、DQL 參數和查詢條件由 Spark 執行時期統一處理。

4. 選擇 Card Template

點選 Card Template 右側的編輯圖標，開啟寬版配置對話框。頂部模板庫會直接顯示三個縮略預覽：

模板	適用場景
Standard	通用業務實體，標題、說明、狀態與元資料結構均衡
Cover	商品、媒體和資產目錄，突出 16:9 封面圖片
Compact	運維或管理工作台，減少描述區域並提高資訊密度

選擇模板後，右側預覽會立即變化，不需要儲存或進入運行頁面才能判斷模板外觀。範本庫下方按主題分為 Content、 Query 和 Layout & paging 三個 Tab；右側預覽始終保留，Desktop、Tablet、Mobile 用於切換預覽寬度。

配置區域和預覽區域可以獨立捲動。 Content 中的 Card fields、Metadata 和 Status tones 都使用獨立分組；Query fields 與 Fixed filters 也使用帶有列標題的配置表。配置較多時，應在目前 Tab 內繼續向下捲動，底部配置不會被對話方塊截斷。

5. 設定字段映射

進入 Content Tab 配置 Card fields、Metadata 和 Status Tones。每個 Card field 右側都會標記它所在的卡片區域，例如 Heading、Corner、Above title 或 Body；Title 帶有紅色必填標記。

本文 Cover 範例使用以下映射：

卡片區域	字段
Eyebrow Field	`code`
Title Field	`name`
Description Field	`description`
Image Field	`imageUrl`
Status Field	`status`

Title Field 是最重要的識別字段，應始終配置。其他欄位為空時，對應區域不會保留空白佔位。

5.1 欄位來源與自訂路徑

字段下拉清單由 Data Source 提供：

Model Data Source 使用 Business Object 欄位元資料。
Custom URL 使用已經儲存的 Response Fields。

選擇欄位時會顯示 Label (path)，可依標籤或路徑搜尋。確實需要綁定未登記的動態欄位時，選擇 Add custom path 後手動填寫。常規欄位應優先加入 Response Fields，避免不同 CardSet 或 ProTable 重複維護字串路徑。

嵌套物件使用點路徑，例如：

owner.name
pricing.amount

Title Field 是保存 CardSet 的必填項目。其他可選映射為空時，對應卡片區域不會渲染。

5.2 刷新真實預覽

資料來源和欄位對應儲存後，點選右側 Live Preview 標題旁的刷新圖示。設計器會以 pageSize=1 讀取一筆記錄，並傳送 X-Spark-Page-Environment: DEV 與 X-Spark-Page-Render-Mode: DESIGN_PREVIEW。

重新整理只更新右側卡片展示值，不會新增、刪除或修改 Response Fields。請求失敗時繼續保留目前預覽和欄位配置。

5.3 配置 Metadata

Metadata 用於展示價格、庫存、負責人或更新時間等短資訊。點選 Add row 新增一行。設定表會固定顯示 Label、Field 和 Format 欄位標題：

屬性	說明
Label	卡片中顯示的短標籤，例如 `Price`
Field Path	資料字段，例如 `price`
Format	`TEXT`、`NUMBER`、`CURRENCY`、`DATE` 或 `DATETIME`

商品範例建議添加：

Label	Field	Format
Category	`category`	`TEXT`
價格	`price`	`CURRENCY`
Stock	`stock`	`NUMBER`

5.4 設定 Status Tones

Status Tones 是可選的狀態色映射。設定表使用 When status equals 和 Show tone 兩列，例如將 ACTIVE 對應為 SUCCESS、DRAFT 對應為 WARNING。未配置對應時，CardSet 會對常見狀態值使用內建語意色，並對未知值使用 MUTED。

6. 設定查詢

進入 Query Tab 配置 Query Form、Show Filter Bar、Query Fields 和 Fixed Filters。 Query Form 與 Show Filter Bar 位於頂部工具條，查詢欄位和固定條件分別位於下方分組。

6.1 Query Fields

Query Fields 顯示在查詢區域首行。設定表固定顯示 Field、Label、Operator 和 Type 欄位標題。

選擇欄位後，設計器會以 Response Field 或 Business Object 欄位的 Label 和 Data Type 預先填入查詢配置；Label 和查詢類型仍可繼續調整。 OBJECT 和 ARRAY 不會出現在快速查詢欄位候選中。

推薦商品範例：

Field	Label	Operator	Type
`name`	Search products	`LIKE`	`TEXT`
`category`	Category	`EQ`	`TEXT`
`status`	Status	`EQ`	`TEXT`

日期和時間類型會自動渲染為 Range Picker。 Search、More 和 Reset 總是位於查詢列右側。

6.2 Fixed Filters

Fixed Filters 每次查詢都生效，但不會顯示給運行使用者。例如，只展示有效商品：

Field	Operator	Value
`status`	`EQ`	`ACTIVE`

關閉 Show Filter Bar 只會隱藏使用者查詢區域，不會停用 Fixed Filters。

6.3 Query Form

Query Form 是可選的進階查詢表單。在下拉清單中選擇 QUERY 場景的 Data Form 後，執行時點選 More 展開表單。 CardSet 使用 Model Data Source 時，下拉清單會優先顯示目前 Business Object 的查詢表單；使用 Custom URL 時會顯示應用程式中可用的 QUERY 表單。

Model Data Source 應選擇目前 Business Object 的 QUERY Data Form。
Custom URL 會把 queryFormValues 原樣傳送給後端，由介面解釋欄位意義。

7. 設定佈局和分頁

進入 Layout & paging Tab 設定響應式列數、間距、分頁和行唯一鍵。 Responsive columns 分組會以 Desktop、Tablet 和 Mobile 三個裝置示意圖即時顯示目前列數；Paging & data 分組集中維護 Paging Mode、Page Size 和 Row Unique Key。

推薦預設值：

屬性	預設值
Desktop Columns	`4`
Tablet Columns	`2`
Mobile Columns	`1`
Spacing	`DEFAULT`
Page Size	`12`
Paging Mode	`PAGINATION`
Row Unique Key	`id`

Paging Mode 支援：

PAGINATION：顯示總數和頁碼，適合管理頁面。
LOAD_MORE：追加下一頁紀錄，適合瀏覽型目錄。
NONE：只展示介面目前回傳的數據，不顯示翻頁控制項。

使用右側 Desktop、Tablet、Mobile 分段控制項檢查單卡寬度；實際執行時間列數會依頁面寬度自動切換。

8. 設定互動

CardSet 支援兩層互動：

整卡 onClick。
卡片底部操作項目的 onClick。

8.1 設定卡片操作項

Card Actions 不在 Card Template 設定對話方塊中。 請先在畫布中選取 CardSet，再到右側屬性面板的 Card Actions 子元素區域完成設定：

點選 Add child element，新增一個 CardAction。
在新增表單中填寫 Title 並確認。設計器會自動選取剛建立的 CardAction。
在 CardAction 的屬性面板中透過統一 Icon 選擇器選用系統圖示或上傳自訂圖片。
點選 Interaction，為 CardAction 新增 onClick 事件和後續動作。

若要修改現有操作項目，請先在 Card Actions 清單中點選對應的列。使用清單左側的拖曳控點可以調整順序；執行時會依此順序在卡片底部顯示前 3 個操作項目。點擊操作項目會阻止事件向上傳遞，因此不會同時觸發整卡點擊。

8.2 設定整卡點擊

重新選取 CardSet 本身，再點選 Interaction 並設定 CardSet 的 onClick。設定整卡點擊後，卡片支援 Tab 聚焦，以及使用 Enter 或 Space 鍵觸發。

8.3 讀取目前記錄

無論觸發整卡點擊或操作項目點擊，CardSet 都會先將被點擊卡片對應的資料寫入執行階段上下文中的 record。在 Interaction 編輯器中，此資料來源顯示為 Current Record；後續動作可以讀取：

record.id
record.code
record.name

這些欄位值來自本次點擊的卡片資料，不是設計時寫死的固定值。Custom URL 應先設定 Response Fields；Model Data Source 則應提供 Business Object 欄位中繼資料，讓 Interaction 編輯器可以顯示正確的 Current Record 欄位候選。

8.4 例：在抽屜中展示卡片詳情

下面以 View product 操作項目為例，在同一個 onClick 中依序配置兩個動作：

新增 Set component value 動作，並命名為 Fill product details。將 record.id、record.code、record.name 等 Current Record 欄位分別寫入詳情抽屜中的對應表單控制項。
新增 Open/close dialog/drawer 動作，並命名為 Open product details。將 Target component 設為 Product details (Drawer)，同時開啟 Open target。

務必先寫入表單值，再開啟抽屜。Interaction 會依照 Action tree 從上到下執行；如果順序相反，抽屜開啟時可能短暫顯示上一筆資料或空值。

設定完成後，點擊卡片底部的 View product，抽屜便會顯示目前卡片對應的商品詳情。

9. Sample 後端實現

範例程式碼位於：

spark-sample/src/main/java/hiforce/spark/sample/cardset/

商品查詢重複使用 ProTable 範例的分頁和條件處理，CardSet 控制器負責公開專用 URL；封面圖片由本機 PNG 端點生成，不依賴外部圖片服務。

本機啟動後可驗證：

curl -X POST 'http://localhost:18080/spark/api/sample/cardset/products' \
  -H 'Content-Type: application/json' \
  -H 'Accept-Language: zh-CN' \
  -H 'X-Spark-Page-Environment: DEV' \
  -H 'X-Spark-Page-Render-Mode: DESIGN_PREVIEW' \
  -d '{"current":1,"pageSize":12,"conditions":[{"field":"status","operator":"EQ","value":"ACTIVE"}]}'

範例回應中的 data.requestContext 會回顯規範化後的 environment 和 renderMode，以便於驗證後端確實接收並處理了頁面上下文。生產業務介面可以使用該上下文選擇資料或執行審計，不要求回顯。

10. 常見問題

設計器只有模板名稱，沒有外觀

確認使用的是新的 Card Template 編輯圖示。模板應以三個縮圖展示；如果仍出現舊 ResourceInfoCard 等類名，請刷新設計器元資料並重新添加 CardSet。

運行時沒有卡片

依序檢查：

Data Source 是否已儲存。
Rows Path 是否指向數組。
Title Field 是否存在於記錄中。
瀏覽器 Network 中請求是否成功。
Fixed Filters 是否排除了所有記錄。

Custom URL 的欄位下拉清單為空

開啟 Data Source，檢查是否已經儲存 Response Fields。可以手工添加，也可以確認 URL 和 Rows Path 正確後使用 Test & Import。刷新 Live Preview 不負責產生欄位目錄。

Test & Import 沒有導入字段

依序檢查 URL、請求方式、Rows Path 和瀏覽器 Network。介面必須在當前條件下至少傳回一筆記錄；合法但為空的結果不會產生字段，此時應手動維護 Response Fields。

圖片不顯示

Image Field 必須傳回瀏覽器可存取的圖片 URL。相對 URL 應以目前 Spark 網域為基準，並確認介面沒有傳回 HTML 登入頁。

查詢後結果沒有變化

Custom URL 後端必須處理 conditions 和 queryFormValues。 CardSet 只負責傳送查詢語意，不會在瀏覽器中對完整資料集做二次過濾。

1. 使用前準備​

1.1 選擇資料來源​

1.2 本文範例​

2. 新增 CardSet​

3. 設定 Data Source​

3.1 Custom URL 範例​

3.2 Model Data Source​

4. 選擇 Card Template​

5. 設定字段映射​

5.1 欄位來源與自訂路徑​

5.2 刷新真實預覽​

5.3 配置 Metadata​

5.4 設定 Status Tones​

6. 設定查詢​

6.1 Query Fields​

6.2 Fixed Filters​

6.3 Query Form​

7. 設定佈局和分頁​

8. 設定互動​

8.1 設定卡片操作項​

8.2 設定整卡點擊​

8.3 讀取目前記錄​

8.4 例：在抽屜中展示卡片詳情​

9. Sample 後端實現​

10. 常見問題​

設計器只有模板名稱，沒有外觀​

運行時沒有卡片​

Custom URL 的欄位下拉清單為空​

Test & Import 沒有導入字段​

圖片不顯示​

查詢後結果沒有變化​

11. 設定檢查清單​