ImageUpload

이미지 전용 업로드 컴포넌트. 드래그 앤 드롭 또는 클릭으로 이미지를 업로드하고, 썸네일 그리드로 관리한다.

개요

Foundation의 FileUpload 컴포넌트를 래핑하여 이미지 전용 업로드 기능을 제공한다. 이미지 확장자만 허용하며, 썸네일 미리보기·회전·미리보기 팝업 등 이미지 관리에 특화된 기능을 제공한다.

주요 특징

• ✅ 이미지 전용: JPG, PNG, GIF만 허용 (확장자 자동 검증)
• ✅ 썸네일 그리드: 업로드된 이미지를 그리드 형태로 미리보기
• ✅ 이미지 회전: 새 파일은 시계방향 90° 회전 지원
• ✅ 미리보기 팝업: 썸네일 클릭 시 원본 이미지 확대 보기
• ✅ 파일 검증: 확장자, 크기, 개수, 빈 파일 검사
• ✅ 읽기 전용: 업로드·삭제·회전 숨김, 다운로드·미리보기 유지
• ✅ FormItem 통합: 레이블, 필수 표시, 수평 배치, 도움말 지원

기본 사용

드래그 앤 드롭 또는 클릭으로 이미지를 업로드한다. 이미지 파일만 허용된다.

<ImageUpload
  onChange={(files) => console.log(files)}
  onError={(e) => alert(e)}
/>

기존 이미지 목록

서버에 저장된 기존 이미지를 썸네일 그리드로 표시한다. 새 파일(isNew)에는 회전 버튼, 기존 파일에는 다운로드 버튼이 표시된다.

<ImageUpload
  existingFiles={[
    { id: "1", name: "photo.jpg", size: 2048000, thumbnailUrl: "/thumb/photo.jpg" },
    { id: "2", name: "logo.png", size: 512000, isNew: true },
  ]}
  onRemoveExisting={(f) => console.log("삭제:", f.name)}
  onDownload={(f) => window.open(f.url)}
  onRotate={(f, angle) => console.log("회전:", f.name, angle)}
/>

읽기 전용

readOnly이면 업로드 영역·삭제·회전 버튼이 숨겨진다.

<ImageUpload
  readOnly
  existingFiles={files}
  onDownload={(f) => window.open(f.url)}
/>

파일 검증

maxFileSize와 maxFileCount로 업로드 규칙을 설정한다.

<ImageUpload
  maxFileSize={2}          // 2MB
  maxFileCount={3}         // 최대 3개
  onError={(e) => alert(e)}
/>

레이블 / 필수

FormItem 래핑으로 레이블, 필수 표시, 수평 레이아웃을 지원한다.

<ImageUpload label="이미지" />
<ImageUpload label="필수 이미지" required />
<ImageUpload label="수평" orientation="horizontal" labelWidth={80} />

라벨 도움말

labelTooltip으로 레이블 옆에 도움말 아이콘을 표시한다.

<ImageUpload
  label="이미지"
  labelTooltip="JPG, PNG, GIF만 업로드 가능합니다. 파일당 최대 5MB."
/>

API Reference

Props

Events

Ref API

접근성

권장 사항

• ✅ label prop으로 업로드 영역에 의미 있는 레이블 제공
• ✅ required 설정 시 aria-required 자동 적용
• ✅ 미리보기 팝업 Dialog에 aria-label 적용
• ✅ 모든 액션 버튼에 aria-label 적용 (회전, 다운로드, 삭제)
• ❌ 아이콘만 있는 버튼에 aria-label 누락 금지

관련 컴포넌트

• FileUpload: 범용 파일 업로드 컴포넌트
• Foundation FileUpload: 기본 FileUpload 컴포넌트
• FormItem: 폼 래퍼