TimePicker#

시간(시·분·초)을 선택할 수 있는 시간 선택기 컴포넌트입니다. 12시간/24시간 형식과 선택적인 초 표시를 지원합니다.

Live Preview#

기본 (popover)#

class TimePickerDefaultExample extends StatefulComponent {
  const TimePickerDefaultExample({super.key});

  @override
  State<TimePickerDefaultExample> createState() =>
      _TimePickerDefaultExampleState();
}

class _TimePickerDefaultExampleState extends State<TimePickerDefaultExample> {
  String? _value;

  @override
  Component build(BuildContext context) {
    return div(
      [
        TimePicker(
          value: _value,
          placeholder: 'Select time',
          onChanged: (value) => setState(() => _value = value),
        ),
      ],
      classes: 'w-${CoreSpace.scale.space256}',
    );
  }
}

class TimePickerDefaultExample extends StatefulWidget {
  const TimePickerDefaultExample({super.key});

  @override
  State<TimePickerDefaultExample> createState() =>
      _TimePickerDefaultExampleState();
}

class _TimePickerDefaultExampleState extends State<TimePickerDefaultExample> {
  String? _value;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: CoreSpace.space256,
      child: TimePicker(
        value: _value,
        placeholder: 'Select time',
        onChanged: (value) => setState(() => _value = value),
      ),
    );
  }
}

class TimePickerChainExample extends StatefulComponent {
  const TimePickerChainExample({super.key});

  @override
  State<TimePickerChainExample> createState() => _TimePickerChainExampleState();
}

class _TimePickerChainExampleState extends State<TimePickerChainExample> {
  String? _value;

  @override
  Component build(BuildContext context) {
    return div(
      [
        TimePicker(
          value: _value,
          placeholder: 'Select time',
          onChanged: (value) => setState(() => _value = value),
        ).withStyle(
          const CoreTimePickerStyle(
            segmentBorderRadius: CoreBorderRadius.all(CoreRadius.radius8),
            segmentBorderColor: CoreColor.token(CoreColors.primary),
            contentColor: CoreColor.token(CoreColors.primary),
            triggerHeight: CoreSpace.space48,
            triggerBorderWidth: CoreStrokeWidth.stroke2,
            triggerContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
            trailingIconStyle: CoreIconStyle(
              size: CoreIconSize.size20,
              color: CoreColor.token(CoreColors.primary),
            ),
          ),
        ),
      ],
      classes: 'w-${CoreSpace.scale.space256}',
    );
  }
}

class TimePickerChainExample extends StatefulWidget {
  const TimePickerChainExample({super.key});

  @override
  State<TimePickerChainExample> createState() => _TimePickerChainExampleState();
}

class _TimePickerChainExampleState extends State<TimePickerChainExample> {
  String? _value;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: CoreSpace.space256,
      child:
          TimePicker(
            value: _value,
            placeholder: 'Select time',
            onChanged: (value) => setState(() => _value = value),
          ).withStyle(
            const CoreTimePickerStyle(
              segmentBorderRadius: CoreBorderRadius.all(CoreRadius.radius8),
              segmentBorderColor: CoreColor.token(CoreColors.primary),
              contentColor: CoreColor.token(CoreColors.primary),
              triggerHeight: CoreSpace.space48,
              triggerBorderWidth: CoreStrokeWidth.stroke2,
              triggerContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
              trailingIconStyle: CoreIconStyle(
                size: CoreIconSize.size20,
                color: CoreColor.token(CoreColors.primary),
              ),
            ),
          ),
    );
  }
}

다이얼로그 모드#

class TimePickerDialogExample extends StatefulComponent {
  const TimePickerDialogExample({super.key});

  @override
  State<TimePickerDialogExample> createState() =>
      _TimePickerDialogExampleState();
}

class _TimePickerDialogExampleState extends State<TimePickerDialogExample> {
  String? _value;

  @override
  Component build(BuildContext context) {
    return div(
      [
        TimePicker(
          value: _value,
          placeholder: 'Select time',
          mode: CorePromptMode.dialog,
          dialogTitle: Text('Pick a time'),
          onChanged: (value) => setState(() => _value = value),
        ),
      ],
      classes: 'w-${CoreSpace.scale.space256}',
    );
  }
}

class TimePickerDialogExample extends StatefulWidget {
  const TimePickerDialogExample({super.key});

  @override
  State<TimePickerDialogExample> createState() =>
      _TimePickerDialogExampleState();
}

class _TimePickerDialogExampleState extends State<TimePickerDialogExample> {
  String? _value;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: CoreSpace.space256,
      child: TimePicker(
        value: _value,
        placeholder: 'Select time',
        mode: CorePromptMode.dialog,
        dialogTitle: const Text('Pick a time'),
        onChanged: (value) => setState(() => _value = value),
      ),
    );
  }
}

초 단위 (HH:MM:SS)#

class TimePickerSecondsExample extends StatefulComponent {
  const TimePickerSecondsExample({super.key});

  @override
  State<TimePickerSecondsExample> createState() =>
      _TimePickerSecondsExampleState();
}

class _TimePickerSecondsExampleState extends State<TimePickerSecondsExample> {
  String? _value;

  @override
  Component build(BuildContext context) {
    return div(
      [
        TimePicker(
          value: _value,
          placeholder: 'Select time',
          showSeconds: true,
          onChanged: (value) => setState(() => _value = value),
        ),
      ],
      classes: 'w-${CoreSpace.scale.space256}',
    );
  }
}

class TimePickerSecondsExample extends StatefulWidget {
  const TimePickerSecondsExample({super.key});

  @override
  State<TimePickerSecondsExample> createState() =>
      _TimePickerSecondsExampleState();
}

class _TimePickerSecondsExampleState extends State<TimePickerSecondsExample> {
  String? _value;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: CoreSpace.space256,
      child: TimePicker(
        value: _value,
        placeholder: 'Select time',
        showSeconds: true,
        onChanged: (value) => setState(() => _value = value),
      ),
    );
  }
}

에러 상태#

class TimePickerErrorExample extends StatefulComponent {
  const TimePickerErrorExample({super.key});

  @override
  State<TimePickerErrorExample> createState() =>
      _TimePickerErrorExampleState();
}

class _TimePickerErrorExampleState extends State<TimePickerErrorExample> {
  String? _value;

  @override
  Component build(BuildContext context) {
    return div(
      [
        TimePicker(
          value: _value,
          placeholder: 'Select time',
          errorText: 'Time is required',
          onChanged: (value) => setState(() => _value = value),
        ),
      ],
      classes: 'w-${CoreSpace.scale.space256}',
    );
  }
}

class TimePickerErrorExample extends StatefulWidget {
  const TimePickerErrorExample({super.key});

  @override
  State<TimePickerErrorExample> createState() =>
      _TimePickerErrorExampleState();
}

class _TimePickerErrorExampleState extends State<TimePickerErrorExample> {
  String? _value;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: CoreSpace.space256,
      child: TimePicker(
        value: _value,
        placeholder: 'Select time',
        errorText: 'Time is required',
        onChanged: (value) => setState(() => _value = value),
      ),
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 예약, 일정, 알림 등 시간을 입력받아야 하는 경우
• 12시간(AM/PM) 또는 24시간 형식의 시간 선택이 필요한 경우
• 영업 시간, 배송 시간처럼 선택 가능한 시간 범위를 제한해야 하는 경우

대신 다른 컴포넌트를 사용하세요:

• DatePicker: 날짜와 시간을 함께 선택해야 하는 경우
• TextField: 시간을 자유 형식 텍스트로 직접 입력받는 경우
• Select: 고정된 시간 슬롯 목록에서 선택해야 하는 경우

기본 사용법 (Basic Usage)#

// 기본 시간 선택기
TimePicker(
  value: selectedTime,
  placeholder: 'Select time',
  onChanged: handleTimeChanged,
)

// 24시간 형식 강제
TimePicker(
  value: meetingTime,
  use24HourFormat: true,
  onChanged: handleMeetingTimeChanged,
)

// 초 표시 포함
TimePicker(
  value: preciseTime,
  showSeconds: true,
  onChanged: handlePreciseTimeChanged,
)

// 선택 가능 범위 제한 (ISO time string)
TimePicker(
  value: businessHour,
  min: '09:00',
  max: '18:00',
  onChanged: handleBusinessHourChanged,
)

// 기본 시간 선택기
TimePicker(
  value: selectedTime,
  placeholder: 'Select time',
  onChanged: handleTimeChanged,
)

// 24시간 형식 강제
TimePicker(
  value: meetingTime,
  use24HourFormat: true,
  onChanged: handleMeetingTimeChanged,
)

// 초 표시 포함
TimePicker(
  value: preciseTime,
  showSeconds: true,
  onChanged: handlePreciseTimeChanged,
)

// 선택 가능 범위 제한
TimePicker(
  value: businessHour,
  min: '09:00',
  max: '18:00',
  onChanged: handleBusinessHourChanged,
)

빠른 오버라이드 (Chain)#

이미 만든 TimePicker 인스턴스에 스타일을 빠르게 덧붙이고 싶다면 withStyle 체인을 쓸 수 있습니다. 생성자의 style 슬롯 인자와 동일하게 동작하지만, 이미 구성된 위젯 위에서 바로 이어 쓸 수 있습니다.

class TimePickerChainExample extends StatefulWidget {
  const TimePickerChainExample({super.key});

  @override
  State<TimePickerChainExample> createState() => _TimePickerChainExampleState();
}

class _TimePickerChainExampleState extends State<TimePickerChainExample> {
  String? _value;

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: CoreSpace.space256,
      child:
          TimePicker(
            value: _value,
            placeholder: 'Select time',
            onChanged: (value) => setState(() => _value = value),
          ).withStyle(
            const CoreTimePickerStyle(
              segmentBorderRadius: CoreBorderRadius.all(CoreRadius.radius8),
              segmentBorderColor: CoreColor.token(CoreColors.primary),
              contentColor: CoreColor.token(CoreColors.primary),
              triggerHeight: CoreSpace.space48,
              triggerBorderWidth: CoreStrokeWidth.stroke2,
              triggerContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
              trailingIconStyle: CoreIconStyle(
                size: CoreIconSize.size20,
                color: CoreColor.token(CoreColors.primary),
              ),
            ),
          ),
    );
  }
}

class TimePickerChainExample extends StatefulComponent {
  const TimePickerChainExample({super.key});

  @override
  State<TimePickerChainExample> createState() => _TimePickerChainExampleState();
}

class _TimePickerChainExampleState extends State<TimePickerChainExample> {
  String? _value;

  @override
  Component build(BuildContext context) {
    return div(
      [
        TimePicker(
          value: _value,
          placeholder: 'Select time',
          onChanged: (value) => setState(() => _value = value),
        ).withStyle(
          const CoreTimePickerStyle(
            segmentBorderRadius: CoreBorderRadius.all(CoreRadius.radius8),
            segmentBorderColor: CoreColor.token(CoreColors.primary),
            contentColor: CoreColor.token(CoreColors.primary),
            triggerHeight: CoreSpace.space48,
            triggerBorderWidth: CoreStrokeWidth.stroke2,
            triggerContentGapStyle: CoreGapStyle(size: CoreSpace.space12),
            trailingIconStyle: CoreIconStyle(
              size: CoreIconSize.size20,
              color: CoreColor.token(CoreColors.primary),
            ),
          ),
        ),
      ],
      classes: 'w-${CoreSpace.scale.space256}',
    );
  }
}

Props / Parameters#

공통 Contract 필드 (CoreTimePickerContract):

스타일 시스템 (Style System)#

TimePicker의 모든 chrome / 치수 / 중첩 슬롯 오버라이드는 CoreTimePickerStyle 한곳으로 흐릅니다.

시맨틱 vs 스타일#

• 시맨틱 enum / 동작: 위젯 파라미터로 직접 (mode, popoverPlacement, placeholder, placeholderSegment, placeholderSeparator, enabled, showSeconds, use24HourFormat, onChanged, min, max, errorText, dialogTitle)
• chrome / 치수 / 슬롯 스타일: CoreTimePickerStyle 한곳 (아래 필드 표)
• 변형 교체: asChild — dialogTitle 슬롯 등에 위젯을 직접 넣습니다

Resolve chain#

design system default for time picker
  → CoreTimePickerTheme.style                  // 프로젝트 공통
  → parent component slot override
  → widget.timePickerStyle                     // 인스턴스별

각 nested 슬롯 스타일 (popoverStyle / dialogStyle / segmentInputStyle / amPmButtonStyle / amPmSelectedButtonStyle / actionButtonStyle) 은 자기 컴포넌트의 자체 resolve chain 으로 다시 한 번 머지됩니다. 예: popoverStyle.triggerStyle 의 chrome 은 → CoreButtonTheme → variant 룩업 → 부모 슬롯 → widget.timePickerStyle.popoverStyle.triggerStyle 순. 마찬가지로 popover 패널 박스는 popoverStyle.panelStyle (CorePopupStyle) 을 통해 Popup 의 resolver 로 흐릅니다.

CoreTimePickerStyle 필드#

사용 예 (Flutter)#

TimePicker(
  value: '14:30',
  placeholder: 'Select time',
  onChanged: handleTimeChanged,
  timePickerStyle: CoreTimePickerStyle(
    popoverStyle: CorePopoverStyle(
      panelStyle: CorePopupStyle(
        borderRadius: CoreBorderRadius.all(CoreRadius.radius12),
        padding: CoreEdgeInsets.all(CoreSpace.space16),
      ),
      placementOffset: CoreSpace.space8,
      triggerStyle: CoreButtonStyle(
        height: CoreSize.size44,
        padding: CoreEdgeInsets.symmetric(horizontal: CoreSpace.space16),
      ),
    ),
    segmentInputStyle: CoreTextFieldStyle(
      borderColor: CoreColor.token(CoreColors.primary),
    ),
    amPmButtonStyle: CoreButtonStyle(height: CoreSize.size36),
    labelStyle: CoreTextStyle(fontWeight: CoreFontWeight.semiBold),
  ),
)

동작 스펙 (Behavior)#

인터랙션#

• 트리거 클릭: mode가 popover(기본)면 Popover 패널이 popoverPlacement 위치로, dialog면 Dialog 가 중앙 모달로 열립니다 (양쪽 동일)
• 직접 입력: 시/분/초 필드에 숫자를 직접 입력 가능 (양쪽 동일)
• AM/PM 토글: 12시간 형식에서 AM/PM 전환 — Button 기반 (양쪽 동일)
• 저장/취소: 패널 하단의 Button (Save / Cancel)

값 형식#

• 값은 ISO 시간 문자열로 주고받습니다: "14:30" 또는 "14:30:45" (showSeconds 시)
• 12시간 포맷에서도 값은 24시간 ISO로 저장되며, 디스플레이만 hh:mm AM/PM로 포맷팅됩니다

Theme 오버라이드#

CoreComponentTheme.timePicker를 통해 프로젝트 레벨의 기본 스타일(CoreTimePickerStyle)을 지정할 수 있습니다:

CoreComponentTheme(
  timePicker: CoreTimePickerTheme(
    style: CoreTimePickerStyle(
      popoverStyle: CorePopoverStyle(
        panelStyle: CorePopupStyle(
          borderRadius: CoreBorderRadius.all(CoreRadius.radius8),
          padding: CoreEdgeInsets.all(CoreSpace.space16),
        ),
        triggerStyle: CoreButtonStyle(
          height: CoreSize.size40,
          padding: CoreEdgeInsets.symmetric(horizontal: CoreSpace.space12),
        ),
      ),
    ),
  ),
)

사용 가이드라인 (Usage Guidelines)#

✅ Do#

TimePicker(
  value: businessHour,
  min: '09:00',
  max: '18:00',
  onChanged: handleBusinessHourChanged,
)

❌ Don't#

// ❌ "HH:MM" ISO 형식이 아닌 12시간 문자열
TimePicker(
  value: '02:30 PM',
  onChanged: (v) => save(v),
)

접근성 (Accessibility)#

• 트리거에 role="button"과 aria-haspopup="dialog"가 붙습니다.
• 패널은 role="dialog"로 열립니다.
• 키보드로 시/분/초를 직접 입력할 수 있습니다 (양쪽 동일).
• 최소 터치 타겟(WCAG 2.2 AA)은 24×24 논리 픽셀입니다. 트리거는 필드 기본 높이(40px)라 이미 그보다 큽니다.

크로스 플랫폼 차이점 (Platform Differences)#

양쪽 모두 Popover + Button + Icon을 사용해 동일한 UX를 제공합니다. 값 형식, 토큰, 동작 모두 1:1 통일되어 있습니다.

관련 컴포넌트 (Related Components)#

• DatePicker: 날짜와 시간을 함께 선택해야 하는 경우
• TextField: 시간을 텍스트로 직접 입력받는 경우
• Select: 고정된 시간 슬롯 목록을 드롭다운으로 제공하는 경우