FileDropZone

파일을 끌어다 놓거나 클릭해서 선택하면 repository 모듈로 업로드하고, 업로드한 파일 목록에서 바로 다운로드·삭제할 수 있는 컨트롤입니다. 오픈소스 Dropzone(v6.3.5, MIT)을 기반으로 하며 파일별 진행률, 썸네일, 오류 표시를 제공합니다.

값은 업로드가 끝난 파일 항목 객체 배열입니다(repository 항목 JSON: ItemID, FileName, Size, Extension, DependencyID 등).

getValue: 업로드가 끝난 파일 항목 배열, 없으면 []
setValue: 항목 배열(또는 ItemID 문자열 배열, 쉼표 문자열, JSON 문자열)로 화면 목록을 교체합니다. 서버에 업로드하거나 삭제하지 않습니다.

FileClient 와의 차이

구분	FileDropZone	FileClient
업로드 화면	화면 안에 직접 표시(끌어놓기, 클릭)	팝업 iframe 페이지
진행률, 썸네일, 목록 내 다운로드·삭제	있음	없음
값	파일 항목 객체 배열	ItemID 문자열(쉼표 구분)
서버	repository 모듈(`/repository/api/storage`)	동일

빠른 시작

<syn_filedropzone id="fdzAttach" syn-datafield="Attachments" syn-events="['change']" syn-options="{
    repositoryID: 'TSTLM01',
    applicationID: 'HDS',
    dependencyID: 'POST_20261014_0001'
}"></syn_filedropzone>

'use strict';
let $mypage = {
    event: {
        fdzAttach_change(evt) {
            // 업로드 성공 또는 삭제 시 발생. evt.detail.value 는 getValue() 와 같은 항목 배열
        },

        btnSave_click() {
            if (syn.uicontrols.$filedropzone.isUploading('fdzAttach') == true) {
                return;
            }

            // [{ItemID, FileName, Size, Extension, DependencyID, ...}]
            var files = syn.uicontrols.$filedropzone.getValue('fdzAttach');
        },

        btnDownload_click() {
            syn.uicontrols.$filedropzone.download('fdzAttach', itemID);
        }
    }
}

/js/syn.loader.js가 syn_filedropzone 태그를 인식해 Dropzone 라이브러리(/lib/dropzone/dist/dropzone-min.js, dropzone.css)와 컨트롤 파일을 자동으로 불러옵니다. 라이브러리는 libman.json에 등록되어 있으며 libman restore로 내려받습니다.

저장소 연동 방식

컨트롤이 로드되면 get-repository로 저장소 정책(확장자, 크기, 개수, 단일 또는 다중)을 조회합니다. 조회가 끝나면 ready 이벤트가 발생하며 whenReady(elID)로도 기다릴 수 있습니다. 저장소가 없으면 컨트롤에 오류가 표시됩니다.
파일은 파일마다 upload-file(multipart, 필드 file)로 올라가며 같은 dependencyID로 묶입니다.
dependencyID를 지정하면 로드할 때 그 키의 파일을 조회해 보여줍니다. 지정하지 않으면 임시 키(TEMP_...)를 만들어 쓰고, 저장할 때 updateDependencyID(elID, 업무키)로 실제 키로 옮깁니다.
다운로드는 download-file(POST)로 받아 브라우저 다운로드로 저장하며, 삭제는 remove-item입니다.
서버 주소는 fileManagerServer 옵션, syn.Config.FileManagerServer 순서로 정합니다. applicationID와 businessID는 FileClient 와 같은 규칙으로 결정합니다.

알아 둘 점

확장자와 개수 제한은 서버가 강제하지 않습니다. repository 는 파일 크기만 서버에서 검사하므로 확장자(UploadExtensions)와 개수(UploadCount)는 컨트롤이 업로드 전에 검사해 거부합니다(fileRejected 이벤트).
단일 파일 저장소(IsMultiUpload: false)는 새 파일을 올리면 서버가 이전 파일을 지우므로, 화면에서도 새 파일 업로드가 성공하면 이전 파일을 교체합니다. 여러 파일을 한꺼번에 놓으면 마지막 파일만 올라갑니다.
저장 경로(customPath1~3): 파일은 PhysicalPath/{customPath1}/{customPath2}/{customPath3}/{정책 경로(연도 등)}에 저장되고, repository 모듈의 다운로드는 항목에 기록된 CustomPath1~3으로 같은 위치를 계산해 검증합니다. 따라서 customPath1~3을 지정하든 안 하든 다운로드됩니다. 이전 버전 repository 모듈은 PhysicalPath/{ApplicationID} 아래 파일만 허용해 기본 설정에서 파일 경로 확인 필요(400)가 났으며, 이 경우 customPath1에 ApplicationID 값을 지정해 우회할 수 있습니다.
setValue, clear는 화면 목록만 바꾸며 change 이벤트도 발생하지 않습니다. 서버 파일을 지우려면 removeItem, removeAll을 사용합니다.

옵션

옵션	기본값	설명
`repositoryID`	`''`	필수. 저장소 ID
`applicationID`, `businessID`	`''`	생략하면 FileClient 와 같은 규칙으로 결정
`dependencyID`	`''`	파일을 묶는 키. 생략하면 임시 키를 만들고 기존 파일을 조회하지 않음
`customPath1`, `customPath2`, `customPath3`	`''`	업로드 저장 하위 경로
`fileManagerServer`, `fileManagerPath`	`''`, `'/repository/api/storage'`	repository 서버 주소와 API 경로
`width`, `height`	`'100%'`, `null`	영역 너비, 최소 높이
`placeholder`	안내 문구	비어 있을 때 보이는 문구
`autoLoad`	`true`	`dependencyID`를 지정했을 때 로드 시 서버 파일 조회
`deleteOnRemove`	`true`	삭제 버튼이 서버 파일도 삭제
`confirmRemove`	`false`	삭제 전 확인창
`readOnly`	`false`	업로드와 삭제를 막고 다운로드만 허용
`showDownload`, `thumbnails`	`true`, `true`	다운로드 버튼, 이미지 썸네일
`acceptedFiles`, `maxFilesize`, `maxFiles`	`null`	저장소 정책보다 엄격할 때만 적용되는 추가 제한(형식, MB, 개수)
`parallelUploads`, `timeout`	`2`, `0`	동시 업로드 수, 제한 시간(ms)
`headers`, `withCredentials`	`null`, `false`	추가 요청 헤더, 쿠키 포함 여부
`rejectedDisplayMs`	`3000`	업로드 전에 거부된 파일 카드 표시 시간(ms)

공통 옵션(dataType, belongID, getter, setter, controlText, validators, transactConfig, triggerConfig)은 다른 컨트롤과 같습니다.

메서드

메서드	설명
`getValue(elID)`	업로드가 끝난 파일 항목 배열
`setValue(elID, value)`	항목 배열 등으로 화면 목록 교체. `Promise<boolean>`, `change` 없음
`clear(elID)`	화면 목록만 비움
`load(elID, dependencyID)`	서버에서 파일을 다시 조회해 목록 교체. `dependencyID`를 주면 이후 업로드도 그 키 사용
`upload(elID, files)`	`File` 객체를 코드에서 추가해 업로드
`removeItem(elID, itemID)`, `removeAll(elID)`	서버 파일 삭제와 목록 제거
`download(elID, itemID)`, `getDownloadUrl(elID, itemID, disposition)`	다운로드, `http-download-file` 주소
`getDependencyID`, `setDependencyID`, `updateDependencyID(elID, targetDependencyID)`	키 조회, 키 변경, 서버 항목의 키 이동(임시 키에서 업무 키로)
`isEmpty`, `isUploading`	파일 유무, 업로드 중 여부
`setReadOnly`, `setDisabled`	읽기 전용, 비활성화 전환
`whenReady(elID)`, `toFileLengthString(bytes)`, `getControl`, `destroy`	준비 대기, 크기 문자열, 내부 항목, 정리

이벤트

이벤트	시점	`evt.detail`
`ready`	정책 조회와 기존 파일 표시가 끝났을 때	`{ policy }`
`fileAdded`	파일을 추가했을 때	`{ file }`
`fileRejected`	크기, 확장자, 개수 초과로 업로드 전에 거부됐을 때	`{ file, reason }`
`uploadProgress`	진행률이 바뀔 때	`{ file, progress }`
`uploadSuccess`	업로드가 성공했을 때	`{ file, item }`
`uploadError`	서버가 거부했거나 네트워크 또는 HTTP 오류일 때	`{ file, message }`
`queueComplete`	대기 중인 업로드가 모두 끝났을 때	`{}`
`fileRemoved`	파일을 제거했을 때	`{ item }`
`fileDownload`	다운로드를 시작했을 때	`{ item }`
`change`	업로드 성공, 삭제, `removeAll`로 값이 바뀌었을 때	`{ value }`

예제 실행하기

/uicontrols/FileDropZone/example/ 폴더에 다음 예제가 있습니다. repository 모듈이 포함된 ack에서 열어야 하며 샘플 저장소 TSTLM01, TSTLS01, TSTLE01과 앱 HDS를 사용합니다.

basic.html — 기본 업로드, 다운로드, 삭제
getset.html — getValue, setValue, clear, load
features.html — 전체 옵션, 메서드, 이벤트 확인
practical.html — 게시글 첨부파일(임시 키로 업로드, 저장 시 게시글 키로 이동, 다시 조회)

별도 샘플 페이지는 /sample/uicontrol/filedropzone.html입니다. 전체 옵션과 메서드 설명은 /uicontrols/FileDropZone/API.md를 참고하세요.

FileClient 와의 차이​

빠른 시작​

저장소 연동 방식​

알아 둘 점​

옵션​

메서드​

이벤트​

예제 실행하기​

FileClient 와의 차이

빠른 시작

저장소 연동 방식

알아 둘 점

옵션

메서드

이벤트

예제 실행하기