ProgressUploader

썸네일 미리보기와 업로드 진행률을 제공하는 단일 카드형 파일 업로드 컴포넌트

개요

ProgressUploader는 최대 1개의 파일을 관리하는 단일 카드형 업로드 컴포넌트입니다. 파일이 없으면 업로드 버튼을, 파일이 있으면 썸네일 카드를 표시하며, 업로드 진행률 바와 크기/확장자 유효성 검사를 내장하고 있습니다.

주요 특징

• ✅ 단일 파일 관리: file / onFileChange로 최대 1개 파일 제어
• ✅ 썸네일 미리보기: 파일 선택 시 카드 형태로 미리보기 표시
• ✅ 진행률 표시: progress prop으로 업로드 진행률 바 표시 (0~100)
• ✅ 유효성 검사: maxSize(기본 15MB), accept 확장자 검증 + onError 콜백
• ✅ 삭제 잠금: locked=true이면 삭제 버튼 비표시
• ✅ 표시 제어: visible prop으로 전체 표시/숨김

기본 사용

file과 onFileChange로 파일 상태를 제어합니다. 파일이 없으면 업로드 버튼이 표시됩니다.

import { ProgressUploader, type ProgressUploaderFile } from "@vortex/ui-cals"
 
const [file, setFile] = useState<ProgressUploaderFile | null>(null)
 
<ProgressUploader file={file} onFileChange={setFile} />

파일 선택됨 상태

파일이 있으면 썸네일 카드와 삭제 버튼이 표시되고 업로드 버튼은 자동으로 숨겨집니다.

const [file, setFile] = useState<ProgressUploaderFile | null>({
  id: "1",
  name: "proposal.pdf",
  size: 240 * 1024,
})
 
<ProgressUploader file={file} onFileChange={setFile} />

업로드 진행률

progress(0~100)를 전달하면 카드 하단에 진행률 바가 표시됩니다. 100에 도달하면 바가 사라집니다. 업로드 중에는 locked로 삭제를 막을 수 있습니다.

<ProgressUploader
  file={{ id: "1", name: "uploading.png" }}
  progress={65}
  locked
/>

확장자/크기 검증

accept로 허용 확장자를, maxSize로 최대 크기(바이트, 기본 15MB)를 지정합니다. 검증 실패 시 onError가 호출됩니다.

<ProgressUploader
  file={file}
  onFileChange={setFile}
  accept={[".jpg", ".png"]}
  onError={(e) =>
    alert(
      e.type === "type"
        ? `허용되지 않는 확장자입니다: ${e.file.name}`
        : `파일 크기 초과: ${e.file.name}`,
    )
  }
/>

비활성화 / 삭제 잠금

disabled로 업로드 버튼을 비활성화하고, locked로 파일 삭제를 잠급니다.

<ProgressUploader disabled />
<ProgressUploader file={{ id: "1", name: "locked.pdf" }} locked />

API Reference

Props

ProgressUploaderFile

ProgressUploaderError

Events

접근성

권장 사항

• ✅ 업로드 버튼에 aria-label="파일 업로드" 자동 적용
• ✅ 삭제 버튼에 aria-label="{파일명} 삭제" 자동 적용
• ✅ 진행률 바에 role="progressbar"와 aria-value 속성 자동 적용
• ❌ 업로드 실패 원인을 onError로 받아 사용자에게 텍스트로 안내하기

관련 컴포넌트

• Upload: 이미지 카드 목록 업로드 컴포넌트
• ImageUpload: 이미지 전용 업로드 컴포넌트
• FileUpload: 파일 업로드 컴포넌트
• Progress: 진행률 표시 바 컴포넌트