SwUploadFile

SwUploadFile 是普通檔案（PDF / 文件 / zip 等非圖非影片）的分片上傳元件，支援點擊選擇和拖曳。它是 useUploader().uploadFile 內功的薄殼 UI：與 SwUploadVideo 複用同一分片端點，但無轉碼二段（不需要 queryFn）——分片成功回應即含可存取 URL， uploadFn 直接 resolve 結果。

圖片用 SwUploadImage、影片用 SwUploadVideo、其餘檔案用本元件。三者同為無樣式元件：自身不渲染任何 UI，透過 uploadFn 注入上傳邏輯、預設 slot 暴露狀態。

基本用法 + 進度

點擊選擇檔案，progress 作用域變數與 progress 事件即時反映分片上傳進度。

加载中...

<script setup lang="ts">
const uploader = useUploader()

function onDone(result: { id: string; value: string }) {
  form.attachment = { id: result.id, url: result.value }
}
</script>

<template>
  <SwUploadFile :upload-fn="uploader.uploadFile" @success="onDone" v-slot="{ open, pending, progress }">
    <SwButton :disabled="pending" @click="open">
      {{ pending ? `上傳中 ${progress}%` : '選擇檔案' }}
    </SwButton>
  </SwUploadFile>
</template>

自訂觸發區（#default slot）

「+ 號上傳卡」：預設 slot 完全接管觸發區 UI，完成後給出可點擊的下載連結。

加载中...

拖曳上傳

透過 slot 的 isOver 高亮拖曳區域。普通檔案不限 mime，任意檔案均可拖入。

加载中...

限定檔案類型（accept）

accept 透傳給檔案選擇框，在選擇層面過濾類型。

加载中...

多檔案上傳

開啟 multiple 後可同時選擇或拖入多個檔案，內部並發上傳並逐條 emit success。

加载中...

進度取捨：單檔案場景 progress 精確；multiple 並發時多檔案進度交錯（後寫覆蓋），進度條以單檔案場景為主要用途。

Props

名稱	類型	必填	預設值	說明
`uploadFn`	`(file: File, options?: FileUploadOptions) => Promise<FileUploadResult>`	✓	—	實際上傳函式，通常傳 `useUploader().uploadFile`
`accept`	`string`		`'*'`	檔案選擇框 accept（普通檔案預設不限類型）
`chunkSize`	`number`		`2097152`（2 MB）	分片大小（位元組），透傳 `uploadFn`
`retries`	`number`		`3`	單片失敗最大重試次數，透傳 `uploadFn`
`concurrency`	`number`		`undefined`	並發分片數，不傳則委託底層預設 6，透傳 `uploadFn`
`multiple`	`boolean`		`false`	是否允許多檔案

類型定義

FileUploadOptions

interface FileUploadOptions {
  chunkSize?: number
  retries?: number
  concurrency?: number
  onProcess?: (result: ChunkProgress) => void
  onBefore?: (file: File) => void
}

FileUploadResult

type FileUploadResult = {
  id: string // 後端檔案 ID（業務側外鍵）
  value: string // 檔案存取 URL（對齊 uploadImage 的 value 語義）
  file_md5: string // 整檔 MD5
}

Events

事件名	載荷類型	說明
`progress`	`pct: number`	上傳進度百分比（0–100）
`success`	`FileUploadResult`	單個檔案上傳成功後觸發（每檔案一條）
`error`	`err: Error`	上傳異常時觸發（非 Error 規整為 Error 實例）

Slots

default（作用域 slot）

作用域變數	類型	說明
`isOver`	`boolean`	檔案正在拖曳懸停區域上方
`pending`	`boolean`	上傳進行中
`progress`	`number`	當前上傳進度（0–100）
`open`	`() => void`	手動觸發檔案選擇對話框

注意事項

無樣式：不內建任何 CSS，UI 完全交給 slot 的消費方實作。
uploadFn 通常封裝自 useUploader（uploadFile 方法）；Demo 中用 mock 實作演示流程。
無轉碼二段：與 SwUploadVideo 的本質區別——普通檔案上傳完直接拿 value（URL），無需 queryFn 輪詢。
pending 期間重複觸發會被忽略（防重複上傳）；UI 應據 pending 做 disabled / loading 態。