跳至主要内容

Collapse

Collapse 用於把相關內容整理成可展開、可收合的區域。你可以手動維護固定面板，也可以從模型或後端 API 取得記錄，再用同一個項目範本重複產生面板。

1. 選擇內容模式​

模式適用情境內容來源
Static面板數量和結構固定新增並編排 CollapsePanel
Data Source面板代表同一類型的記錄一個 Data Source 與一個 Item Template

既有頁面 JSON 沒有 Content Mode 時，屬性面板會自動顯示 Static，Runtime 也會以 Static 運作，不需要遷移。

本手冊使用三個互補範例。下方截圖和設定步驟已包含重現所需資訊，不要求讀者存取 Spark Sample 應用程式：

  • Onboarding Checklist：明確設定 Content Mode = Static，四個面板分別承載不同的唯讀表單，用來說明靜態結構、預設展開和元件函數。
  • Frequently Asked Questions：設定 Content Mode = Data Source，從 /spark/api/sample/collapse/faqs 讀取記錄，並透過 FAQ Item Template 動態產生面板，用來說明 Test、欄位映射、分頁、Current Record 和開發態預覽資料。
  • Support Answers with Custom Content：重用同一資料來源，並在每個動態面板中重複顯示頁面 Content，用來說明共享內容與 record.* 綁定。

2. 靜態模式​

  1. 從 Containers 將 Collapse 拖入頁面。
  2. 保持 Content Mode = Static。
  3. 在 Collapse Panels 中新增項目並拖曳排序。
  4. 設定 Title、Description、Icon、預設展開、Disabled 和 Trigger Area。
  5. 把 Form、Panel 或其他內容放入面板。

外層可設定 Single Panel Mode、Show Border、Transparent Style、Size 和 Arrow Position。Trigger Area 建議使用 Header；此時整列標題區域（包括右側空白處）都可點擊展開或收合。若選擇 Icon，則只有箭頭可以觸發。Disabled 面板在 Design Mode 中仍可選取和編輯。

3. 資料驅動模式​

3.1 設定資料來源​

  1. 選擇 Content Mode = Data Source。
  2. 指定 id 或 code 等 Row Unique Key。每筆記錄都必須存在且唯一。
  3. 設定 Items Per Request 和 Empty State Text。
  4. 設定模型或 Custom URL，以及 URL、Method、Rows Path、Total Path、Record Fields。
  5. 按一下 Test。Test 與 Design Preview、Runtime 使用相同的請求和回應解析，也會檢查唯一鍵缺漏或重複。

建議回應：

{
  "success": true,
  "data": {
    "total": 6,
    "current": 1,
    "pageSize": 4,
    "records": [{
      "id": "invite-team",
      "category": "Getting started",
      "question": "When should I invite the wider team?",
      "answer": "Invite the team after access rules are ready.",
      "disabled": false,
      "defaultExpanded": true
    }]
  }
}

Rows Path 使用 data.records，Total Path 使用 data.total。

3.2 選擇 Item Template​

操作方式和 CardSet 一致：按一下 Item Template 的編輯按鈕，在範本庫中選擇範本，再於同一個對話框設定欄位參數。

在 Content 中設定標題、說明、內文、分類或徽標；在 Behavior 中視需要對應 Icon、Visible、Disabled 和 Default Expanded。三種範本共用同一套行為規則。

範本適用情境主要對應
FAQ說明中心Title、Answer、Category、Answer Format
Record Summary業務記錄Title、Description、Content、Badge
Custom Content自訂版面標題與行為欄位，以及頁面 Content 引用

Live Preview 可以切換 Preview Record 或重新載入真實預覽資料。Save 才會儲存草稿；Cancel、關閉和 Escape 都不會修改目前範本。

3.3 使用 Content 編排自訂內容​

Content 是頁面內可重複使用的內容資源，不是 Form，也不是藏在 Collapse 裡的子畫布。Page Resources 分為 Popups 和 Contents。開啟 Content 後會從畫布右側滑出寬版設計抽屜，並保留左側元件庫與右側屬性面板。可按標題列關閉按鈕、點擊抽屜外區域、按 Back to page，或按 Escape 返回。

Custom Content 可選擇既有 Content，或使用 Create Content、Edit Content、Unlink Content。解除關聯只移除目前 Collapse 的引用。同一 Content 可被多處共用，修改會同步套用到所有引用；仍被引用的 Content 不能刪除。子控制項不需要參數對應，可直接讀取 record.*。舊 Item Template panels 會在首次載入或儲存時自動提升為 Content。

3.4 設計預覽與 Runtime​

  • Design Preview 與 Runtime 使用同一個渲染器。
  • 預覽只請求一頁；沒有真實資料時顯示明確標記的 Sample Record。
  • 初次載入顯示骨架；空白與錯誤狀態清楚呈現，錯誤可 Retry。
  • Runtime 有更多資料時顯示 Load more，且同時只執行一個載入請求。
  • 重新載入後保留仍存在的展開鍵。
  • Runtime 略過無效鍵；Test 將其顯示為設定錯誤。

4. 互動​

Static 支援 Collapse onChange 與 CollapsePanel onClick；Data Source 支援 Collapse onChange 與 Item Template onClick。

切換動態項目時，Spark 先寫入 Current Record，再執行 Item Template onClick，最後執行 Collapse onChange。動作可以讀取 record.* 與：

collapse.activeKeys
collapse.expandedCount
collapse.changedKey
collapse.changedIndex
collapse.changedNumber
collapse.changedRecord
collapse.expanded
collapse.accordion
collapse.contentMode

Toast 範例：FAQ: [[record.question]]。

5. 元件函數​

函數行為
expandAll展開可用項目；Single Panel Mode 只保留第一項
collapseAll收合全部項目
resetPanels還原預設展開狀態
reloadCollapse重新載入資料並協調展開鍵
setCollapseData(data)用先前動作提供的陣列取代資料

6. 請求內容​

Test、Design Preview、Runtime 都會自動傳送：

X-Spark-Page-Environment: DEV | TEST | PROD
X-Spark-Page-Render-Mode: DESIGN_PREVIEW | RUNTIME

請勿手動新增。另請參閱頁面請求內容與後端除錯。Spark Sample 使用 /spark/api/sample/collapse/faqs，後端以 SparkPageRequestHeaders.resolve(environment, renderMode) 解析內容，並可在 DESIGN_PREVIEW 回傳確定的開發資料。

7. 重現範例​

7.1 靜態開通檢查清單​

  1. 新增 Collapse，保持 Static，並關閉 Single Panel Mode。
  2. 新增四個 CollapsePanel，分別放入不同的唯讀 Form。
  3. 第一項開啟 Expanded by Default。
  4. 新增三個按鈕，分別呼叫 expandAll、collapseAll、resetPanels。

7.2 動態 FAQ​

  1. 選擇 Data Source、Single Panel Mode 和 Transparent Style。
  2. Row Unique Key 填 id，Items Per Request 設為 4。
  3. 使用 /spark/api/sample/collapse/faqs、POST、data.records、data.total。
  4. 按 Test，再選擇 FAQ 範本。
  5. 對應 question、answer、category、disabled、defaultExpanded。
  6. 在 onChange 加入 FAQ: [[record.question]]。

7.3 Custom Content 記錄詳情​

  1. 新增另一個 Data Source Collapse，並以相同回應路徑重用 /spark/api/sample/collapse/faqs。
  2. 選擇 Custom Content，把 Title 對應到 question，Description 對應到 summary。
  3. 按 Create Content，將資源命名為 Support answer content，並在寬版設計抽屜中編輯。
  4. 在 Content 中新增唯讀 Form，設定 Controls Per Row 為 2、Label 為 4、Content 為 8。
  5. 新增綁定 [[record.category]]、[[record.environment]]、[[record.renderMode]] 的唯讀 Field。
  6. 新增獨占整列、綁定 [[record.answer]] 的唯讀 TextArea。
  7. 切換 Preview Record，確認標題和 Form 內容都會同步更新。

8. 疑難排解​

Test 提示 Row Unique Key 重複​

使用穩定的業務 ID，不要使用列索引。分頁、排序和重新載入後，該鍵仍必須保持不變。

Design Preview 顯示 Sample Record​

資料來源尚未設定、無法存取或請求失敗。請透過 Test 檢查 URL、回應路徑與後端請求。

修改範本後預覽沒有變化​

儲存範本對話框，並確認 Record Fields 或實際回應中存在對應欄位。

在 Content 中讀取目前記錄​

在子控制項值或 Interaction 運算式中使用 record.*，不要寫死從預覽記錄複製的值。

Load more 後原本展開的項目消失​

確認同一業務記錄持續使用相同的 Row Unique Key。Spark 只能保留仍然穩定的鍵。

9. 設計建議​

  • 一組通常保持 3～8 個可見面板；更多項目應提供分類或搜尋。
  • FAQ 和長說明優先使用 Single Panel Mode；需要對照時可允許多個面板展開。
  • Title 應能獨立說明展開後的內容，Description 不要重複標題。
  • Disabled 必須搭配可讀說明，不能只依賴灰色樣式。
  • 後端必須提供穩定唯一鍵，並保持分頁回應結構一致。
  • 動態欄位映射應在 Record Fields 中明確宣告，方便選擇、測試和維護。
  • 不要嵌套多層 Collapse；請改用小標題、Tab 或獨立頁面。
最後於 更新