1. 라이센스
이 플러그인은 MIT 라이센스로 배포됩니다.
개인 및 상업적 프로젝트 모두 자유롭게 사용, 수정, 배포할 수 있습니다.
단, 원본 저작권 표시는 유지해야 합니다.
2. 특징 및 설명
bsTimepicker는 jQuery와 Bootstrap을 기반으로 동작하는 원형 시계 다이얼 방식의 시간 선택기 플러그인입니다. 모바일 알람 앱에서 볼 수 있는 원형 다이얼 UI를 웹 폼에 그대로 구현할 수 있으며, Bootstrap의 드롭다운 컴포넌트를 활용하여 기존 Bootstrap 기반 프로젝트에 자연스럽게 통합됩니다.
지원 환경
jQuery 3.x 이상 / Bootstrap 4.6.x 또는 5.x / Bootstrap Icons
주요 기능
· 24시간(HH:mm) 및 12시간(AM/PM) 표시 모드 지원
· 마우스 클릭 및 터치 드래그로 조작 가능한 원형 시계 다이얼
· input 요소, div 요소, Bootstrap form-floating 컨테이너 모두 지원
· 분 선택 간격 설정 가능 (1분 / 5분 / 10분 / 15분 단위)
· 데이터베이스 저장에 바로 사용 가능한 24시간 형식(HH:mm) 값 반환
· div에 초기화 시 숨김 input 자동 생성 (nameField 옵션)
· 취소 또는 외부 클릭 시 이전 값으로 자동 복원
· 트리거 버튼 스타일, 너비, 아이콘 자유 커스터마이징
· 클리어 버튼 표시 여부 및 레이블 커스터마이징
· minuteInterval 설정 후 자동 닫기 옵션(closeOnSelect)
· show / hide / toggle / setTime / getTime / val / clear / destroy 공개 API 제공
· 초기화, 열림/닫힘, 값 변경 등 세분화된 이벤트 훅 지원
3. 설치 방법 & 사용 방법
설치 방법
아래 순서대로 CSS와 JS 파일을 HTML 문서에 불러옵니다. Bootstrap Icons는 기본 트리거 아이콘에 필수입니다.
<!-- Bootstrap CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">
<!-- Bootstrap Icons -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.css">
<!-- jQuery -->
<script src="https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js"></script>
<!-- Bootstrap Bundle (Popper.js 포함) -->
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
<!-- bsTimepicker 플러그인 -->
<script src="dist/bs-timepicker.js"></script>
기본 사용법 — input 요소 (24시간)
<input type="text" id="meetingStart" value="09:00"> $("#meetingStart").bsTimepicker({ format: "24h" });
기본 사용법 — input 요소 (12시간 AM/PM)
기본 사용법 — input 요소 (12시간 AM/PM) <input type="text" id="reminderTime" value="10:30 AM"> $("#reminderTime").bsTimepicker({ format: "12h" });
기본 사용법 — div 요소 (숨김 input 자동 생성)
<div id="shiftStart"></div> $("#shiftStart").bsTimepicker({ format: "24h", defaultTime: "07:30", nameField: "shift_start", btnClass: "btn btn-primary", btnWidth: "200px", btnEmptyText: "시간을 선택하세요" });
전체 옵션 목록
format (기본값: "24h") — "24h" 또는 "12h" 중 선택합니다.
minuteInterval (기본값: 5) — 분 선택 단위. 1, 5, 10, 15 중 선택.
defaultTime (기본값: null) — 초기값이 없을 때 사용할 기본 시간. "14:00", "02:00 PM", new Date(), { hour24: 14, minute: 0 } 형식 모두 허용.
nameField (기본값: null) — div에 초기화할 때 생성할 숨김 input의 name 속성값.
title (기본값: "Select time") — 드롭다운 상단에 표시할 제목. null 또는 빈 문자열로 숨길 수 있음.
closeOnSelect (기본값: false) — true로 설정 시 분 선택 후 자동으로 닫힘.
btnClass (기본값: "btn btn-outline-secondary") — 트리거 버튼에 적용할 Bootstrap 클래스.
btnWidth (기본값: null) — 트리거 버튼의 고정 너비. 예: "220px".
btnEmptyText (기본값: "--:--") — 값이 없을 때 트리거에 표시할 안내 문구.
showClearButton (기본값: true) — 클리어 버튼 표시 여부.
clearLabel — 클리어 버튼 레이블. HTML 사용 가능.
icons.trigger (기본값: "bi bi-clock") — 트리거 버튼 아이콘 클래스.
okLabel — 확인 버튼 레이블. HTML 사용 가능.
cancelLabel — 취소 버튼 레이블. HTML 사용 가능.
공개 API 메서드
// 현재 시간을 구조화된 객체로 반환 const data = $("#meetingStart").bsTimepicker("getTime"); // 반환: { hour24, minute, hour12, meridiem, formatted24, formatted12, isEmpty } // 저장된 값을 "HH:mm" 문자열로 반환 (값 없으면 null) const val = $("#meetingStart").bsTimepicker("val"); // 값 설정 (변경 이벤트 미발생) $("#meetingStart").bsTimepicker("val", "16:45"); // 값 설정 (변경 이벤트 발생) $("#meetingStart").bsTimepicker("setTime", "11:00"); // 값 초기화 (변경 이벤트 발생) $("#meetingStart").bsTimepicker("clear"); // 드롭다운 열기 / 닫기 / 토글 $("#meetingStart").bsTimepicker("show"); $("#meetingStart").bsTimepicker("hide"); $("#meetingStart").bsTimepicker("toggle"); // 플러그인 제거 및 생성된 DOM 정리 $("#meetingStart").bsTimepicker("destroy");
4. 기타 참고 사항
원본 사이트에서 다운로드 받은 파일은 vendor 가 누락되어서 정상 작동하지 않습니다.
수정된 버젼을 첨부해 두었으니 소스다운로드 버튼을 클릭하여 다운로드 받아주세요.
demo/index2.html 파일을 실행하시거나 확인하시기 바랍니다.
|
