FileUpload

파일 업로드 컴포넌트. 드래그 앤 드롭 또는 클릭으로 파일을 업로드하고, 업로드된 파일 목록을 관리한다.

개요

Foundation의 FileUpload 컴포넌트를 래핑하여 CALS 폼 시스템과 통합한다. 허용 확장자·MIME 타입·파일 크기·개수 검증, 읽기 전용, 기존 파일 다운로드·미리보기 등 비즈니스 요구사항을 지원한다.

주요 특징

• ✅ 드래그 앤 드롭: Atlassian Pragmatic DnD 기반 안정적인 파일 드롭
• ✅ 파일 검증: 확장자, MIME 타입, 크기, 빈 파일 검사
• ✅ 읽기 전용: 업로드 영역·삭제 숨김, 열기·다운로드 유지
• ✅ 기존 파일: 서버 저장 파일 목록 + 다운로드/미리보기 콜백
• ✅ FormItem 통합: 라벨, 필수 표시, 수평 배치, 도움말 지원
• ✅ 디자인 토큰: Foundation 토큰 시스템 완벽 호환

기본 사용

드래그 앤 드롭 또는 클릭으로 파일을 업로드한다.

<FileUpload onChange={(files) => console.log(files)} />

파일 검증

accept, allowedExtensions, maxFileSize, maxFileCount로 업로드 규칙을 설정한다.

<FileUpload
  accept="image/*,.pdf"
  allowedExtensions="jpg,jpeg,png,pdf"
  maxFileSize={2}          // 2MB
  maxFileCount={3}
  onError={(e) => alert(e)}
/>

읽기 전용

readOnly이면 업로드 영역과 삭제 버튼이 숨겨지고, 기존 파일의 열기·다운로드만 표시된다.

<FileUpload
  readOnly
  existingFiles={[{ id: "1", name: "보고서.pdf", size: 2048000 }]}
  onDownload={(f) => alert(`다운로드: ${f.name}`)}
/>

라벨 / 필수

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

<FileUpload label="첨부파일" />
<FileUpload label="필수 첨부" required />
<FileUpload label="수평" orientation="horizontal" labelWidth={80} />

라벨 도움말

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

<FileUpload
  label="첨부"
  labelTooltip="최대 5개 파일, 파일당 5MB까지 업로드 가능합니다."
/>

API Reference

Props

Events

Ref API

접근성

권장 사항

• ✅ label prop으로 업로드 영역에 의미 있는 라벨 제공
• ✅ required 설정 시 aria-required 자동 적용
• ✅ 키보드(Enter/Space)로 파일 선택 대화상자 열기 지원
• ❌ 아이콘만 있는 버튼에 aria-label 누락 금지

관련 컴포넌트

• Foundation FileUpload: 기본 FileUpload 컴포넌트
• FormItem: 폼 래퍼