TimePicker

세그먼트 + 드롭다운으로 시간을 선택하는 기본 컴포넌트

개요

Foundation TimePicker는 Popover 기반의 시간 선택 컴포넌트입니다. 오전/오후 · 시 · 분(· 초) 세그먼트를 개별 클릭해 드롭다운을 열고 값을 선택합니다. iCignal 레이어에서 FormItem(레이블/에러/필수 표시) 확장을 제공합니다.

주요 특징

• ✅ 세그먼트 선택: 오전/오후 · 시 · 분 · 초 세그먼트를 개별 클릭해 열기
• ✅ 키보드 직접 입력(Key-in): 시·분·초는 실제 <input> 필드로 네이티브 텍스트 타이핑 지원
• ✅ 12 / 24시간제: use12Hour prop으로 전환 (기본 12시간제)
• ✅ 초 선택: showSeconds로 초 세그먼트 및 컬럼 추가
• ✅ 간격 설정: minuteStep, secondStep으로 선택 간격 제어
• ✅ 제어/비제어: value/defaultValue 모두 지원
• ✅ 상태: disabled, readOnly, 포커스 링
• ✅ 다양한 크기: xs, sm, md, lg, xl
• ✅ 디자인 토큰: --input-* 토큰 상속, 테마 커스터마이징 지원

Sizes

<TimePicker size="xs" />
<TimePicker size="sm" />
<TimePicker size="md" />
<TimePicker size="lg" />
<TimePicker size="xl" />

사용 예시

기본 사용

각 세그먼트(오전/오후 · 시 · 분)를 클릭하면 드롭다운이 열리고 값을 선택합니다. 우측 아이콘 버튼은 시 세그먼트 드롭다운의 단축 토글입니다.

const [time, setTime] = useState<Date | undefined>()
 
<TimePicker value={time} onChange={setTime} width={200} />

기본값 설정

defaultValue로 초기값을 지정할 수 있습니다.

<TimePicker defaultValue={new Date(2025, 0, 1, 14, 30)} width={200} />

12시간제 / 24시간제

기본은 12시간제(AM/PM)입니다. use12Hour={false}로 24시간제로 전환하면 오전/오후 세그먼트가 사라집니다.

{/* 12시간제 (기본) */}
<TimePicker use12Hour defaultValue={new Date(2025, 0, 1, 9, 15)} />
 
{/* 24시간제 */}
<TimePicker use12Hour={false} defaultValue={new Date(2025, 0, 1, 21, 45)} />

초 표시

showSeconds로 초 세그먼트와 드롭다운 컬럼을 추가합니다.

<TimePicker showSeconds defaultValue={new Date(2025, 0, 1, 10, 30, 45)} />

분 / 초 간격 설정

minuteStep / secondStep으로 드롭다운 옵션 간격을 조절합니다.

<TimePicker minuteStep={5} />
<TimePicker minuteStep={15} />
<TimePicker showSeconds secondStep={10} />

너비 제어

width로 트리거 너비를 고정합니다.

<TimePicker width={160} />
<TimePicker width={220} showSeconds />

비활성화 / 읽기 전용

disabled는 전체 트리거를 비활성화하고, readOnly는 값을 유지한 채 선택만 차단합니다.

<TimePicker disabled defaultValue={new Date(2025, 0, 1, 12, 0)} />
<TimePicker readOnly defaultValue={new Date(2025, 0, 1, 9, 30)} />

키보드 직접 입력 (Key-in)

시·분·초 세그먼트는 실제 <input type="text" inputMode="numeric"> 필드로 구현되어, 일반 텍스트 입력처럼 숫자를 직접 타이핑할 수 있습니다. 붙여넣기 · 전체 선택 · 백스페이스 같은 브라우저 기본 텍스트 편집이 모두 동작합니다. 두 자리를 모두 채우면 해당 세그먼트를 확정하고 자동으로 다음 세그먼트로 포커스가 이동합니다. 한 자리만 입력하고 넘기려면 Tab / → / Enter를 누르거나 다른 곳을 클릭하면 됩니다. AM/PM은 텍스트 입력 대상이 아니므로 버튼으로 유지되며 A/P 키로 지정합니다.

{/* 12시간제: period → hours → minutes */}
<TimePicker width={200} />
 
{/* 24시간제 + 초: hours → minutes → seconds */}
<TimePicker width={220} use12Hour={false} showSeconds />

키보드 내비게이션

API Reference

Props

Events

기본 사용법

import { TimePicker } from "@vortex/ui-foundation"
 
<TimePicker />
<TimePicker use12Hour={false} showSeconds />
<TimePicker minuteStep={15} defaultValue={new Date()} />

접근성

권장 사항

• ✅ 키보드: Tab으로 세그먼트 및 아이콘 버튼 이동, ←/→로 세그먼트 간 이동
• ✅ 실제 <input> 기반 텍스트 입력 — 붙여넣기 / IME / 스크린리더 등 표준 입력 경로 지원
• ✅ ↑/↓로 step 단위 증감, 경계에서 자동 wrap
• ✅ 각 세그먼트는 aria-label을 포함하는 버튼으로 제공
• ✅ 드롭다운은 Popover 기반으로 포커스 트랩 및 Esc 닫기 지원
• ❌ 레이블/설명 없이 단독 사용은 iCignal 래퍼 사용 권장

관련 컴포넌트

• TimePicker (iCignal): FormItem 통합 래퍼 (label, required, error 등)
• DatePicker (Foundation): 날짜 선택
• Input (Foundation): 일반 텍스트 입력