跳至主要内容

DataList 控制項介紹

DataList 用於在頁面中顯示和操作 Business Object 資料。它會讀取業務物件的欄位、查詢定義和動作，因此適合訂單、設備、客戶等模型資料清單。

閱讀本手冊後，你可以完成以下設定：

  • 綁定 Business Object 和 DQL Query
  • 使用 FX 將輸入控制項、Page Context 或 URL 參數傳給 DQL
  • 設定欄位、欄位連結、分頁和顯示樣式
  • 使用 Fixed Filters 限定使用者不能移除的基礎資料範圍
  • 使用 Query Fields 設定第一列快速查詢，並使用 Query Form 擴充進階查詢
  • 在工具列按鈕中重新整理 DataList 或取代本機表格資料
  • 將 Business Object Action 設定為資料列操作

DataList 是面向 Business Object 的模型清單，不提供 Custom URL 資料來源。需要直接呼叫任意 HTTP API 時，請使用 ProTable 控制項介紹 中的 Custom URL 資料來源。工作清單不由 DataList 承載，後續將由專用的 TaskList 控制項提供。

1. 使用前準備​

1.1 準備 Business Object​

進入 Spark Designer → Objects Designer，確認目標 Business Object 已經完成以下設定：

  1. 已關聯可用的資料來源和實體資料表。
  2. 需要顯示的欄位允許用於清單顯示。
  3. 需要作為篩選或查詢條件的欄位已設定為可搜尋、可篩選、已建立索引或識別欄位。
  4. 用作資料列唯一識別的欄位穩定且不會重複，通常使用 id。
  5. 如需資料列操作，已在 Business Object 中定義對應的 Object Action。

如果 DataList 的 Fixed Filters 或 Query Fields 候選清單為空，請先檢查 Business Object 欄位是否已設定為可搜尋、可篩選、已建立索引或識別欄位。

如需使用 Query Form 提供進階查詢，還應為同一個 Business Object 建立 Data Form，並在 Usage Scenarios 中啟用 Query。Query Form 是選用資產，不影響 Fixed Filters 和 Query Fields 的使用。

1.2 視需要建立 DQL​

DQL 用於儲存可重複使用的 Business Object 查詢條件。進入：

Objects Designer → Data → Filters

按一下 Add DQL 建立查詢。Query Key 由系統自動產生，不需要手動維護。

例如，依寵物編碼進行選用的模糊查詢：

code LIKE :code

在參數定義中將 code 設定為非必填。執行階段：

  • 輸入參數時，查詢會依編碼進行包含比對。
  • 參數為空時，該條件不會參與查詢。
  • LIKE 參數直接傳入使用者輸入值，不需要手動加入 %。

如果 DQL 參數被設定為必填，DataList 執行查詢時必須提供有效值，否則查詢會失敗。

1.3 確認資料隔離方式​

是否需要租戶欄位由資料模型和資料來源的隔離方式決定：

  • 獨占資料來源或不需要租戶隔離的物件，可以使用資料來源範圍隔離，不必強制新增租戶欄位。
  • 多租戶共用實體資料表時，應在 Business Object 對應中明確設定唯一的租戶欄位。
  • DQL 只負責業務查詢條件，不能覆寫模型層已強制執行的資料隔離條件。

2. 新增 DataList​

  1. 開啟目標頁面並進入 Page Designer。
  2. 在左側控制項面板展開 Data 群組。
  3. 將 DataList 拖曳到頁面中可接受的容器。
  4. 選取 DataList，在右側屬性面板的 Basic 區域完成設定。
  5. 建議為 DataList 設定穩定且容易識別的控制項名稱，例如 petList、orderList。

穩定的控制項名稱方便後續在 FX、按鈕互動和 Component API 中識別目標控制項。

3. 設定模型和 DQL​

3.1 選擇 Model​

在 Model 屬性中選擇 Business Object。選擇後，DataList 會自動取得：

  • 可顯示欄位
  • 可查詢欄位
  • Business Object Actions
  • 可選的 DQL Queries

切換 Model 時，應重新檢查 Columns、Fixed Filters、Query Fields、Query Form、DQL Parameters 和 Row Operations。原模型中的欄位、表單或動作可能不再適用於新模型。

3.2 選擇 DQL Query​

在 DQL Query 中選擇目前 Business Object 已發佈的 DQL。DQL 是選用設定：

  • 未選擇 DQL：DataList 使用模型基礎查詢，並疊加頁面設定的篩選條件。
  • 選擇 DQL：DataList 使用 DQL，並繼續疊加 Fixed Filters、Query Fields 和 Query Form 條件。

DQL、Fixed Filters、Query Fields 和 Query Form 之間以 AND 關係組合。

3.3 設定 DQL Parameters​

選擇包含參數的 DQL 後，DQL Parameters 會列出參數名稱。參數名稱來自 DQL 定義，頁面只需要設定參數值。

按一下參數右側的 FX，在 Value Resolver 中新增變數並選擇資料來源。常用來源如下：

來源適用情境
Component Value讀取 Input、Select、Radio、Date Picker、Uploader 等頁面控制項的目前值
Page Context讀取 Page Context 或業務參數
URL Parameter讀取瀏覽器網址中的查詢參數
Current Row在資料列內容中讀取目前記錄欄位
Static Value傳入固定文字、數字或布林值

新增變數後，在 Target Value 中參考變數：

[[petCode]]

Range 類型控制項會傳回兩個元素，可分別參考開始值和結束值：

[[queryRange.0]]
[[queryRange.1]]

如果一個參數值需要組合多個變數，也可以在同一個 Target Value 中參考多個變數。參數較多時，DQL Parameters 區域會在限定高度內捲動，不會持續將下方屬性推到很遠的位置。

在 FX 對話方塊中按一下 Add Variable 只會新增一個變數綁定。完成變數來源和 Target Value 設定後，再儲存對話方塊。

4. 設定 Columns​

展開 Columns，選擇需要顯示的 Business Object 欄位。欄位順序就是執行階段表格的顯示順序。

設定建議：

  • 第一欄放置最容易識別記錄的名稱或編碼。
  • 數量、狀態、時間等欄位依業務閱讀順序排列。
  • 避免一次顯示過多低頻欄位；詳細資訊可以透過欄位連結、資料列操作、Dialog 或 Drawer 顯示。
  • 確保 Row Unique Key 對應的值在所有記錄中唯一。

需要按一下某一欄進入詳細資料頁面時，編輯該欄位的連結設定：

  1. 啟用欄位連結。
  2. 在 Target Page 中選擇目標頁面。
  3. 在 Param Name 中填寫目標頁面接收的參數名稱，通常為 id。
  4. 在 Row Field 中選擇目前資料列用於傳遞參數的欄位。

例如，將目前資料列 id 以 id 參數傳給詳細資料頁面，執行階段會形成類似以下導覽參數：

?id=<目前資料列 id>

5. 設定 Pagination​

展開 Pagination 設定預設分頁大小。執行階段 DataList 會將目前頁碼和分頁大小傳給模型查詢。

建議：

  • 一般管理清單使用每頁 10 到 20 筆。
  • 欄位較少、頁面高度充足時可以適度增加。
  • 資料量較大時，不要透過超大分頁一次載入全部記錄。

按一下查詢按鈕呼叫 reloadTable 時，DataList 會從第一頁重新查詢，避免保留在已經不存在的後續頁碼。

6. 設定固定篩選和查詢區域​

DataList 將不可見的資料範圍限制與使用者可操作的查詢條件分開設定：

設定執行階段是否可見作用
Fixed Filters否每次查詢都必須符合的固定條件
Query Fields是顯示在篩選列第一列的快速查詢控制項
Query Form是按一下 More 後顯示的進階查詢表單
Show Filter Bar不適用控制 Query Fields、Query Form 和查詢按鈕是否顯示

DataList 不會像 TaskList 一樣自動提供預設查詢欄位。希望顯示查詢區域時，必須至少設定一個 Query Field 或選擇一個 Query Form，並保持 Show Filter Bar 開啟。

6.1 設定 Fixed Filters​

Fixed Filters 會自動附加到每一次查詢中，執行階段不顯示給使用者，也不能由使用者移除。即使關閉 Show Filter Bar，Fixed Filters 仍然生效。

適合以下情境：

  • 頁面只顯示某一種業務類型的資料
  • 固定排除已封存或已刪除的記錄
  • 根據 Page Context 限定所屬專案、組織或父記錄
  • 根據 URL 參數將清單限定在目前詳細資料記錄下

在 Fixed Filters 中按一下 Add，為每個條件設定 Field、Operator 和 Value。Value 可以直接填寫，也可以按一下 FX，在統一的 Value Resolver 中參考 Page Context、URL Parameter、Component Value 或靜態變數。

Fixed Filters 支援以下常用運算子：

運算子含義值範例
EQ等於OPEN
NEQ不等於DELETED
LIKE包含PET-01
GE大於等於100
GT大於100
LE小於等於500
LT小於500
BETWEEN區間2026-07-01,2026-07-31
IN屬於集合OPEN,PROCESSING
NOT_IN不屬於集合DELETED,CLOSED

IN、NOT_IN 使用半形逗號分隔多個值；BETWEEN 使用「開始值,結束值」。空值不會產生篩選條件。

6.2 開啟或關閉 Show Filter Bar​

Show Filter Bar 控制整個執行階段查詢區域：

  • 開啟：當 Query Fields 或 Query Form 至少設定一項時，顯示查詢區域。
  • 關閉：隱藏 Query Fields、Query Form、Search、More 和 Reset，但不影響 Fixed Filters。
  • 開啟但未設定 Query Fields 和 Query Form：不顯示空白查詢區域。

查詢範圍固定、頁面不允許使用者繼續縮小結果時，可以關閉 Show Filter Bar。

6.3 設定 Query Fields​

Query Fields 用於定義篩選列第一列的快速查詢控制項。開啟 Query Fields 對話方塊後，按一下 Add，每一列可以設定：

屬性說明
Field從目前 Business Object 的可查詢欄位中選擇，不允許重複選擇同一個欄位
Operator依欄位實際類型提供可用運算子
Placeholder執行階段控制項中的預留位置提示，用於說明查詢用途

使用上移和下移圖示調整查詢欄位順序，使用刪除圖示移除欄位。執行階段控制項依此順序顯示。設定對話方塊中的 Field、Operator 和 Placeholder 標籤位於控制項上方；Operator 為較長的本地化名稱預留完整顯示空間。

Query Fields 依欄位類型呈現控制項並限制運算子：

欄位類型預設運算子可選運算子執行階段控制項
Text、String、TextareaContainsContains、Equals、Not equal文字輸入方塊
Number、Decimal、MoneyEqualsEquals、Not equal、Greater than or equal、Greater than、Less than or equal、Less than數字輸入方塊
Enum、Select、BooleanEqualsEquals、Not equal、In、Not in下拉式選單；In 和 Not in 使用多選
Date、DateTime、TimestampRangeRange日期或日期時間範圍選擇器
User、DepartmentEqualsContains、Equals、Not equal使用者或部門選擇器

執行階段不會重複顯示可見 Label，而是使用 Placeholder 說明欄位用途。日期和日期時間欄位使用 Range：開始值編譯為 GE，結束值編譯為 LE，兩個邊界都包含在結果中。

6.4 建立並選擇 Query Form​

Query Form 是選用設定，用於承載不適合全部放在第一列的進階查詢條件。DataList 參考的是 Objects Designer 中的 Data Form，不是 Task Form。

建立 Query Form：

  1. 進入 Spark Designer → Objects Designer，開啟 Data Forms。
  2. 新增或編輯與 DataList 相同 Business Object 的 Data Form。
  3. 在 Usage Scenarios 中啟用 Query。
  4. 只保留使用者實際需要的可查詢欄位，設定合適的標題、Placeholder 和 Field Width。
  5. 儲存 Data Form，返回 Page Designer，在 DataList 的 Query Form 中選擇該表單。

Query Form 會保留 Data Form 中設定的 24 格線 Field Width。例如，4 個欄位都設定為寬度 6 時，執行階段 More 區域會將它們保持在同一列；寬度依序為 8、8、8 時，一列顯示 3 個欄位。需要換列時，讓目前列寬度合計達到 24，或在 Data Form 中調整欄位順序和寬度。

Query Form 下拉式選單只列出目前 Business Object 可用且支援 Query 情境的 Data Form。如果下拉式選單為空，請檢查 Data Form 是否繫結了同一個 Business Object、是否啟用了 Query 情境，以及目前版本是否已儲存。

按一下執行階段的 More 圖示後，Query Form 顯示在快速查詢列下方。Query Form 欄位遵循以下規則：

  • 只呈現目前 Business Object 中可查詢且未隱藏的欄位。
  • Text 使用包含比對，一般純量欄位使用等值比對。
  • Date、DateTime 和 Timestamp 自動使用 Range 查詢。
  • Query 模式不會強制 Required 驗證，空欄位不參與查詢。
  • Uploader、Multi Row Input、Rich Editor 和 JSON Editor 不會作為查詢控制項呈現。

6.5 Search、More 和 Reset​

  • Search：讀取 Query Fields 和 Query Form 目前值，從第一頁重新查詢。
  • More 圖示：僅在設定 Query Form 時出現，用於展開或收合進階查詢區域。
  • Reset 圖示：清除 Query Fields 和 Query Form 值、收合 More，並從第一頁重新查詢。
  • Enter：在文字型 Query Field 中按 Enter 可以直接查詢。

空值不會參與查詢。最終查詢依以下關係組合：

Business Object 資料權限與隔離條件
AND DQL Query
AND Fixed Filters
AND Query Fields
AND Query Form

7. 設定 Toolbars（選用）​

DataList 支援左側工具列和右側工具列。Toolbars 是清單命令和自訂控制項區域，不是內建查詢列的前置條件。一般欄位查詢優先使用 Query Fields 和 Query Form，不需要在 Toolbar 中重複新增 Search 和 Reset。

以下情境仍適合使用 Toolbars：

  • DQL 參數需要讀取頁面上的自訂 Input、Select 或 Date Picker
  • 提供 Create、Import、Export 等清單命令
  • 放置 Uploader、Dropdown 或業務專用按鈕
  • 透過 Component API 主動重新整理清單或取代本機表格資料

選取 DataList，在屬性面板開啟 Toolbars：

  1. 在 Left Toolbar 群組按一下 Add，選擇 Input、Date Picker、Select 等查詢控制項。
  2. 在 Toolbar 群組按一下 Add，選擇 Button、Dropdown 等操作控制項。
  3. 按一下已新增的控制項，繼續設定 Label、Name 和互動。

常見配置：

  • Left Toolbar：自訂 DQL 參數控制項、Uploader 或其他業務輸入。
  • Toolbar：Create、Import、Export 等操作按鈕。

選取工具列內的控制項後，可繼續在屬性面板中編輯控制項本身。請為查詢控制項設定穩定且不重複的名稱，方便 DQL 參數和按鈕互動參考。

7.1 自訂 DQL 查詢按鈕重新整理 DataList​

只有在使用 Toolbar 控制項驅動 DQL Parameters 等自訂查詢時，才需要手動新增 Search 按鈕並設定按一下互動：

  1. 選取 Search 按鈕，開啟 Interaction editor。
  2. 新增 Component API 動作。
  3. Target Component 選擇目前 DataList，例如 petList。
  4. Function 選擇 reloadTable。
  5. 儲存互動設定。

按一下按鈕時，DQL Parameters 會重新解析目前控制項值，DataList 隨後從第一頁查詢。

7.2 使用 setTableData 更新本機資料​

當按鈕先呼叫自訂 API，並希望直接將 API 傳回陣列顯示在 DataList 中時，可以呼叫：

setTableData(data)

data 應為記錄陣列。此函式會取代目前表格資料，並同步重設分頁狀態。對於標準 Business Object 查詢，優先使用 reloadTable，讓分頁、篩選和總筆數繼續由模型查詢統一處理。

7.3 工具列 Uploader 與 Import 按鈕​

需要先上傳檔案再執行匯入時，可以採用以下結構：

  1. 在工具列中新增 Uploader，並設定穩定名稱，例如 importFiles。
  2. 新增 Import 按鈕。
  3. 在 Import 按鈕的要求參數中，透過 FX 讀取 importFiles 的 Component Value。
  4. 要求成功後，再呼叫 DataList 的 reloadTable。

工具列 Uploader 上傳後的附件透過附件檢視入口管理，不應將完整附件清單直接展開並撐大工具列。表單中的 Uploader 用於表單欄位，其顯示和資料提交方式與工具列情境不同。

8. 設定 Row Operations​

Row Operations 用於對目前記錄執行 Business Object Action，例如編輯、啟用、停用、封存或刪除。

8.1 前置條件​

先在 Business Object 中定義動作及參數。DataList 不應使用前端臨時邏輯取代需要重複使用、驗證或稽核的業務動作。

8.2 新增資料列操作​

  1. 展開 Row Operations。
  2. 按一下新增操作。
  3. 選擇 Business Object Action。
  4. 設定操作名稱和顯示方式。
  5. 將 Action 參數綁定到 Current Row 欄位、靜態值或 Page Context。
  6. 依業務順序調整多個資料列操作的位置。

例如，刪除動作通常會將 Action 的記錄參數綁定到目前資料列 id。

8.3 設定互動​

編輯資料列操作的 Interaction 時，可以設定：

  • 執行前確認提示
  • 開啟 Dialog 或 Drawer
  • 設定 Page Context
  • 呼叫其他控制項函式
  • 執行後重新整理 DataList

危險操作應提供明確的確認步驟。操作完成後，可呼叫目前 DataList 的 reloadTable 顯示最新資料。

9. Advanced 屬性​

DataList 的進階屬性包括：

屬性說明
Enable Row Number顯示資料列序號
Table Size設定 large、middle 或 small 密度
Show Header是否顯示包含欄位標題的表頭列；關閉後只隱藏欄位標題，不隱藏 DataList 標題、Toolbar、查詢區域或資料列
Bordered是否顯示表格框線
Row Unique Key每一資料列的唯一識別欄位，預設使用 id

Row Unique Key 必須穩定且唯一。使用名稱、狀態等可能重複或變更的欄位，會導致選取狀態、更新和轉譯異常。

10. 完整範例：使用 DQL 參數依 Pet Code 模糊查詢​

目標：使用者輸入 Pet Code 後按一下 Search，DataList 依編碼模糊查詢；未輸入時顯示全部可存取記錄。

如果 code 只是一般可查詢欄位，更簡單的方式是在 Query Fields 中新增 code，選擇 Contains 並設定 Placeholder，執行階段直接使用內建 Search 和 Reset。以下範例用於說明需要重複使用參數化 DQL，或 DQL 參數必須來自自訂 Toolbar 控制項時的設定方式。

第一步：建立 DQL​

在 Business Object 的 Data → Filters 中建立 DQL：

code LIKE :code

將 code 參數設定為非必填。

第二步：新增查詢控制項​

選取 DataList，開啟 Toolbars，在 Left Toolbar 群組按一下 Add 並選擇 Input：

  • Label：Pet Code

第三步：綁定 DQL 參數​

  1. 在 DataList 中選擇剛建立的 DQL Query。
  2. 在 DQL Parameters 中找到 code。
  3. 按一下 FX。
  4. 新增變數 petCode。
  5. Source 選擇 Component Value。
  6. Component 選擇 Pet Code 控制項。
  7. 按一下「+」符號新增變數。
[[petCode]]

第四步：設定 Search 按鈕​

為 Search 按鈕新增 Component API 互動：

  • Target Component：目前 DataList
  • Function：reloadTable

第五步：驗證​

  1. 不輸入 Pet Code，按一下 Search，應傳回全部可存取記錄。
  2. 輸入部分編碼，按一下 Search，應傳回編碼包含該文字的記錄。
  3. 清除輸入後再次按一下 Search，應還原為未依編碼篩選的結果。
  4. 如同時設定 Fixed Filters、Query Fields 或 Query Form，確認結果符合所有條件的交集。

11. 儲存、預覽和執行階段驗證​

完成設定後，建議依以下順序驗證：

  1. 儲存頁面。
  2. 開啟 Preview，檢查欄寬、工具列換行、Query Fields、Query Form 格線和分頁。
  3. 驗證 DQL 參數有值和為空兩種情況。
  4. 驗證內建 Search、More、Reset、欄位連結和資料列操作。
  5. 開啟實際 Runtime 頁面，重複關鍵查詢和操作。
  6. 確認 Preview 與 Runtime 的工具列對齊、控制項寬度和互動結果一致。

設計模式只負責設定和近似預覽，資料權限、實際附件上傳、API 呼叫和模型查詢應以 Runtime 驗證結果為準。

12. 常見問題​

12.1 選擇 Model 後沒有可選欄位​

檢查 Business Object 是否已完成資料表對應，欄位是否允許用於清單顯示或查詢，並確認目前版本已經儲存或發佈。

12.2 選擇 DQL 後沒有 DQL Parameters​

DQL 中只有使用 :PARAM_NAME 宣告的參數才會出現在 DQL Parameters。先在 Objects Designer 中驗證並儲存 DQL，再回到頁面重新選擇。

12.3 參數為空時仍然查詢不到資料​

檢查該 DQL 參數是否被設定為必填。希望「空值不篩選」時，應將參數設定為非必填，並確保該參數只控制需要忽略的條件。

12.4 LIKE 查詢沒有結果​

直接傳入使用者輸入文字，不要在 FX 值中加入 %。同時檢查欄位類型是否支援文字包含查詢。

12.5 按一下自訂 Toolbar Search 後資料沒有變化​

依序檢查：

  1. Search 按鈕是否設定了 Component API。
  2. Target Component 是否為正確的 DataList。
  3. Function 是否為 reloadTable。
  4. DQL 參數是否透過 FX 參考了正確控制項。
  5. 控制項名稱是否唯一且未在設定後被修改。

12.6 Query Fields 沒有顯示或沒有生效​

依序檢查：

  1. Show Filter Bar 是否開啟。
  2. Query Fields 中是否已新增至少一個欄位。
  3. Business Object 欄位是否可搜尋、可篩選、已建立索引或為識別欄位。
  4. Operator 是否適用於該欄位類型。
  5. 是否按下內建 Search；空值不會參與查詢。

12.7 Query Form 下拉式選單為空​

檢查 Data Form 是否繫結了與 DataList 相同的 Business Object、Usage Scenarios 是否包含 Query，以及目前開發版本是否已儲存。一般 Create、Edit 或 View Data Form 不會作為 Query Form 候選項目。

12.8 資料列操作清單為空​

先在 Business Object 中定義 Object Action，並確認 DataList 綁定的就是該 Business Object。

12.9 資料列更新後頁面仍顯示舊資料​

在操作成功後的互動鏈中呼叫 DataList 的 reloadTable。如果使用 setTableData，確認傳入的是完整記錄陣列，而不是單筆物件或 API 外層回應物件。

12.10 Preview 正常但 Runtime 回報權限或資料隔離錯誤​

檢查 Runtime 環境中的 Business Object 發佈版本、資料來源權限、使用者資料權限和模型隔離設定。不要透過前端 DQL 參數繞過模型層的資料隔離規則。

13. 設定檢查清單​

  • DataList 已綁定正確的 Business Object
  • Columns 只包含需要顯示的欄位
  • Row Unique Key 穩定且唯一
  • DQL 已驗證，參數必填性符合業務需求
  • DQL Parameters 的 FX 來源和 Target Value 正確
  • Fixed Filters 不會誤排除合法記錄
  • Show Filter Bar 的開啟狀態符合頁面需求
  • Query Fields 的欄位、運算子、Placeholder 和順序正確
  • 如需進階查詢，Query Form 已繫結同一個 Business Object 並啟用 Query 情境
  • 自訂 Toolbar Search 按鈕呼叫了目前 DataList 的 reloadTable
  • 欄位連結傳遞了正確的資料列欄位
  • Row Operations 已綁定正確的 Current Row 參數
  • Preview 與 Runtime 均已驗證

完成以上設定後，DataList 就可以作為 Business Object 清單頁面的穩定資料入口，並與頁面查詢控制項、DQL 和業務動作協同運作。

最後於 更新