資料表格欄位

一、甚麼是資料表格¶

「資料表格」是一種進階型欄位，可讓表單設計者透過串接外部資料來源（如：API、SQL），在表單中顯示一份即時、動態的資料清單。

此欄位支援依據使用者提供的參數，自動取得對應的資料列，並以表格方式呈現，無論是申請者或簽核者，都能根據權限設定查看表格內容。

這類欄位特別適合資料檢視的場景，並不支援編輯行為，因此使用者僅可檢視內容，無法修改資料表格內的數值或欄位。

場景名稱	說明
查詢外部資料清單	串接外部資料來源(例如:API、SQL)，顯示符合條件的供應商清單、產品清單、客戶訂單紀錄等，讓使用者查閱詳細內容。
結合欄位互動顯示對應資料	可搭配下拉選單、單選、複選等其他欄位，動態指定查詢條件，例如：當使用者選擇某個「供應商名稱」，下方的【資料表格】欄位就會即時載入該供應商的歷史訂單。
顯示數據摘要報表	將系統內部統計資料（如：每月工時統計、已核銷項目清單）透過API呈現在表單中，讓主管一目瞭然。

如下圖所示，在設定 資料表格 前，需要先 建立外部連線設定 與 建立外部資料來源 設定。

你可以在 [欄位元件庫/進階]，拖拉 [資料表格] 至欄位畫布上，根據下方說明設定欄位屬性

開啟 [資料表格] 欄位屬性，點按 [1. 資料來源] 區塊的 [設定] 按鈕，開啟 [選擇資料來源] 視窗
選擇資料來源：你可以選擇到由 [工作流程管理員] 所建立外部資料來源主檔清單，你可以清楚識別SQL類型或API類型的資料來源，且也可以點按按鈕，來檢視外部資料來源主檔內容。
其他設定值：系統將會根據 你所選擇不同的資料來源類型，需要維護不同的設定值。
- A. JSONPath：當選擇的資料來源類型為 [API] 時，需填寫JSONPath以取得JSON數據結構中的值。
- B. 參數來源：根據不同的 [外部資料來源]，有不同的參數清單，你可以指定其參數來源為表單的哪一個欄位。

[外部資料來源] 設定注意事項（分頁參數）

當【資料表格】欄位綁定 外部資料來源（SQL 或 API），且啟用 [Sept3-資料分頁]設定（已設定總筆數資料來源）時，系統在前端查詢資料時，會自動傳入以下兩個參數：

參數名稱	說明
`@目前是第幾頁`	表示使用者目前正在瀏覽第幾頁的資料（從第 1 頁開始）
`@每頁筆數`	表示每一頁希望顯示的筆數（由表格設定控制）

設計表單欄位時所支援的參數來源為

1.支援[一般欄位]、[自訂欄位]：包含單行文字、多行文字、數值、日期、日期時間、單選清單、下拉選單、複選清單、欄位計算、上傳檔案、明細欄位、選擇人員、選擇部門、資料表格。
2.支援文件檢視器、外掛欄位、表單變數。

當你設定好資料來源後，系統會自動抓出資料裡的每一個欄位，你可以針對這些欄位重新命名，讓使用者更容易理解這些資料的意思。
舉例來說，如果資料欄位原本叫做 emp_name，你可以把它改成「員工姓名」，讓畫面看起來更清楚與容易理解；如果你沒有特別修改，系統就會直接使用資料來源裡的原始欄位名稱來顯示。

當資料筆數很多時，一次載入全部資料會影響表單效能，建議啟用分頁功能，能將資料切成一頁一頁顯示，加快載入速度以提升效能與使用者體驗，。
如果要啟用分頁，需進一步設定「總筆數資料來源」：
- 總筆數資料來源：指定 API 或查詢語法中，能回傳總筆數的欄位（例如 totalCount）
- 系統會根據總筆數自動計算頁數，並顯示分頁元件
- 分頁功能支援跳頁、每頁筆數切換等操作
若沒有啟用分頁，將無法自動分頁，且為了避免頁面延遲載入，只會顯示前100筆資料。

完成上述設定後，點選 [預覽] 按鈕，就能立即查看資料表格實際呈現的效果，系統會根據你設定的資料來源即時抓取資料，呈現在表單中，方便你檢查以下內容是否正確：
- 資料是否成功載入
- 欄位名稱是否清楚易懂
- 分頁功能是否如預期運作
透過預覽功能，你可以在正式使用前，快速驗證整體設定，確保表單使用體驗順暢。