Upload 上傳

選擇並上傳檔案。使用 Element Plus 的 el-upload。

設計準則

• 限制先講:格式、單檔大小、數量上限一律寫在 tip 裡,不要讓使用者上傳完才報錯;accept 同步限制選檔視窗
• 形式跟著場景:表單裡的一個欄位用按鈕式;上傳是頁面主要任務(匯入名單)用拖曳區;單張圖(頭像、logo)用就地預覽;多張圖用照片牆(picture-card);圖片和檔名都重要用縮圖列表(picture)
• 上傳中要有進度回饋;失敗的檔案要能看到原因、可重試或移除
• 已上傳清單顯示檔名、可刪除;刪除已成功上傳的檔案要二次確認
• 按鈕文字寫明上傳什麼:「上傳名單」「上傳商品圖」,不要只寫「上傳」

失敗狀態是本站補的

Element Plus 會在失敗的項目加上 .is-fail,但沒有附任何樣式 —— 失敗的檔案和正常檔案長得一模一樣。 本站在 @accuhit/ui 統一補上:檔名與圖示轉紅、✕ 常駐(不必 hover 才移得掉)、檔名後補一句「上傳失敗,請重新上傳」; 照片牆(picture-card)失敗時不會渲染檔名區,改以紅色邊框標示。引入 @accuhit/ui 即生效,RD 不需要另外設定。

具體原因(檔案過大、格式不符)DOM 裡沒有可放的節點,請在 on-error 用 ElMessage 補上。 重試就是重新選檔;若需要每列各自重試,用 #file slot 自己畫一列。

必填驗證的紅框也是本站補的

el-form-item 的 .is-error 樣式是一份逐一列舉的白名單(el-input__wrapper、el-textarea__inner、 el-select__wrapper、el-input-tag__wrapper、el-input-otp__input-field), 上傳的兩種框 —— el-upload-dragger(拖曳區)和 el-upload--picture-card(照片牆加號磚)—— 都不在裡面。 所以「附件必填」驗證沒過時,EP 只會在下方顯示訊息,上傳區本身完全沒有變化。

本站把這兩個框在 .is-error 時一併轉紅,權重也壓過 :hover 與 .is-dragover —— 驗證沒過期間滑過或拖曳,邊框都維持紅色。RD 照常用 <el-form-item prop="files" required> 即可。

按鈕式沒有可以上色的框,錯誤就只有 .el-form-item__error 那一行訊息 —— 這是刻意不動的,把主要按鈕染紅會和「這是主要動作」互相打架。 照片牆的錯誤訊息屬於整面牆,不屬於單一磚(EP 的 error 在 form-item content 最下方)。

基本用法

按鈕式 + tip 寫清楚限制;檔案清單顯示在按鈕下方,滑過可刪除:

loading

上傳頭像

單張圖、就地預覽、不顯示檔案清單:選完直接把圖顯示在上傳框裡(頭像、品牌 logo):

loading

照片牆

多張圖用 picture-card:縮圖排成格狀,滑過可預覽、可刪除,點預覽開大圖(可實際操作):

loading

圖片列表縮略圖

list-type="picture":清單形式但帶縮圖,適合「圖片 + 檔名都重要」的場景:

loading

拖曳上傳

匯入流程這類「上傳為主要任務」的頁面,拖曳區目標大、也支援點擊:

loading

手動上傳

「選擇檔案」和「開始上傳」分成兩步:適合上傳前要再確認的場景 (匯入名單這類影響大的操作,選錯檔還來得及換)。選檔按鈕用次要樣式、真正送出的按鈕才是主要按鈕:

loading

Do / Don't

✅ Do	❌ Don't
tip 寫明格式/大小/數量	上傳完才報「檔案太大」
「上傳名單」寫明上傳什麼	只寫「上傳」
圖片用照片牆給預覽	圖片上傳只看到檔名
失敗可重試、可移除	失敗就卡死整個表單
失敗原因用 on-error 跳訊息說清楚	只把整列變紅,使用者不知道為什麼

給工程師

完整 API 見 Element Plus Upload 文件。 本站規範優先於 EP 文件中的視覺建議。示範用 :auto-upload="false",實際串接後端由工程決定。