[해피CGI][cgimall] Bootstrap용 원형 다이얼 시간 선택기 플러그인 - jQuery bsTimepicker

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 파일을 실행하시거나 확인하시기 바랍니다.