DatePicker
이 컨트롤은 무엇인가요?
DatePicker는 <syn_datepicker> 태그 하나로 "달력 아이콘 버튼 + 날짜 입력창"을 만들어 주는 레거시 내부 JS UI 컨트롤입니다.
실제 화면에서는 Pikaday 라이브러리를 내부적으로 사용해서 달력 팝업을 그리고, 선택한 날짜를 텍스트 입력창(input[type=text])에 채워 넣습니다.
syn.loader.js가 페이지에 있는 <syn_datepicker> 태그를 찾아서 자동으로 다음을 처리합니다.
DatePicker.js/DatePicker.css등 필요한 스크립트·스타 일 자동 주입- 원래 태그를 숨김 처리(
display: none)하고, 그 옆에 실제 보이는input과 달력 버튼을 생성 syn.uicontrols.$datepicker싱글턴 객체에 컨트롤 정보 등록 (getValue/setValue/clear등으로 제어 가능)
이름은 $datepicker 이지만, 페이지에서 사용하는 태그명은 syn_datepicker 입니다. 이 문서 전체에서 "DatePicker 컨트롤"이라 하면 이 둘을 함께 가리킵니다.
언제 사용하나요?
- 회원 가입일, 계약일, 마감일처럼 날짜 1개만 입력받아야 할 때 사용합니다.
- 조회 시작일/종료일처럼 날짜 2개(기간) 를 하나의 짝으로 다루어야 한다면
DatePicker를 2개 두고useRangeSelect옵션으로 서로 연동시키거나(아래 API.md 참고), 또는 형제 컨트롤인DatePeriodPicker(syn.uicontrols.$dateperiodpicker) 를 사용하는 것이 더 간단합니다.DatePeriodPicker는 시작일~종료일을 하나의 컨트롤에서 한 번에 관리하도록 설계된 별도 컨트롤입니다. - 요약하면:
- 날짜 1개, 단순 입력 →
DatePicker - 날짜 1개씩이지만 두 개를 서로 최소/최대로 연동하고 싶다 →
DatePicker+useRangeSelect - 처음부터 "기간(period)" 개념으로 다루고 싶다 →
DatePeriodPicker
- 날짜 1개, 단순 입력 →
빠른 시작
<form autocomplete="off" id="form1" syn-datafield="MainForm">
<syn_datepicker id="dtpBirthday" syn-datafield="Birthday"></syn_datepicker>
</form>
<script src="/js/syn.loader.js"></script>
이렇게만 작성해도 syn.loader.js가 알아서 필요한 리소스를 불러오고, 화면에는 텍스트 입력창과 달력 아이콘 버튼이 나타납니다. 버튼을 누르면 달력이 열리고, 날짜를 클릭하면 입력창에 값이 채워집니다.
값을 코드로 다루고 싶다면 아래처럼 syn.uicontrols.$datepicker를 사용합니다.
// 값 읽기
var value = syn.uicontrols.$datepicker.getValue('dtpBirthday'); // 예: '2026-07-06'
// 값 설정
syn.uicontrols.$datepicker.setValue('dtpBirthday', '2026-01-01');
// 값 초기화
syn.uicontrols.$datepicker.clear('dtpBirthday');
예제 실행하기
이 폴더의 example 하위 폴더에 있는 HTML 파일을 웹서버(예: rdy 실행 중인 wwwroot)를 통해 브라우저로 열어보세요. file://로 직접 열면 syn.loader.js가 정상 동작하지 않을 수 있으니 반드시 프로젝트를 실행한 상태에서 접속해야 합니다.
example/basic.html: 가장 단순한 날짜 1개 선택 예제example/format.html:format,minDate,maxDate등 옵션 예제example/datetime.html:useTime,minuteStep으로 날짜와 시간(HH:mm)을 함께 선택하는 예제example/events.html: 선택(onselect) 이벤트,getValue/setValue/clear버튼 데모example/leaverequest.html: 휴가 신청 실무 패턴 - 시작일/종료일DatePicker2개를 두고onselect에서$date.parseDate/$date.diff로 휴가 일수를 자동 계산, 저장 전 두 값 모두 필수값 검증example/features.html: 전체 기능 확인 - 모든 옵션/메서드/이벤트를 한 화면에서 확인하는 예제example/practical.html: 회의실 예약 화면(실무형) - 실무 화면 패턴(조회 조건/목록/검증/저장)을 반영한 예제
각 HTML은 같은 이름의 .js 파일과 짝을 이루며, 화면 하단 로그 영역에 syn.$l.eventLog로 동작 로그가 출력됩니다.
더 알아보기
- 상세 옵션·메서드·이벤트 표는 아래 API 참조 섹션 문서를 참고하세요.
- 달력 팝업 자체의 세부 동작(연/월 이동, 다중 월 표시 등)은 내부적으로 사용하는 Pikaday 라이브러리 문서를 참고하세요: https://github.com/Pikaday/Pikaday
- 기간(시작일~종료일)을 한 번에 다루려면 형제 컨트롤
DatePeriodPicker(syn.uicontrols.$dateperiodpicker)를 확인하세요.
실전 예제 페이지
/uicontrols/DatePicker/example/ 경로의 예제를 아래 iframe에서 바로 확인할 수 있습니다.
basic.html
events.html
format.html
leaverequest.html
datetime.html
features.html
practical.html
소스와 로드 파일
| 항목 | 내용 |
|---|---|
| 컨트롤 | DatePicker |
| 전역 별칭 | syn.uicontrols.$datepicker |
| 버전 | v2026.10.1 |
| 소스 | uicontrols/DatePicker/DatePicker.js |
| 스타일 | uicontrols/DatePicker/DatePicker.css |
API 참조
소스 근거:
uicontrols/DatePicker/DatePicker.js(syn.uicontrols.$datepicker, versionv2025.10.1)
마크업
<syn_datepicker
id="dtpTourDate"
syn-datafield="TourDate"
syn-options="{belongID: ['UD01', 'MD01']}">
</syn_datepicker>
id: 컨트롤 식별자. 필수. 이 id로getValue/setValue/clear/getControl을 호출합니다.syn-datafield: 폼 전송/바인딩 시 사용할 데이터 필드명. 생략 가능.syn-options: 아래 "Options" 표의 값을 JSON 형태 문자열로 지정. 생략 가능.syn-events: 내부적으로 생성되는 실제input요소에 그대로 전달됩니다(예:['change']). 다만 날짜 선택 관련 이벤트는 아래 "이벤트" 절의{elID}_onselect관례를 사용하는 것을 권장합니다.
로더가 처리한 뒤 실제 DOM 구조는 다음과 같이 바뀝니다.
- 원래
<syn_datepicker id="dtpTourDate">태그 →id="dtpTourDate_hidden"으로 변경되고display:none처리(내부 설정 보관용) - 그 자리에 실제 보이는
<input id="dtpTourDate" type="text">생성 (마스크9999-99-99,editType: 'date'자동 적용) - 바로 뒤에 달력 아이콘 버튼
<button id="dtpTourDate_Button">생성
Options (defaultSetting)
| 옵션 | 타입 | 기본값 | 설명 |
|---|---|---|---|
elID | string | '' | 내부적으로 자동 설정됨(직접 지정 불필요) |
width | string | '100%' | 컨트롤 너비 |
value | string | '' | 초기값. 'now', 'day:N', 'week:N', 'month:N', 'year:N' 형태 지정 가능(N은 양/음수). 예: 'day:-7' → 오늘 기준 7일 전 |
placeholder | string | '' | 입력창 placeholder. 값이 없을 때(달력 닫힘 시점 기준) 자동 적용 |
defaultDate | Date/null | null | 달력을 열었을 때 기본으로 표시할 날짜(Pikaday 옵션) |
setDefaultDate | boolean | false | true면 defaultDate를 실제 선택값으로도 사용 |
minDate | Date/null | null | 선택 가능한 최소 날짜 |
maxDate | Date/null | null | 선택 가능한 최대 날짜 |
bound | boolean | true | 입력 필드에 종속되어 포커스/클릭 시 달력을 여닫을지 여부(Pikaday 옵션) |
format | string | 'YYYY-MM-DD' | 표시 날짜 포맷(moment.js 포맷 문자열). useTime: true이면 'YYYY-MM-DD HH:mm'로 고정됨 |
useTime | boolean | false | true로 설정하면 날짜와 함께 시간(HH:mm)까지 관리. 달력 아래에 시/분 선택 영역과 "확인" 버튼이 표시되고, 입력창은 YYYY-MM-DD HH:mm 형식(마스크 9999-99-99 99:99)이 됨. 날짜를 클릭해도 팝업이 닫히지 않으므로 시간을 고른 뒤 "확인" 버튼이나 바깥 영역 클릭으로 닫음 |
minuteStep | number | 1 | useTime: true일 때 분 선택 간격(예: 5, 10, 30). 직접 입력하거나 setValue로 지정한 분은 간격과 달라도 그대로 유지됨 |
ariaLabel | string | '날짜를 선택 하세요' | 접근성 라벨 |
i18n | object | 한국어 월/요일 명 세트 | 달력에 표시할 월/요일 이름(직접 바꿀 일은 거의 없음) |
showWeekNumber | boolean | false | 주차 번호 표시 여부 |
showMonthAfterYear | boolean | true | 헤더에서 "연도 뒤에 월" 표시 순서 |
showDaysInNextAndPreviousMonths | boolean | true | 이전/다음 달 날짜를 회색으로 함께 표시할지 여부 |
enableSelectionDaysInNextAndPreviousMonths | boolean | true | 이전/다음 달의 흐린 날짜도 클릭 선택 가능하게 할지 여부 |
yearSuffix | string | '년' | 연도 뒤에 붙는 접미사 |
firstDay | number | 0 | 한 주의 시작 요일(0=일요일) |
useRangeSelect | boolean | false | true로 설정하면 다른 DatePicker와 시작일/종료일로 연동(2개 이상 짝) |
rangeStartControlID | string/null | null | useRangeSelect: true일 때 시작일 컨트롤 id. 생략 시 자기 자신 id |
rangeEndControlID | string/null | null | useRangeSelect: true일 때 종료일 컨트롤 id. 생략 시 자기 자신 id |
numberOfMonths | number | 1 | 달력에 동시에 표시할 개월 수 |
dataType | string | 'string' | 값 데이터 타입 |
belongID | string/array/null | null | 하위 텍스트박스 컨트롤에 전달되는 소속 그룹 식별자(예: 컨테이너/폼 그룹 연동용). 값이 있으면 배열/문자열 여부에 따라 자동으로 JSON 처리되어 내부 input의 syn-options에 전달됨 |
getter | boolean | false | 값 조회 시 커스텀 처리 여부(프레임워크 공통 옵션) |
setter | boolean | false | 값 설정 시 커스텀 처리 여부(프레임워크 공통 옵션) |
controlText | any/null | null | 표시용 텍스트 커스터마이즈(프레임워크 공통 옵션) |
validators | any/null | null | 유효성 검사 규칙(프레임워크 공통 옵션) |
transactConfig | any/null | null | 트랜잭션 연동 설정(프레임워크 공통 옵션) |
triggerConfig | any/null | null | 트리거 연동 설정(프레임워크 공통 옵션) |
useRangeSelect사용 예:시작일을 선택하면 종료일의
minDate가 자동으로 갱신되고, 종료일을 선택하면 시작일의maxDate가 자동으로 갱신됩니다.
useTime사용 예:
getValue는'2026-10-15 14:30'처럼 시간이 포함된 문자열을 반환합니다. 시간을 고르지 않고 날짜만 선택하면00:00이 사용되며,useTime을 켠 상태에서useRangeSelect를 함께 쓰면 연동 범위(minDate/maxDate)는 날짜 단위로만 적용됩니다(같은 날짜의 시각 선후 검증은 하지 않음).
메서드
| 메서드 | 시그니처 | 설명 |
|---|---|---|
getValue | getValue(elID, meta) | 입력창(실제 input)에 표시된 현재 값을 문자열로 반환 |
setValue | setValue(elID, value, meta) | 지정한 값으로 날짜를 설정(Pikaday setDate 사용). value는 Date 객체 또는 파싱 가능한 날짜 문자열. useTime: true이면 '2026-10-15 14:30', '2026-10-15' 형식 문자열이나 Date의 시/분까지 반영 |
clear | clear(elID, isControlLoad) | 선택값을 초기화(Pikaday clear 사용). useTime: true이면 시간도 00:00으로 되돌림 |
getControl | getControl(elID) | 객체 설정 형태의 내부 컨트롤 객체 반환. picker는 Pikaday 인스턴스(Pikaday 메서드 문서 참고: getDate(), setDate(), show(), hide(), setMinDate(), setMaxDate() 등) |
updateRangeDate | updateRangeDate(elID, date) | useRangeSelect 연동 컨트롤 간 날짜 갱신(내부용, 직접 호출할 일 거의 없음) |
setLocale | setLocale(elID, translations, control, options) | 로케일 훅(현재 구현은 비어 있음 — 다국어 전환 시 확장 지점) |
이벤트 (syn-events)
DatePicker는 다른 컨트롤처럼 syn-events 속성에 이벤트 이름을 나열하는 방식이 아니라, 페이지 스크립트의 event 객체에 {elID}_onselect 함수를 정의해두면 자동으로 호출되는 관례를 사용합니다.
| 이벤트(관례 함수명) | 호출 시점 | 콜백 인자 |
|---|---|---|
{elID}_onselect(elID, date) | 달력이 열릴 때(onOpen), 닫힐 때(onClose), 날짜를 클릭해 선택할 때(onSelect) 모두 동일하게 호출됨 | elID : 컨트롤 id(string), date : 현재 Pikaday getDate() 결과(Date 객체, 선택 안 됐으면 null일 수 있음). useTime: true이면 선택한 시/분이 반영된 Date이며, 시/분을 바꿀 때도 호출됨 |
예:
let $mypage = {
event: {
dtpTourDate_onselect(elID, date) {
syn.$l.eventLog('dtpTourDate_onselect', elID + ' => ' + date);
}
}
}
이 외에 실제 생성되는 input 요소는 텍스트박스 컨트롤(syn.uicontrols.$textbox)의 표준 이벤트(change 등)도 syn-events 속성을 통해 그대로 사용할 수 있습니다.