TimePicker
세그먼트 + 드롭다운으로 시간을 선택하는 폼 컴포넌트
개요
iCignal TimePicker는 Foundation TimePicker를 FormItem으로 래핑하여 레이블, 필수값, 설명, 에러 메시지를 통합 제공합니다. 폼 내에서 시간 입력 필드로 사용할 수 있습니다.
주요 특징
- ✅ 필수값 표시: Label 좌측에 *(Asterisk) 표시
- ✅ 단일 input + 드롭다운: 시·분·초를 하나의 input에서 입력하거나 드롭다운에서 선택
- ✅ 자동 마스킹: 숫자만 타이핑해도
HH:MM[:SS]형식으로 콜론 자동 삽입 - ✅ 12 / 24시간제:
use12Hourprop으로 전환 - ✅ AM/PM 라벨 커스터마이즈:
amLabel·pmLabel로 다국어 텍스트 지원 (기본AM/PM) - ✅ 초 선택:
showSeconds로 초까지 선택 - ✅ 간격 설정:
minuteStep,secondStep - ✅ 오류 상태:
error로 메시지 표시 및 포커스 링 강조 - ✅ 읽기 전용 / 비활성화:
readOnly,disabled - ✅ 다양한 크기: xs, sm, md, lg, xl
- ✅ FormItem 통합: 레이블, 설명, 에러 메시지
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Sizes
Preview
States
Preview
24시간 형식 · 15분 단위
사용 예시
필수값 표시
필수 입력 항목은 Label 좌측에 *(Asterisk)를 표시합니다.
Preview
12시간제 / 24시간제
기본값은 12시간제(AM/PM)이며, use12Hour={false}로 24시간제로 전환할 수 있습니다.
Preview
AM / PM 라벨 커스터마이즈
amLabel / pmLabel prop으로 오전·오후 표시 텍스트를 변경할 수 있습니다. 기본값은 "AM" / "PM"입니다.
Preview
초 표시
showSeconds로 초까지 선택할 수 있는 세그먼트와 컬럼이 추가됩니다.
Preview
분 / 초 간격 설정
minuteStep, secondStep으로 드롭다운 옵션 간격을 조절합니다. 예약 시간처럼 특정 단위만 허용할 때 유용합니다.
Preview
오류 상태 표시
error prop으로 오류 메시지를 표시합니다. 포커스 링이 에러 색상으로 강조됩니다.
Preview
레이블 레이아웃
orientation="vertical"로 레이블을 상단에 배치할 수 있습니다.
Preview
예시 1: 회의 예약 시간
15분 단위로 회의 시작/종료 시각을 예약합니다.
Preview
예시 2: 배치 작업 스케줄
초 단위까지 정밀하게 스케줄을 설정합니다.
Preview
초 단위 정밀 스케줄
키보드 직접 입력 (Key-in)
시·분·초는 하나의 <input type="text" inputMode="numeric"> 필드로 통합되어 있습니다. 숫자만 타이핑하면 HH:MM[:SS] 형식으로 콜론이 자동 삽입되며, 최대 자릿수(4 또는 6) 도달 시 즉시 commit됩니다. 부분 입력 상태에서는 Tab / blur 시점에 검증 후 commit되며, 유효하지 않으면 기존 값이 유지됩니다. 붙여넣기 · 전체 선택 · 백스페이스 같은 브라우저 기본 텍스트 편집이 모두 동작합니다. AM/PM은 별도 버튼으로 좌측에 유지되며 A/P 키 또는 클릭으로 지정합니다.
Preview
키보드 내비게이션
| 키 | 동작 |
|---|---|
0 – 9 | 단일 input에 숫자 타이핑 → 콜론(:) 자동 삽입, 최대 자릿수 도달 시 즉시 commit |
↑ / ↓ | 커서 위치의 세그먼트(시/분/초) 값 증감 (step 반영, 경계에서 wrap) |
← / → | input 내 커서 이동 (브라우저 기본) |
A / P | AM / PM 지정 (AM/PM 버튼 포커스 시) |
Backspace | input 문자 삭제 (브라우저 기본) |
Enter / Space | 드롭다운 토글 |
Esc | 열린 드롭다운 닫기 |
Tab / Shift+Tab | 다음/이전 포커스 가능 요소로 이동 (기본 동작) |
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | - | 선택된 시간 (제어 컴포넌트) |
defaultValue | Date | - | 초기 시간 |
use12Hour | boolean | true | 12시간제(AM/PM) 사용 여부 |
showSeconds | boolean | false | 초 세그먼트 표시 여부 |
minuteStep | number | 1 | 분 드롭다운 간격 |
secondStep | number | 1 | 초 드롭다운 간격 |
amLabel | string | "AM" | 오전(AM) 표시 텍스트 |
pmLabel | string | "PM" | 오후(PM) 표시 텍스트 |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 컴포넌트 크기 |
width | string | number | - | 트리거 너비 |
disabled | boolean | false | 비활성화 여부 |
readOnly | boolean | false | 읽기 전용 여부 |
label | string | - | 필드 레이블 |
labelWidth | string | number | - | 레이블 너비 |
labelAlign | "start" | "center" | "end" | - | 레이블 가로 정렬 |
labelVerticalAlign | "start" | "center" | "end" | - | 레이블 세로 정렬 |
align | "start" | "center" | "end" | - | 필드 영역 정렬 |
required | boolean | false | 필수 여부 (* 표시) |
orientation | "horizontal" | "vertical" | "horizontal" | 레이블-필드 배치 방향 |
description | string | - | 설명 텍스트 |
error | string | - | 에러 메시지 |
className | string | - | FormItem 래퍼에 적용할 CSS 클래스 |
inputClassName | string | - | TimePicker 트리거에 적용할 클래스 |
Events
| Event | Type | Description |
|---|---|---|
onChange | (value: Date | undefined) => void | 값 변경 시 호출 |
기본 사용법
import { TimePicker } from "@vortex/ui-icignal"
// 기본
<TimePicker label="시간" />
// 24시간제 + 15분 단위
<TimePicker label="시작" use12Hour={false} minuteStep={15} />
// 초 포함 + 필수
<TimePicker label="실행 시각" showSeconds required />접근성
ARIA 속성
<TimePicker label="시작 시각" required />권장 사항
- ✅
label로 시간 선택 목적 전달 - ✅
description/error로 맥락과 유효성 안내 - ✅ 키보드: Tab으로 세그먼트·아이콘 버튼 이동, ←/→로 세그먼트 간 이동, Esc로 드롭다운 닫기
- ✅ 실제
<input>기반 텍스트 입력 — 붙여넣기 / IME / 스크린리더 등 표준 입력 경로 지원 - ✅ ↑/↓로
step단위 증감, 경계에서 자동 wrap - ❌ 레이블 없이 단독 사용 지양
관련 컴포넌트
- TimePicker (Foundation): 기본 TimePicker
- DatePicker: 날짜 선택
- Input: 텍스트 입력
- InputNumber: 숫자 입력