FileClient
이 컨트롤은 무엇인가요?
FileClient는 파일을 업로드/다운로드하는 컨트롤입니다. 화면에 그려지는 것은 값(업로드된 파일의 ItemID, 다중일 경우 콤마로 연결된 문자열)을 담는 숨겨진 <input type="hidden"> 하나뿐이며, 실제 업로드 UI(파일 선택, 진행 상태 등)는 별도의 팝업 다이얼로그(iframe)로 열립니다.
컨트롤이 초기화(controlLoad)될 때 서버(fileManagerServer)에 repositoryID로 지정한 저장소 정보를 조회해서, 그 저장소가 어떤 업로드 방식(UploadType: 단일/프로필 이미지/다중/에디터 이미지)인지, 허용 확장자·업로드 개수·용량 제한이 얼마인지를 자동으로 결정합니다. 즉 업로드 정책은 화면 코드가 아니라 repositoryID가 가리키는 서버 설정에 달려 있습니다.
언제 사용하나요?
- 회사 로고, 프로필 사진처럼 파일 1개를 업로드/교체해야 할 때 (
Single,Profile저장소) - 첨부파일처럼 여러 개의 파일을 업로드해야 할 때 (
Multi저장소) - 에디터(
HtmlEditor등) 안에 삽입할 이미지를 업로드해야 할 때 (ImageLink저장소) - 업로드된 파일을 다운로드하거나, 목록 조회/삭제/이름 변경/소속 변경(
dependencyID변경) 같은 파일 관리 기능이 필요할 때
버튼 클릭 등으로 업로드 창을 여는 것이 일반적인 사용 방식이며, 컨트롤 자체가 파일 선택 UI를 화면에 항상 그려주는 것은 아닙니다.
빠른 시작
<syn_fileclient id="sfcCompanyImage" syn-datafield="CompanyImage" syn-options="{repositoryID: 'BDLLP01'}"></syn_fileclient>
<input type="button" id="btnUploadCompanyImage" value="이미지 업로드" syn-events="['click']" />
let $mypage = {
event: {
btnUploadCompanyImage_click() {
// 1. 이 컨트롤에 저장된 기본 업로드 옵션을 가져온다
var uploadOptions = syn.uicontrols.$fileclient.getFileSetting('sfcCompanyImage');
// 2. 업로드 완료 후 결과를 받을 콜백, 소속 ID(dependencyID) 등을 필요에 맞게 덮어쓴다
uploadOptions.fileUpdateCallback = 'sfcCompanyImage_callback';
uploadOptions.dependencyID = syn.$w.User.CompanyID;
uploadOptions.minHeight = 386;
// 3. 업로드 팝업을 연다
syn.uicontrols.$fileclient.uploadUI(uploadOptions);
},
sfcCompanyImage_callback(action, result) {
if (action == 'upload') {
const item = result.items[0];
syn.$l.get('hdnCompanyImageUrl').value = item.AbsolutePath;
}
}
}
}
핵심 흐름은 "기본 설정을 가져온다(getFileSetting) → 필요한 값만 덮어쓴다 → uploadUI로 업로드 창을 연다 → 업로드가 끝나면 지정한 콜백 함수가 (action, result)로 호출된다"입니다. 업로드는 보통 이렇게 버튼 클릭에서 프로그램적으로(programmatically) 호출하며, 컨트롤이 페이지 로드 시 자동으로 업로드 UI를 그려주지는 않습니다.
/js/syn.loader.js가 syn_fileclient 태그를 자동으로 인식해 필요한 CSS/JS를 알아서 불러오므로, 페이지 맨 아래에 <script src="/js/syn.loader.js"></script> 한 줄만 있으면 됩니다.
예제 실행하기
example/ 폴더에 다음 예제가 있습니다. 실행 중인 사이트에서 아래 경로로 바로 열어볼 수 있습니다. (예제의 repositoryID 값은 서버에 미리 등록되어 있어야 실제로 동작합니다. 등록되지 않은 값이면 "파일 서버 저장 정보 확인 필요" 경고가 표시됩니다.)
example/basic.html— 단일 파일 업로드/다운로드/삭제와 업로드 완료 콜백(fileUpdateCallback)으로 결과를 표시하는 가장 기본적인 사용법example/settings.html—dependencyID,custom1~custom3,minHeight등 업로드 옵션을 상황에 맞게 커스터마이징하는 방법 (다중 파일 저장소 기준)example/methods.html—getValue/setValue/clear와getItem/getItems/deleteItem등 값 조회·관리 메서드 데모example/attachments.html— 게시판/전자결재처럼 여러 건을 첨부하는 실무 패턴: 그리드 없이Flag(R/C/D) 배열을 직접 관리하고, 업무 키(문서 번호)가 있어야만 첨부 가능, 첨부 개수 상한 검증, 저장 트랜잭션에type: 'List'로 함께 전송
더 알아보기
전체 옵션/메서드 목록은 아래 API 참조 섹션를 참고하세요.
실전 예제 페이지
/uicontrols/FileClient/example/ 경로의 예제를 아래 iframe에서 바로 확인할 수 있습니다.
basic.html
methods.html
settings.html
attachments.html
소스와 로드 파일
| 항목 | 내용 |
|---|---|
| 컨트롤 | FileClient |
| 전역 별칭 | syn.uicontrols.$fileclient |
| 버전 | v2025.9.16 |
| 소스 | uicontrols/FileClient/FileClient.js |
| 스타일 | uicontrols/FileClient/FileClient.css |
API 참조
syn.uicontrols.$fileclient (버전: v2025.9.16)
마크업
<syn_fileclient id="sfcCompanyImage" syn-datafield="CompanyImage" syn-options="{
repositoryID: 'BDLLP01',
dialogTitle: '회사 이미지 업로드'
}"></syn_fileclient>
controlLoad 실행 시 다음이 일어납니다.
fileManagerServer+fileManagerPath(기본/repository/api/storage) +pageGetRepository(기본get-repository) 경로로 서버에repositoryID의 저장소 정보를 조회합니다.- 조회 결과(
RepositoryName,UploadType,UploadExtensions,UploadCount,UploadSizeLimit등)를setting에 병합하고,UploadType(Single/Profile/Multi/ImageLink)에 따라 실제 업로드 팝업이 열 페이지(uploadUrl)를 결정합니다. - 원본
<syn_fileclient>엘리먼트는id가<elID>_hidden으로 바뀌고display:none처리되며, 그 자리에 실제 값을 담는<input type="hidden" id="<elID>">가 새로 생성됩니다. 이 hidden input의value가 업로드된 파일의ItemID(다중이면 콤마로 연결한 문자열)입니다. - 저장소 조회에 실패하면(등록되지 않은
repositoryID등) 경고창과 함께uploadUrl이 비워집니다.
Options (defaultSetting)
| 옵션명 | 타입 | 기본값 | 설명 |
|---|---|---|---|
elementID | string | null | null | 내부적으로 자동 설정되는 엘리먼트 ID (직접 지정할 필요 없음) |
dialogTitle | string | '파일 업로드' | 업로드 팝업 제목. 저장소 조회 후 RepositoryName으로 자동 대체됨 |
tokenID | string | '' | 다운로드 시 사용하는 토큰 값 |
repositoryID | string | '' | 필수. 서버에 등록된 저장소(업로드 정책) ID. 이 값에 따라 업로드 방식/허용 확장자/개수/용량 제한이 결정됨 |
dependencyID | string | '' | 업로드된 파일이 속하는 소속 키(예: 게시글 ID, 사용자 ID 등). 업로드/조회/삭제 시 이 값으로 파일 그룹을 구분 |
businessID | string | '' | 내부적으로 사용되는 사업장/회사 구분 값(대부분 자동 결정됨) |
applicationID | string | '' | 내부적으로 사용되는 애플리케이션 구분 값(대부분 자동 결정됨) |
fileUpdateCallback | string | null | null | 업로드 완료 후 호출할 콜백 함수명. 페이지 스크립트의 event.<이름> 또는 $this.event.<이름>에서 찾음. 시그니처: callback(action, result) |
accept | string | '*/*' | 허용 파일 확장자(MIME 패턴). 저장소 조회 후 서버의 UploadExtensions로 대체됨 |
uploadUrl | string | '' | 실제 업로드 팝업 페이지 경로. 저장소의 UploadType에 따라 자동 결정됨(Single→upload/SingleFile.html, Profile→upload/ProfilePicture.html, Multi→upload/MultiFiles.html, ImageLink→upload/ImageLinkFiles.html) |
fileChangeHandler | function | undefined | undefined | 파일 선택 변경 시 직접 연동할 핸들러(저수준 API, 일반적인 사용에서는 잘 쓰이지 않음) |
custom1, custom2, custom3 | any | undefined | undefined | 업로드 요청에 함께 전달되는 사용자 정의 경로/값(서버에서 custompath1~3으로 수신) |
minHeight | number | 360 | 업로드 팝업 다이얼로그의 최소 높이(px). uploadUI 호출 시 오버라이드하는 경우가 많음 |
fileManagerServer | string | '' | 파일 저장소 API 서버 주소. 비어 있으면 syn.Config.FileManagerServer 값을 사용 |
fileManagerPath | string | '/repository/api/storage' | 파일 저장소 API 기본 경로 |
pageGetRepository | string | 'get-repository' | 저장소 정보 조회 API 경로명 |
pageUploadFile | string | 'upload-file' | 단일 파일 업로드(Blob/DataUri 등) API 경로명 |
pageUploadFiles | string | 'upload-files' | 다중 파일 업로드(폼 submit) API 경로명 |
pageActionHandler | string | 'action-handler' | 조회/변경(GetItem, GetItems, UpdateDependencyID, UpdateFileName 등) API 경로명 |
pageRemoveItem | string | 'remove-item' | 단일 항목 삭제 API 경로명 |
pageRemoveItems | string | 'remove-items' | 복수 항목 삭제 API 경로명 |
pageDownloadFile | string | 'download-file' | 파일 다운로드(POST + Blob 응답) API 경로명 |
pageHttpDownloadFile | string | 'http-download-file' | iframe 기반 직접 다운로드 API 경로명 |
pageVirtualDownloadFile | string | 'virtual-download-file' | 가상 경로 파일 다운로드 API 경로명 |
pageVirtualDeleteFile | string | 'virtual-delete-file' | 가상 경로 파일 삭제 API 경로명 |
sharedAssetUrl | string | '' | 업로드 팝업 페이지(html)들이 위치한 공유 자산 경로. 비어 있으면 syn.Config.SharedAssetUrl 사용 |
dataType | string | 'string' | 값의 데이터 타입 |
belongID | string | string[] | null | null | 이 필드가 속한 트랜잭션 함수 ID |
getter | boolean | function | false | 값을 가져올 때 커스텀 변환 함수 |
setter | boolean | function | false | 값을 설정할 때 커스텀 변환 함수 |
controlText | string | null | null | 컨트롤 라벨/설명 텍스트(검증 메시지 등에 사용) |
validators | array | null | null | 값 검증 규칙 |
transactConfig | object | null | null | 트랜잭션 관련 설정 |
triggerConfig | object | null | null | 다른 컨트롤에 의해 트리거되는 동작 설정 |
저장소 조회 응답을 통해 추가로 채워지는 값(직접 지정하지 않아도 됨): storageType, isMultiUpload, isAutoPath, policyPathID, uploadType, uploadExtensions, uploadCount, uploadSizeLimit.
메서드
| 메서드 | 시그니처 | 설명 |
|---|---|---|
controlLoad | controlLoad(elID, setting) | 컨트롤 초기화(마크업 상 <syn_fileclient>가 자동으로 호출) |
getValue | getValue(elID, meta) | hidden input의 현재 값(ItemID, 다중이면 콤마로 연결된 문자열) 반환 |
setValue | setValue(elID, value, meta) | hidden input 값을 직접 지정(예: 서버에서 내려온 기존 ItemID로 초기화할 때) |
clear | clear(elID, isControlLoad) | hidden input 값을 빈 문자열로 초기화 |
getFileSetting | getFileSetting(elID) | 해당 컨트롤의 저장소 조회가 끝난 뒤 저장된 옵션 객체(복제본)를 반환. 업로드를 열기 전에 이 메서드로 기본 옵션을 가져와 필요한 값만 덮어쓰는 것이 표준 패턴 |
getFileManagerSetting | getFileManagerSetting() | 페이지에 등록된 첫 번째 FileClient 컨트롤의 설정을 반환(공용 API 경로 계산 등에 사용되는 내부 헬퍼) |
setPageSetting | setPageSetting(pageSettings) | 페이지의 모든 FileClient 컨트롤에 대해 API 경로명(pageUploadFile 등)을 일괄 재정의 |
uploadUI | uploadUI(uploadOptions) | uploadOptions.repositoryID/uploadUrl이 설정된 업로드 옵션으로 업로드 팝업 다이얼로그를 연다. repositoryID 또는 uploadUrl이 비어 있으면 경고 후 중단 |
fileDownload | fileDownload(elIDOrOptions) | 파일을 다운로드한다. 문자열(elID)을 넘기면 그 컨트롤의 현재 값(ItemID)을 다운로드하고, 객체 설정 객체를 넘기면 임의의 파일을 다운로드(다중 업로드에서 특정 항목만 받을 때 사용) |
httpDownloadFile | httpDownloadFile(repositoryID, itemID, fileMD5, tokenID) | 숨김 iframe의 src를 설정해 브라우저가 직접 처리하는 방식으로 다운로드(팝업 차단 등에 영향받지 않는 대안) |
virtualDownloadFile | virtualDownloadFile(repositoryID, fileName, subDirectory) | 저장소에 등록되지 않은 가상 경로의 파일을 다운로드 |
virtualDeleteFile | virtualDeleteFile(repositoryID, fileName, subDirectory) | 가상 경로의 파일을 삭제 |
getItem | getItem(elID, itemID, callback) | 업로드된 파일 1건의 상세 정보 조회. callback(result) |
getItems | getItems(elID, dependencyID, callback) | dependencyID에 속한 업로드 파일 목록 조회. callback(result) |
deleteItem | deleteItem(elID, itemID, callback) | 파일 1건 삭제. 삭제 성공 시 컨트롤 값(ItemID 목록)에서 해당 항목을 자동으로 제거. callback(response) |
deleteItems | deleteItems(elID, dependencyID, callback) | dependencyID에 속한 파일 전체 삭제. 성공 시 컨트롤 값을 빈 문자열로 초기화. callback(response) |
updateDependencyID | updateDependencyID(elID, sourceDependencyID, targetDependencyID, callback) | 임시로 업로드한 파일들의 소속 키(dependencyID)를 실제 키로 변경(예: 신규 등록 화면에서 임시 ID로 올려두고, 저장 시 실제 PK로 변경) |
updateFileName | updateFileName(elID, itemID, fileName, callback) | 업로드된 파일의 파일명을 변경 |
uploadBlob | uploadBlob(options, callback) | Blob 객체를 직접 업로드(팝업 없이). options: {repositoryID, dependencyID, blobInfo, mimeType, fileName} |
uploadDataUri | uploadDataUri(options, callback) | Data URI(data:...;base64,...) 문자열을 Blob으로 변환 후 업로드. options: {repositoryID, dependencyID, dataUri, fileName} |
uploadBlobUri | uploadBlobUri(options, callback) | Blob URL(blob:...)을 Blob으로 변환 후 업로드. options: {repositoryID, dependencyID, blobUri, fileName} |
fileUpload | fileUpload(el, repositoryID, dependencyID, callback, uploadUrl) | <input type="file"> 엘리먼트(또는 그 id)의 선택된 파일들을 팝업 없이 즉시 업로드(저수준 API) |
getTemporaryDependencyID | getTemporaryDependencyID(prefix) | 신규 등록 화면 등에서 실제 PK가 없을 때 사용할 임시 dependencyID를 생성(GUID 또는 prefix + 랜덤값) |
getRepositoryID / getDependencyID / setDependencyID | (elID) / (elID, dependencyID) | init/addFileUI 기반의 구형 다중 첨부 UI(fileManagers)에서 저장소/소속 키를 조회·변경하는 내부 헬퍼 |
toFileLengthString | toFileLengthString(fileLength) | 바이트 크기를 '123 KB'/'1.2 MB' 형태 문자열로 변환 |
setLocale | setLocale(elID, translations, control, options) | 다국어 텍스트 적용(현재 구현은 빈 함수) |
callback인자를 받는 메서드(getItem,getItems,deleteItem,deleteItems,updateDependencyID,updateFileName,uploadBlob,uploadDataUri,uploadBlobUri,fileUpload)는callback을 생략하면 동일한 결과로 resolve되는Promise를 반환합니다(await사용 가능). 요청 실패·검증 실패 시null로 resolve 됩니다.
init, addFileUI, getFileManager, getFileMaxIndex, prependChild, doUpload, getUploadUrl, getFileAction, executeProxy, getFileMimeType는 팝업 없이 폼에 파일 입력행을 직접 추가하는 구형(레거시) 다중 첨부 UI를 위한 내부 구현 세부사항입니다. 신규 화면에서는 getFileSetting + uploadUI 조합을 사용하는 것이 표준 패턴이며, 위 내부 메서드들을 직접 호출할 일은 거의 없습니다.
이벤트 (syn-events)
FileClient가 실제로 화면에 렌더링하는 것은 <input type="hidden">이므로, 일반적인 syn-events="['change']" 방식의 네이티브 DOM 이벤트 와이어링은 값 변경 시점을 감지하는 용도로는 사용되지 않습니다(업로드 완료 시 el.value가 코드로 직접 대입되며 change 이벤트가 발생(dispatch)되지 않습니다).
대신 값이 바뀌는 시점(업로드 완료)을 알아야 한다면 fileUpdateCallback 옵션을 사용하세요.
uploadOptions.fileUpdateCallback = 'sfcCompanyImage_callback';
syn.uicontrols.$fileclient.uploadUI(uploadOptions);
이 콜백은 업로드 팝업(iframe)이 부모 창으로 postMessage를 보내면, $fileclient가 이를 가로채(window의 message 이벤트) 페이지 스크립트 객체(window[syn.$w.pageScript])의 event.<콜백이름> 함수를 찾아 (action, result) 형태로 호출하는 방식으로 동작합니다. 콜백이 호출되고 나면 열려 있던 업로드 다이얼로그도 자동으로 닫힙니다($.modal.close()).
참고: 업로드 콜백(fileUpdateCallback) 결과 객체 구조
콜백은 callback(action, result) 형태로 호출되며, 업로드 완료 시 action은 'upload', result는 다음 구조입니다.
{
elID: 'sfcCompanyImage', // 업로드를 요청한 컨트롤의 엘리먼트 ID
repositoryID: 'BDLLP01', // 업로드된 저장소 ID
items: [ // 업로드된 파일 목록(다중 업로드면 여러 건)
{
ItemID: 'e9259ffe12534c83957906bdb2ff7d6b',
AbsolutePath: 'https://.../e9259ffe12534c83957906bdb2ff7d6b.png',
// 그 외 서버가 내려주는 파일 메타데이터 필드(파일명, 크기, 저장 경로 등)
}
// ...
]
}
콜백 처리와 별개로, $fileclient는 업로드된 항목들의 ItemID를 콤마로 연결해 자동으로 원본 hidden input(elID)의 value에 채워 넣습니다. 즉 getValue(elID)만 호출해도 업로드 결과(ItemID 목록)를 즉시 얻을 수 있으며, fileUpdateCallback은 주로 업로드 직후 화면에 파일명/미리보기 등을 갱신하거나 후속 처리를 트리거하는 용도로 사용합니다.