Upload
이미지 카드 목록 형태의 파일 업로드 컴포넌트
개요
Upload는 업로드된 파일을 정사각형 카드 그리드로 표시하고, + 버튼으로 파일을 추가하는 업로드 컴포넌트입니다. 파일 크기·확장자 유효성 검사와 카드 호버 시 삭제 기능을 내장하고 있습니다.
주요 특징
- ✅ 카드 목록: 업로드된 파일을 이미지 카드 그리드로 표시
- ✅ 미리보기: url이 있는 파일은 이미지 미리보기 자동 표시
- ✅ 유효성 검사: maxSize(크기), accept(확장자) 검증 및 onError 콜백
- ✅ 호버 삭제: 카드 호버 시 오버레이 삭제 버튼 표시
- ✅ 다중 선택: multiple prop으로 다중 파일 선택 제어
- ✅ 표시 제어: visible prop으로 전체 표시/숨김
기본 사용
files와 onFilesChange로 파일 목록을 제어합니다.
Preview
유효성 검사
accept(허용 확장자)와 maxSize(최대 크기, 바이트)를 지정하고 onError로 실패를 처리합니다. 기본 최대 크기는 15MB입니다.
Preview
단일 파일 선택
multiple={false}로 파일 선택 창에서 단일 파일만 선택할 수 있습니다.
Preview
비활성화
disabled로 파일 추가와 삭제를 모두 비활성화합니다.
Preview
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
files | UploadFile[] | [] | 파일 목록 |
maxSize | number | 15728640 (15MB) | 최대 파일 크기 (바이트) |
accept | string[] | - | 허용 확장자 (예: [".jpg", ".png"]) |
multiple | boolean | true | 다중 선택 허용 |
disabled | boolean | false | 비활성화 (추가/삭제 불가) |
visible | boolean | true | 표시 여부 (false면 렌더링 안 함) |
className | string | - | 컨테이너에 적용할 CSS 클래스 |
Events
| Event | Type | Description |
|---|---|---|
onFilesChange | (files: UploadFile[]) => void | 파일 목록 변경 시 호출 (추가/삭제) |
onSelect | (file: UploadFile) => void | 카드 클릭 시 호출 |
onError | (error: UploadError) => void | 유효성 검사 실패 시 호출 (type: “size” | “type”) |
UploadFile
| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✅ | 고유 ID |
name | string | ✅ | 파일 이름 |
url | string | - | 미리보기 URL |
size | number | - | 파일 크기 (바이트) |
UploadError
| Field | Type | Description |
|---|---|---|
type | "size" | "type" | 실패 유형 (크기 초과/확장자) |
file | File | 실패한 원본 File 객체 |
접근성
권장 사항
- ✅ 파일 추가 버튼에
aria-label="파일 추가"자동 적용 - ✅ 카드별 삭제 버튼에
aria-label="{파일명} 삭제"자동 적용 - ✅ 이미지 미리보기에 파일명 alt 텍스트 자동 적용
- ❌ url 없는 파일은 파일명 텍스트가 표시되므로 의미 있는 파일명 사용
관련 컴포넌트
- FileUpload: 파일 업로드 컴포넌트
- ImageUpload: 이미지 전용 업로드 컴포넌트
- ImageView: 이미지 슬라이드 뷰어 컴포넌트
Last updated on