File Uploader
<file-uploader>프레임워크 독립적인 Web Component 기반 파일 업로더입니다. 드래그 앤 드롭, 이미지/PDF 미리보기, 파일 검증, 정렬 등 다양한 기능을 제공합니다.
주요 기능
File Uploader가 제공하는 핵심 기능들입니다.
드래그 앤 드롭
파일을 드래그하여 쉽게 업로드
이미지 미리보기
업로드 전 이미지 썸네일 표시
PDF 렌더링
PDF.js로 첫 페이지 썸네일 생성
파일 검증
타입, 크기, 개수 제한
드래그 정렬
파일 순서 변경 지원
수정 모드
기존 파일 로드 및 편집
설치 방법
프로젝트에 File Uploader를 추가하는 방법입니다.
Web Component이므로 React, Vue, Angular 등 모든 프레임워크에서 사용할 수 있습니다.
파일 다운로드
배포 파일을 다운로드하여 프로젝트에 추가합니다.
HTML에서 사용
ES Module Import
빠른 시작
가장 기본적인 사용법입니다.
기본 사용
태그 하나로 파일 업로더를 추가할 수 있습니다.
옵션 적용
다양한 속성으로 동작을 커스터마이즈합니다.
속성 (Attributes)
컴포넌트에서 사용할 수 있는 HTML 속성들입니다.
| 속성명 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| accept | string | * | 허용 파일 타입 (예: image/*, .pdf) |
| max-size | number | 10485760 | 최대 파일 크기 (bytes, 기본 10MB) |
| max-files | number | 10 | 최대 파일 개수 |
| view-mode | string | list | 보기 모드 (list | grid) |
| compact | boolean | false | 컴팩트 모드 (폼 내부용) |
| readonly | boolean | false | 읽기 전용 모드 |
| disabled | boolean | false | 비활성화 |
| hide-upload-btn | boolean | false | 업로드 버튼 숨기기 |
| hide-clear-btn | boolean | false | 초기화 버튼 숨기기 |
| preview-height | number | 120 | 미리보기 높이 (px) |
| drop-text | string | - | 드롭 영역 메인 텍스트 |
| drop-hint | string | - | 드롭 영역 힌트 텍스트 |
메서드 (Methods)
JavaScript로 컴포넌트를 제어하는 메서드들입니다.
| 메서드 | 반환 타입 | 설명 |
|---|---|---|
| getFiles() | File[] | 새로 추가된 파일 목록 반환 |
| clearFiles() | void | 모든 파일 제거 |
| addFiles(files) | void | 파일을 프로그래밍 방식으로 추가 |
| loadFiles(fileInfos) | void | 기존 파일 로드 (수정 모드) |
| getNewFiles() | File[] | 새로 추가된 파일만 반환 |
| getDeletedFileIds() | Array | 삭제된 기존 파일 ID 목록 |
| getExistingFileIds() | Array | 유지되는 기존 파일 ID 목록 |
| getAllFiles() | Array | 모든 파일 정보 반환 |
| getAllFilesForUpload() | Promise<Array> | 업로드용 Blob/File 배열 (비동기) |
이벤트 (Events)
컴포넌트에서 발생하는 커스텀 이벤트입니다. event.detail로 데이터에 접근합니다.
| 이벤트 | detail | 설명 |
|---|---|---|
| files-selected | { files: File[] } | 파일이 선택되었을 때 |
| file-removed | { file, index } | 파일이 삭제되었을 때 |
| files-cleared | - | 전체 파일이 초기화되었을 때 |
| files-reordered | { files } | 파일 순서가 변경되었을 때 |
| files-loaded | { files } | 기존 파일이 로드되었을 때 |
| upload-requested | { files: File[] } | 업로드 버튼이 클릭되었을 때 |
폼 통합 예제
FormData를 사용하여 서버로 파일을 업로드하는 전체 예제입니다.
폼 제출 코드
FormData로 파일과 데이터를 함께 전송합니다.
수정 모드 예제
기존 데이터를 수정할 때 파일을 관리하는 방법입니다.
수정 모드에서는
loadFiles()로 기존 파일을 로드하고,
getNewFiles(), getDeletedFileIds()로 변경사항을 추적합니다.