Upload 控制項介紹

Upload 上傳一個或多個檔案，並把伺服器回傳的檔案中繼資料交給 Form。它會加入所在 Form 的欄位狀態、驗證與提交範圍。

1. 適用情境

常見用途：

• 附件與證明資料
• 圖片或文件上傳
• 需要格式、數量與大小限制的檔案輸入

2. 新增與設定

1. 把 Upload 加入 Form Section 的 Fields 區域。
2. 設定穩定且唯一的 Field Key / Name，並與後端 DTO 屬性一致。
3. 設定下列元件屬性，再視需要加入 Required、Help Text、Full row 與條件運算式。
4. 在 Design Preview 檢查初始值與版面，並使用 Form Validate / Submit 驗證完整資料流程。

3. 主要屬性

屬性	作用
Multiple	啟用或關閉此行為。
Form Upload / Upload URL	定義可選資料的來源與對應方式。
Component Style	控制欄位在 Design Preview 與 Runtime 中的顯示方式。
Upload Format Filter	限制允許的數量、長度或取值範圍。
Upload Count / Size Limit	限制允許的數量、長度或取值範圍。
Enable Image Cropping	啟用或關閉此行為。

Field Key、Required、Help Text、Full row、Visible When 等通用屬性由 Form 欄位契約提供；本表列出使用 Upload 時最需要注意的設定。

4. 表單值與後端契約

提交值： 檔案中繼資料陣列；具體欄位由上傳介面回應與對應決定，不是瀏覽器二進位物件。

[
  {"id": "file-1024", "name": "evidence.pdf", "url": "/files/file-1024"}
]

範例只說明資料形狀；API 仍應依業務 DTO 驗證型別、範圍與權限。

5. 驗證、條件與互動

所有欄位都可使用 Required、Visible When、Disabled When、Required When、Dependencies 與 Clear When Hidden。條件運算式只控制互動，不取代後端權限與驗證。

元件能力： 支援 setValue；上傳成功指令碼與上傳狀態用於處理伺服器回應。

6. 使用建議

設定建議： 先固定請求與回應 JSON 契約，再設定欄位；對陣列項目、檔案中繼資料與伺服器錯誤路徑做端到端測試。

返回 Form 總覽，瞭解版面、驗證、提交、草稿與後端協定。