TaskList 元件介紹
TaskList 用於在頁面中顯示 Spark Tasks。它以 Task Designer 中儲存的 Filter 為基礎資料範圍，並重複使用任務權限、任務欄位、任務詳細資料和執行階段查詢能力。
閱讀本指南後，你可以完成以下設定：
- 使用 Task Filter 限定 TaskList 的基礎任務範圍
- 使用 Task Form 呈現進階查詢條件
- 新增系統欄位和自訂欄位作為表格欄
- 調整欄位順序、標題、寬度、排序、固定方式和超長省略
- 將 Task Key 或其他欄位設定為任務連結
- 控制篩選列、欄位設定和分頁大小
- 驗證 Assignee、Select、Date 和 DateTime 欄位的查詢行為
1. TaskList 的適用情境
TaskList 適合以下情境：
- 在業務頁面中顯示某一種或一組任務
- 使用 TQL 固定任務類型、狀態、步驟或其他基礎條件
- 讓使用者繼續依標題、負責人、時間和自訂欄位縮小結果範圍
- 按一下清單中的任務編號或業務欄位開啟任務詳細資料
- 在同一個表格中同時顯示任務系統欄位和業務自訂欄位
TaskList、DataList 和 ProTable 的資料邊界不同：
| 元件 | 主要資料 | 查詢定義 | 典型用途 |
|---|---|---|---|
| TaskList | Spark Tasks | Task Filter + 執行階段條件 | 任務清單、審核清單、業務待辦頁面 |
| DataList | Business Object | DQL + 模型篩選 | 訂單、客戶、裝置等物件資料 |
| ProTable | Custom URL 或模型資料來源 | HTTP 請求參數或模型查詢 | 第三方 API、彙總資料、自訂分頁通訊協定 |
如果頁面顯示的不是任務，請改用 DataList 或 ProTable。
2. 先備知識與範例來源
TaskList 顯示的是 Spark Tasks 流程任務。開始設定前，建議先完成以下內容：
- 閱讀 Process Designer 介紹，瞭解 Task Type、欄位、表單、步驟、工作流程和權限方案之間的關係。
- 完成 快速開始：採購審核工作流程，確認可以在 DEV 中建立並處理 Purchase Request。
本文直接重複使用該快速開始中已經設定完成的採購審核工作流程，不再重複建立流程資產。快速開始提供以下基礎內容：
| 資產 | 範例設定 |
|---|---|
| Task Type | PURCHASE / Purchase Request |
| Workflow | Purchase Approval |
| 自訂欄位 | 包括 Finance Review Result、Department Review Result、Required Date 等採購申請欄位 |
| 執行階段資料 | 已在 DEV 中建立並完成不同審核分支驗證的 Purchase Request |
在這些流程資產之上，本文繼續設定 TaskList 所需的清單資產和頁面屬性：
| 資產或屬性 | 本文設定 |
|---|---|
| Task Filter | All Purchase Request Tasks |
| Filter TQL | taskType = "PURCHASE" ORDER BY createdAt DESC |
| Query Form | purchaseQueryForm |
| Query Form 欄位 | Assignee、Finance Review Result、Department Review Result、Required Date |
| Columns | Task Key、Title、Task Type、Current Step、Created At |
| Page Size | 20 |
| Show Filter Bar | 開啟 |
| Show Column Settings | 開啟 |
3. 使用前準備
3.1 準備任務資產
在目前應用程式和設計版本中確認以下資產已經儲存：
- Task Type 已設定工作流程、權限方案和所需表單。
- 需要顯示或查詢的自訂欄位已經新增到 Task Type。
- 至少存在一個可供 TaskList 參照的 Task Filter。
- 如需進階查詢，已經建立專用 Task Form。
TaskList 的候選項目依目前 App + Version 載入。在 DEV 中，可以使用目前開發版本已經儲存的任務資產；在 TEST 或 PROD 驗證時，應確認對應版本已經發佈到目標環境。
3.2 建立 Task Filter
進入 Task Designer → Data & Permission → Filters，建立 Filter 並儲存 TQL。本文範例為：
taskType = "PURCHASE" ORDER BY createdAt DESC
輸入 taskType = 後，從目前版本的候選清單中選擇 Purchase Request。TQL 使用穩定的 Task Type Key PURCHASE，請勿以顯示名稱取代 Key。
Task Filter 決定 TaskList 的基礎任務範圍。執行階段使用者不能移除這段 TQL，任務權限也不會因 Filter 條件而放寬。有關語法和權限邊界，請閱讀 Filter 與 TQL。
3.3 建立 Query Form
Query Form 是選用設定，不是顯示查詢區域的先決條件。只要開啟 Show Filter Bar，即使未選擇 Query Form，TaskList 也會提供預設查詢條件：
- 第一列快速條件：Title、Status、Task Type、Created At。
- 按一下 More 後的進階條件：Current Step、SLA Status、Assignee、Updated At。
Search 保持為查詢區域右側的主要按鈕，More 和 Reset 使用緊接其後的圖示按鈕，欄位設定位於操作群組末尾。設定 Query Form 後，TaskList 會保留上述預設條件，並在 More 區域繼續附加 Query Form 中的自訂欄位；Query Form 不會取代預設條件。關閉 Show Filter Bar 時，預設條件和 Query Form 都不會顯示。
需要增加業務自訂查詢欄位時，建議建立專用 Task Form，只放置使用者真正需要的查詢欄位，不要直接複製包含大量唯讀詳細資料或附件的業務表單。
本文使用 purchaseQueryForm：
| 欄位 | 欄位類型 | 執行階段查詢控制項 |
|---|---|---|
| Assignee | User | 使用者選擇器 |
| Finance Review Result | Select | Approved / Rejected 下拉選單 |
| Department Review Result | Select | Approved / Rejected 下拉選單 |
| Required Date | Date | 日期範圍選擇器 |
Query Form 不要求繫結某一個 Task Type 才能用於查詢。欄位定義仍來自目前應用程式和版本，因此應確保表單參照的欄位未被刪除。
4. 新增並設定 TaskList
- 開啟目標頁面並進入 Page Designer。
- 在左側元件面板展開 Task 群組。
- 將 TaskList 拖入頁面中可接收的容器。
- 選取 TaskList，在屬性面板完成基礎設定。
TaskList 的主要屬性如下：
| 屬性 | 是否必填 | 說明 |
|---|---|---|
| Task Filter | 是 | 選擇 Task Designer 中儲存的 Filter，執行階段依 Filter Key 載入 TQL |
| Query Form | 否 | 在預設查詢條件之外，將 Task Form 欄位附加到 More 區域 |
| Columns | 否 | 依順序設定系統欄位和自訂欄位；未設定時使用任務清單預設欄位 |
| Show Filter Bar | 否 | 控制是否顯示整個查詢區域 |
| Show Column Settings | 否 | 控制右上角欄位設定入口；只有顯示篩選列時才會出現 |
| Page Size | 否 | 預設每頁數量，預設值為 20，允許範圍為 1 到 200 |
本文範例選擇：
Task Filter: All Purchase Request Tasks
Query Form: purchaseQueryForm
Show Filter Bar: On
Show Column Settings: On
Page Size: 20
關閉 Show Filter Bar 後，快速條件、More、Search、Reset 和欄位設定入口都會隱藏，頁面只保留任務表格與分頁器。適合查詢範圍固定、不允許使用者繼續調整條件的頁面。
5. 設定 Columns
5.1 新增和排序欄位
展開 TaskList 下的 Columns，按一下 Add。每次新增都會在左側樹狀結構中產生一筆 Task Column，而不是把所有欄位儲存在一個多選控制項中。
對每一個欄位設定：
- 在 Task Field 中選擇系統欄位或自訂欄位。
- 檢查自動帶出的 Column Title，依頁面語意修改標題。
- 開啟 Advanced，依需要設定寬度、任務連結、排序、固定欄位和超長省略。
- 在左側樹狀結構中拖曳 Task Column，調整執行階段欄位順序。
設計畫布中的表頭應隨 Task Field、Column Title 和欄位順序同步變化。Column Title 已經承擔欄位顯示名稱，不需要再維護額外的 Display Name。
5.2 可選欄位
Task Field 候選項目分為兩組：
- System Fields：Task Key、Title、Task Type、Status、Current Step、Assignee、Creator、Created At、Updated At、SLA 等。
- Custom Fields：目前應用程式和版本中定義的任務欄位，例如 Amount、Category、Required Date、Department Review Result。
自訂欄位即使不是獨立 Worklist 的預設可見欄位，也可以由頁面作者明確新增到 TaskList。
5.3 欄位進階屬性
| 屬性 | 說明 |
|---|---|
| Width | 欄寬，單位為像素 |
| Task Link | 按一下該欄位值時開啟任務 |
| Enable Sorting | 允許使用者依該欄位排序，僅對後端支援排序的欄位生效 |
| Fixed Column | 將欄位固定在表格左側或右側 |
| Show Ellipsis | 內容超出欄寬時顯示省略效果 |
SLA 狀態欄顯示時固定在第一欄。建議緊接其後放置 Task Key 和 Title，並為這兩欄開啟 Task Link。也可以把其他業務欄位設為任務連結；如果明確關閉某一欄的 Task Link，該欄會以一般文字顯示。
執行階段欄位設定只能暫時隱藏已設定的欄位或調整排序，不會反向修改 Page Designer 中的欄位結構和順序。
6. 執行階段查詢區域
6.1 快速查詢條件
開啟 Show Filter Bar 後，TaskList 頂端預設顯示以下快速條件：
- Title
- Status
- Task Type
- Created At
這些控制項使用 Placeholder 說明用途，不重複顯示可見 Label。Search、More、Reset 和欄位設定依此順序位於右側；More 和 Reset 使用帶有 Tooltip 的圖示按鈕。查詢條件與操作群組在同一水平線上垂直置中。
按一下 More 後會顯示：
- Current Step
- SLA Status
- Assignee
- Updated At
- Query Form 中設定的欄位
內建進階條件同樣使用 Placeholder，不重複顯示 Label。Query Form 欄位保留表單本身的欄位標題和版面配置，方便區分自訂業務條件。
6.2 Search 和 Reset
- Search：讀取目前快速條件和 Query Form 值，從第一頁重新查詢。
- More 圖示：展開或收合進階條件和 Query Form。
- Reset 圖示：清除執行階段條件和 Query Form 值，然後重新查詢。
- Enter：在 Title 輸入框中按 Enter 可以直接執行查詢。
空值不會參與查詢。Task Filter、快速條件和 Query Form 條件依 AND 關係疊加，租戶、應用程式、環境和任務瀏覽權限始終由後端強制執行。
例如，本文基礎 Filter 已限定 taskType = "PURCHASE"。再選擇 Assignee 和 Required Date 後，結果必須同時符合：
Purchase Request 基礎範圍
AND 目前 Assignee
AND Required Date 範圍
AND 目前使用者可瀏覽任務權限
7. Query Form 欄位的查詢規則
查詢控制項由欄位的實際類型決定，不依欄位名稱猜測控制項類型。
| 欄位類型 | 查詢行為 |
|---|---|
| Text、Textarea、Rich Text、Markdown | 包含比對 |
| Select、Radio、Switch | 等值比對 |
| 多選欄位 | 集合比對，即 IN |
| Number | 等值比對 |
| User、Assignee | 使用者選擇器提交使用者 ID，介面持續顯示使用者名稱 |
| Department | 部門樹狀選擇器 |
| Date、DateTime | Range 方式查詢，開始和結束邊界都包含在結果中 |
| Attachment | 查詢模式不呈現 |
隱藏欄位不會進入 Query Form。業務表單中的 Required 屬性在查詢模式下不會強制使用者輸入；未填寫的條件會被忽略。
7.1 Assignee
Assignee 從目前應用程式可用的使用者目錄中搜尋。選擇使用者後，查詢請求使用穩定的使用者 ID，但控制項仍顯示使用者名稱或帳號，不應在按一下 Search 後變成純數字 ID。
7.2 Select
Select 必須依欄位設定的 Options 呈現。本文的 Department Review Result 和 Finance Review Result 都顯示：
Approved
Rejected
欄位名稱中包含 Department 不會把 Select 誤判為部門選擇器。只有實際類型為 Department 的欄位才顯示部門樹狀結構。
7.3 Date 和 DateTime
Query Form 中的 Date 和 DateTime 使用範圍選擇器：
- 只選擇開始值：查詢
field >= start - 只選擇結束值：查詢
field <= end - 同時選擇：查詢
field >= start AND field <= end
兩個邊界都是包含關係。Date 欄位依日期值查詢；DateTime 欄位允許選擇具體時間。
8. 開啟任務和頁面互動
開啟某一欄的 Task Link 後，按一下該欄位值會開啟任務。
- 未設定
onTaskClick：在新的瀏覽器分頁中開啟 Spark 標準任務詳細資料頁，目前業務頁面保持不變。 - 已設定
onTaskClick：在目前頁面執行 Page Designer 中的互動，並提供task和record內容；此時不會自動開啟標準詳細資料頁。 - Ctrl / Command 按一下等瀏覽器輔助按鍵操作：保留連結的瀏覽器預設行為。
需要由頁面中的其他按鈕重新整理 TaskList 時，可以對該元件呼叫 Component API：
reloadTable
9. 範例驗證清單
在本文範例的 DEV 執行頁面中依序驗證：
- 清單只傳回 Filter 範圍內的 Purchase Request。
- 表頭依 Task Key、Title、Task Type、Current Step、Created At 的順序顯示。
- Task Key 和 Title 都顯示為連結，按一下後在新的瀏覽器分頁中開啟對應任務。
- 展開 More 後可以看到
purchaseQueryForm的四個欄位。 - 選擇 Assignee 並按一下 Search 後，控制項仍顯示使用者名稱。
- Department Review Result 顯示 Approved / Rejected，而不是部門樹狀結構。
- Required Date 選擇不包含任務日期的區間時，該任務會從結果中排除。
- 按一下 Reset 後恢復到 Task Filter 的基礎結果。
- 欄位設定可以暫時隱藏欄位並切換可排序欄位。
- 表格最後一筆資料後直接銜接帶分隔線的分頁區域，沒有無意義的大塊空白。