Upload 上傳

原生 <input type="file"> 驅動 + 拖曳區。請求由使用方透過 request prop 提供（庫零執行時期依賴，不內建 HTTP 客戶端）。

基礎用法

基礎用法

選擇檔案

<script setup lang="ts">
</script>

<template>
  <LhUpload :max-size="1048576" :accept="['.png', '.jpg']" />
</template>

<script>
export default {}
</script>

<template>
  <LhUpload :max-size="1048576" :accept="['.png', '.jpg']" />
</template>

accept 也支援逗號字串寫法（如 accept=".png,.jpg"，靜態屬性直接書寫）。

拖曳 + 自訂請求

拖曳上傳

將檔案拖到此處，或點選上傳

<script setup>
const fakeRequest = ({ file, onProgress }) =>
  new Promise((resolve) => {
    let percent = 0
    const timer = setInterval(() => {
      percent += 20
      onProgress(percent)
      if (percent >= 100) {
        clearInterval(timer)
        resolve({ url: `https://example.com/${file.name}` })
      }
    }, 200)
  })
</script>

<template>
  <!-- 拖曳上傳 -->
  <LhUpload drag :multiple="true" :request="fakeRequest" />
</template>

<script>
export default {
  methods: {
    fakeRequest({ file, onProgress }) {
      return new Promise((resolve) => {
        let percent = 0
        const timer = setInterval(() => {
          percent += 20
          onProgress(percent)
          if (percent >= 100) {
            clearInterval(timer)
            resolve({ url: `https://example.com/${file.name}` })
          }
        }, 200)
      })
    },
  },
}
</script>

<template>
  <!-- 拖曳上傳 -->
  <LhUpload drag :multiple="true" :request="fakeRequest" />
</template>

停用與數量上限

disabled 停用上傳；max-count 限制最多上傳的檔案數。

停用 / 數量上限

選擇檔案

選擇檔案

<script setup lang="ts">
</script>

<template>
  <LhUpload disabled />
  <LhUpload :max-count="2" />
</template>

<script>
export default {}
</script>

<template>
  <LhUpload disabled />
  <LhUpload :max-count="2" />
</template>

API

LhUpload Props

屬性名	說明	類型	預設值
multiple	允許多選	boolean	false
drag	拖曳上傳區	boolean	false
disabled	停用	boolean	false
accept	允許的副檔名 / MIME，陣列（['.png', 'image/*']）或逗號字串（'.png,.jpg'）均可	string | string[]	() => []
maxSize	單一檔案大小上限（位元組）	number	[LH_UPLOAD_MAX_SIZE](#const-LH_UPLOAD_MAX_SIZE)
maxCount	數量上限（0 為不限）	number	0
request	上傳請求函式（不傳則只做本地選擇與校驗）	(options: { file: File; onProgress: (percent: number) => void; }) => Promise<{ url?: string; }>	—
sx	sx 快速版面配置屬性	LhSxProps	—

Events

事件名	說明	回呼參數
change	檔案列表變化時觸發（新增檔案、上傳結束、移除檔案後）	(files: LhUploadFile[])
success	單一檔案上傳成功後觸發	(file: LhUploadFile)
error	單一檔案上傳失敗後觸發	(file: LhUploadFile, reason: string)
remove	移除檔案後觸發	(uid: string)

插槽：default（觸發區內容）。

LhUploadRequest

(options: { file: File; onProgress: (percent: number) => void }) => Promise<{ url?: string }>

無障礙

• 原生 <input type="file"> 視覺隱藏但保留在無障礙樹，aria-label 命名
• 觸發區 role="button" + tabindex + Enter/Space 開啟檔案選擇，停用時移出互動
• 進度條 role="progressbar" + aria-valuenow/min/max；校驗失敗 role="alert" 播報；每項移除按鈕帶檔案命名

類型定義

本元件對外匯出的 TypeScript 類型結構如下（自動提取自 packages/components/upload/src/types.ts 與 @lh-ui/share/core/* 原始碼，點選各條目展開檢視完整定義；屬性說明見上方 Props 表）：

LhUploadProps

export interface LhUploadProps {
  /** 允許多選 */
  multiple?: boolean
  /** 拖曳上傳區 */
  drag?: boolean
  /** 停用 */
  disabled?: boolean
  /** 允許的副檔名 / MIME：陣列 `['.png', 'image/*']` 或逗號字串 `'.png,.jpg'` */
  accept?: string[] | string
  /** 單一檔案大小上限（位元組） */
  maxSize?: number
  /** 數量上限（0 為不限） */
  maxCount?: number
  /** 上傳請求函式（不傳則只做本地選擇與校驗） */
  request?: LhUploadRequest
  /** sx 快速版面配置屬性 */
  sx?: LhSxProps
}

LhUploadRequest _{（來自 @lh-ui/share/core/upload）}

/** 上傳請求函式簽章（由使用方提供，庫不內建 HTTP 客戶端） */
export type LhUploadRequest = (options: {
  file: File
  onProgress: (percent: number) => void
}) => Promise<{ url?: string }>

LhUploadFileStatus _{（來自 @lh-ui/share/core/upload）}

/** 檔案項狀態 */
export type LhUploadFileStatus = 'ready' | 'uploading' | 'success' | 'fail'

LhUploadFile _{（來自 @lh-ui/share/core/upload）}

/** 上傳檔案項 */
export interface LhUploadFile {
  /** 唯一識別（內部產生或使用者提供） */
  uid: string
  /** 檔案名稱 */
  name: string
  /** 位元組大小 */
  size: number
  /** 狀態 */
  status: LhUploadFileStatus
  /** 上傳進度 0-100 */
  percent: number
  /** 伺服器傳回地址（成功時） */
  url?: string
  /** 失敗原因 */
  error?: string
  /** 原始 File 物件 */
  raw?: File
}

常數

本元件用到的公開常數如下（可在 Props 表的「類型 / 預設值」欄點選同名條目跳轉至此）：

LH_UPLOAD_MAX_SIZE _{（來自 @lh-ui/share/core/upload）}

/** 預設大小上限 5MB */
export const LH_UPLOAD_MAX_SIZE = 5 * 1024 * 1024