Upload 업로드

네이티브 <input type="file"> 기반의 업로드와 드래그 앤 드롭 영역을 제공합니다. 요청은 사용자가 request prop으로 제공합니다 (라이브러리는 런타임 의존성이 없으며, HTTP 클라이언트를 내장하지 않습니다).

기본 사용법

파일 선택

vue

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

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

vue

<script>
export default {}
</script>

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

accept는 쉼표로 구분된 문자열 형태도 지원합니다 (예: accept=".png,.jpg", 정적 속성으로 직접 작성).

드래그와 사용자 정의 요청

파일을 여기로 끌어다 놓거나 클릭하여 업로드하세요

vue

<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>

vue

<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는 최대 업로드 파일 수를 제한합니다.

파일 선택

vue

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

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

vue

<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	파일 1개당 크기 제한 (바이트)	`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
  /** 파일 1개당 크기 제한 (바이트) */
  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

Upload 업로드 ​

기본 사용법 ​

드래그와 사용자 정의 요청 ​

비활성화와 수량 제한 ​

API ​

LhUpload Props ​

Events ​

LhUploadRequest ​

접근성 ​

타입 정의 ​

상수 ​