DatePicker

Podo UI의 DatePicker 컴포넌트와 사용법을 안내합니다

기본 사용법

DatePicker는 날짜, 시간, 또는 날짜+시간을 선택할 수 있는 컴포넌트입니다. 단일 선택(instant)과 기간 선택(period) 모드를 지원합니다.

TSX

import { DatePicker } from 'podo-ui';

// 단일 날짜 선택
<DatePicker
  mode="instant"
  type="date"
  value={value}
  onChange={setValue}
/>

// 기간 선택
<DatePicker
  mode="period"
  type="date"
  value={value}
  onChange={setValue}
/>

실제 예제:

단일 선택

선택됨: -

기간 선택

~

선택됨: -

타입

세 가지 타입을 지원합니다: date(날짜만), time(시간만), datetime(날짜+시간)

타입별 예제:

type="date"

날짜만 선택합니다

-

type="time"

시간만 선택합니다

:

-

type="datetime"

날짜와 시간을 함께 선택합니다

:

-

TSX

// 날짜만 선택
<DatePicker type="date" />

// 시간만 선택
<DatePicker type="time" />

// 날짜 + 시간
<DatePicker type="datetime" />

기간 선택

mode="period"로 설정하면 시작일과 종료일을 선택할 수 있습니다. 하단에 초기화/적용 버튼이 표시됩니다.

기간 선택 예제:

날짜 기간

~

-

시간 기간

:

~

:

-

날짜+시간 기간

:

~

:

-

TSX

// 기간 날짜 선택
<DatePicker mode="period" type="date" />

// 기간 시간 선택
<DatePicker mode="period" type="time" />

// 기간 날짜+시간 선택
<DatePicker mode="period" type="datetime" />

상태

다양한 상태를 지원합니다:

상태 예제:

기본

-

비활성화

초기값 설정

2025. 12. 8.

TSX

// 기본 상태
<DatePicker type="date" />

// 비활성화
<DatePicker type="date" disabled />

// 초기값 설정
<DatePicker type="date" value={{ date: new Date() }} />

Props

DatePicker 컴포넌트의 Props:

Prop	Type	Default	Description
`mode`	`'instant' \| 'period'`	`'instant'`	선택 모드 (instant: 단일, period: 기간)
`type`	`'date' \| 'time' \| 'datetime'`	`'date'`	값 타입 (date: 날짜, time: 시간, datetime: 날짜+시간)
`value`	`{ date?: Date, time?: TimeValue, endDate?: Date, endTime?: TimeValue }`	`-`	선택된 값 객체
`onChange`	`(value) => void`	`-`	값 변경 콜백 함수
`placeholder`	`string`	`-`	플레이스홀더 텍스트
`disabled`	`boolean`	`false`	비활성화 여부
`showActions`	`boolean`	`period: true`	하단 버튼 표시 여부 (period 모드에서 기본 true)
`align`	`'left' \| 'right'`	`'left'`	드롭다운 정렬 (left 또는 right)
`disable`	`DateCondition[]`	`-`	선택 불가능한 날짜 조건 (특정 날짜, 범위, 함수)
`enable`	`DateCondition[]`	`-`	선택 가능한 날짜 조건 (지정된 날짜만 활성화)
`minDate`	`Date \| DateTimeLimit`	`-`	선택 가능한 최소 날짜 (Date 또는 DateTimeLimit)
`maxDate`	`Date \| DateTimeLimit`	`-`	선택 가능한 최대 날짜 (Date 또는 DateTimeLimit)
`minuteStep`	`1 \| 5 \| 10 \| 15 \| 20 \| 30`	`1`	분 단위 선택 간격 (1, 5, 10, 15, 20, 30)
`format`	`string`	`-`	날짜/시간 표시 포맷 (y: 년, m: 월, d: 일, h: 시, i: 분)
`initialCalendar`	`{ start?: CalendarInitial, end?: CalendarInitial }`	`-`	기간 선택 모드에서 초기 달력 표시 월 설정

Value 인터페이스

DatePickerValue는 날짜와 시간을 별도의 필드로 관리합니다. 이를 통해 날짜와 시간을 독립적으로 바인딩하고 제어할 수 있습니다.

TypeScript

// 시간 값 인터페이스
interface TimeValue {
  hour: number;   // 0-23
  minute: number; // 0-59
}

// DatePicker 값 인터페이스
interface DatePickerValue {
  date?: Date;        // 시작 날짜 (년, 월, 일)
  time?: TimeValue;   // 시작 시간 (시, 분)
  endDate?: Date;     // 종료 날짜 - period 모드
  endTime?: TimeValue; // 종료 시간 - period 모드
}

필드	타입	사용 조건	설명
`date`	`Date`	`date, datetime`	시작 날짜 (년, 월, 일). Date 객체로 저장됩니다.
`time`	`TimeValue`	`time, datetime`	시작 시간 (시, 분). hour(0-23)과 minute(0-59)을 포함하는 객체입니다.
`endDate`	`Date`	`period + date/datetime`	종료 날짜. period 모드에서 기간의 끝 날짜를 지정합니다.
`endTime`	`TimeValue`	`period + time/datetime`	종료 시간. period 모드에서 기간의 끝 시간을 지정합니다.

사용 예제

// 날짜만 선택 (type="date")
const dateValue: DatePickerValue = {
  date: new Date(2024, 0, 15), // 2024-01-15
};

// 시간만 선택 (type="time")
const timeValue: DatePickerValue = {
  time: { hour: 14, minute: 30 }, // 14:30
};

// 날짜 + 시간 (type="datetime")
const datetimeValue: DatePickerValue = {
  date: new Date(2024, 0, 15),
  time: { hour: 14, minute: 30 },
};

// 기간 선택 (mode="period", type="date")
const periodValue: DatePickerValue = {
  date: new Date(2024, 0, 15),    // start
  endDate: new Date(2024, 0, 20), // end
};

// 기간 날짜+시간 선택 (mode="period", type="datetime")
const periodDatetimeValue: DatePickerValue = {
  date: new Date(2024, 0, 15),
  time: { hour: 9, minute: 0 },
  endDate: new Date(2024, 0, 20),
  endTime: { hour: 18, minute: 0 },
};

날짜 비활성화

disable과 enable props를 사용하여 선택 가능한 날짜를 제한할 수 있습니다. 특정 날짜, 날짜 범위, 또는 함수를 통해 조건을 지정할 수 있습니다.

비활성화 예제:

특정 날짜 비활성화

특정 날짜들을 선택할 수 없게 합니다

-

날짜 범위 비활성화

특정 기간의 날짜들을 선택할 수 없게 합니다

-

함수로 비활성화

조건 함수로 날짜를 동적으로 비활성화합니다

-

특정 날짜만 활성화

enable을 사용하여 지정된 날짜만 선택 가능하게 합니다

-

TSX

// 특정 날짜 비활성화
<DatePicker
  type="date"
  disable={[
    new Date(2024, 0, 10), // 2024-01-10
    new Date(2024, 0, 15), // 2024-01-15
  ]}
/>

// 날짜 범위 비활성화
<DatePicker
  type="date"
  disable={[
    { from: new Date(2024, 0, 5), to: new Date(2024, 0, 12) },
  ]}
/>

// 함수로 비활성화 (주말 비활성화)
<DatePicker
  type="date"
  disable={[
    (date) => date.getDay() === 0 || date.getDay() === 6,
  ]}
/>

// 특정 날짜만 활성화
<DatePicker
  type="date"
  enable={[
    { from: new Date(2024, 0, 1), to: new Date(2024, 0, 7) },
  ]}
/>

TypeScript

// 날짜 범위 인터페이스
interface DateRange {
  from: Date;
  to: Date;
}

// 날짜 조건 타입
type DateCondition =
  | Date                        // 특정 날짜
  | DateRange                   // 날짜 범위
  | ((date: Date) => boolean);  // 조건 함수

최소/최대 날짜

minDate와 maxDate props를 사용하여 선택 가능한 날짜 범위를 지정할 수 있습니다. Date 객체 또는 DateTimeLimit 형태로 시간까지 지정할 수 있습니다.

최소/최대 날짜 예제:

날짜만 제한

오늘부터 30일 이내 선택 가능

-

날짜+시간 제한

시작/종료 시간까지 정밀하게 제한

:

-

TSX

// 날짜만 제한 (Date 객체)
<DatePicker
  type="date"
  minDate={new Date()}                    // 오늘부터
  maxDate={new Date(2024, 11, 31)}        // 까지 2024-12-31
/>

// 날짜+시간 제한 (DateTimeLimit 객체)
<DatePicker
  type="datetime"
  minDate={{
    date: new Date(),
    time: { hour: 9, minute: 0 },        // 오늘부터 09:00
  }}
  maxDate={{
    date: new Date(2024, 11, 31),
    time: { hour: 18, minute: 0 },       // 까지 2024-12-31 18:00
  }}
/>

TypeScript

// 날짜+시간 제한 인터페이스
interface DateTimeLimit {
  date: Date;
  time?: TimeValue; // { hour: number, minute: number }
}

// minDate/maxDate 타입
type MinMaxDate = Date | DateTimeLimit;

분 단위 선택

minuteStep props를 사용하여 분 선택 간격을 지정할 수 있습니다. 1, 5, 10, 15, 30분 단위를 지원하며 기본값은 1분입니다.

분 단위 예제:

minuteStep=1

1분 단위 (기본)

:

-

minuteStep=5

5분 단위

:

-

minuteStep=10

10분 단위

:

-

minuteStep=15

15분 단위

:

-

minuteStep=20

20분 단위

:

-

minuteStep=30

30분 단위

:

-

TSX

// 1분 단위 (기본값)
<DatePicker type="time" minuteStep={1} />

// 5분 단위
<DatePicker type="time" minuteStep={5} />

// 10분 단위
<DatePicker type="time" minuteStep={10} />

// 15분 단위
<DatePicker type="time" minuteStep={15} />

// 20분 단위
<DatePicker type="time" minuteStep={20} />

// 30분 단위
<DatePicker type="time" minuteStep={30} />

// datetime과 함께 사용
<DatePicker type="datetime" minuteStep={15} />

TypeScript

// 분 단위 선택 타입
type MinuteStep = 1 | 5 | 10 | 15 | 20 | 30;

날짜 포맷

format props를 사용하여 날짜/시간 표시 형식을 지정할 수 있습니다. y(년), m(월), d(일), h(시), i(분)을 조합하여 원하는 포맷을 만들 수 있습니다.

포맷 예제:

format="y-m-d"

대시 구분

-

format="y.m.d"

점 구분

-

format="y년 m월 d일"

한국어 포맷

-

format="y.m.d h:i"

날짜+시간 포맷

:

-

TSX

// 대시 구분
<DatePicker type="date" format="y-m-d" />

// 점 구분
<DatePicker type="date" format="y.m.d" />

// 한국어 포맷
<DatePicker type="date" format="y년 m월 d일" />

// 날짜+시간 포맷
<DatePicker type="datetime" format="y.m.d h:i" />

// 한국어 날짜+시간 포맷
<DatePicker type="datetime" format="y년 m월 d일 h시 i분" />

TypeScript

// 포맷 키
// y: 년 (4자리, 예: 2024)
// m: 월 (2자리, 예: 01)
// d: 일 (2자리, 예: 15)
// h: 시 (2자리, 예: 14)
// i: 분 (2자리, 예: 30)

초기 달력 월 설정

기간 선택 모드에서 initialCalendar props를 사용하여 왼쪽/오른쪽 달력의 초기 표시 월을 설정할 수 있습니다. 'now'(현재 달), 'prevMonth'(이전 달), 'nextMonth'(다음 달) 또는 Date 객체를 사용할 수 있습니다.

초기 달력 예제:

prevMonth / now

이전 달 / 현재 달

~

-

now / nextMonth

현재 달 / 다음 달

~

-

Date

특정 날짜 지정

~

-

TSX

// 이전 달 / 현재 달
<DatePicker
  mode="period"
  type="date"
  initialCalendar={{
    start: 'prevMonth',
    end: 'now',
  }}
/>

// 현재 달 / 다음 달
<DatePicker
  mode="period"
  type="date"
  initialCalendar={{
    start: 'now',
    end: 'nextMonth',
  }}
/>

// 특정 날짜 지정
<DatePicker
  mode="period"
  type="date"
  initialCalendar={{
    start: new Date(2024, 0, 1),  // 2024-01
    end: new Date(2024, 1, 1),    // 2024-02
  }}
/>

TypeScript

// 초기 달력 표시 월 타입
type CalendarInitial = 'now' | 'prevMonth' | 'nextMonth' | Date;

// 초기 달력 설정 인터페이스
interface InitialCalendar {
  start?: CalendarInitial;  // 왼쪽 달력 (시작 달력)
  end?: CalendarInitial;    // 오른쪽 달력 (종료 달력)
}

CDN 사용 (Vanilla JS)

React 없이 순수 JavaScript로 DatePicker를 사용할 수 있습니다. jsDelivr CDN을 통해 스크립트와 스타일을 로드하세요.

라이브 데모

아래는 Vanilla JS로 구현된 DatePicker 실제 동작 예제입니다:

단일 날짜

-

기간 선택

-

날짜+시간

-

기본 사용법

<!-- CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/podo-ui@latest/cdn/podo-datepicker.min.css">

<!-- JS -->
<script src="https://cdn.jsdelivr.net/npm/podo-ui@latest/cdn/podo-datepicker.min.js"></script>

<!-- HTML -->
<div id="my-datepicker"></div>

<!-- Initialize -->
<script>
  const picker = new PodoDatePicker('#my-datepicker', {
    mode: 'instant',
    type: 'date',
    onChange: function(value) {
      console.log('Selected:', value);
    }
  });
</script>

jsDelivr CDN에서 최신 버전을 자동으로 가져옵니다.

옵션

JavaScript

const picker = new PodoDatePicker('#my-datepicker', {
  // 선택 모드: 'instant' (단일) 또는 'period' (기간)
  mode: 'instant',

  // 값 타입: 'date', 'time', 'datetime'
  type: 'date',

  // 초기값
  value: {
    date: new Date(),
    time: { hour: 9, minute: 0 }
  },

  // 값 변경 콜백
  onChange: function(value) {
    console.log(value);
  },

  // 비활성화
  disabled: false,

  // 드롭다운 정렬: 'left' 또는 'right'
  align: 'left',

  // 하단 버튼 표시 (period 모드에서 기본 true)
  showActions: true,

  // 분 단위: 1, 5, 10, 15, 20, 30
  minuteStep: 15,

  // 최소/최대 날짜
  minDate: new Date(),
  maxDate: new Date(2025, 11, 31),

  // 또는 시간 포함
  minDate: {
    date: new Date(),
    time: { hour: 9, minute: 0 }
  },

  // 날짜 비활성화 조건
  disable: [
    new Date(2024, 0, 1),  // 특정 날짜
    { from: new Date(2024, 0, 10), to: new Date(2024, 0, 20) },  // 범위
    function(date) { return date.getDay() === 0; }  // 일요일
  ],

  // 특정 날짜만 활성화
  enable: [
    { from: new Date(2024, 0, 1), to: new Date(2024, 0, 15) }
  ],

  // 날짜/시간 표시 포맷 (y: 년, m: 월, d: 일, h: 시, i: 분)
  format: 'y-m-d',  // 예: 2024-01-15
  // format: 'y.m.d',  // 예: 2024.01.15
  // format: 'y년 m월 d일',  // 예: 2024년 01월 15일
  // format: 'y-m-d h:i',  // 예: 2024-01-15 14:30

  // 기간 선택 시 초기 달력 월 설정 (period 모드에서만 사용)
  initialCalendar: {
    start: 'prevMonth',  // 왼쪽 달력: 이전 달
    end: 'now'           // 오른쪽 달력: 현재 달
  }
  // start/end 값: 'now', 'prevMonth', 'nextMonth', 또는 Date 객체
});

메서드

JavaScript

// 현재 값을 반환합니다
const value = picker.getValue();
// { date: Date, time: { hour: 9, minute: 0 }, endDate: Date, endTime: {...} }

// 값을 설정합니다
picker.setValue({
  date: new Date(2024, 5, 15),
  time: { hour: 14, minute: 30 }
});

// 값을 초기화합니다
picker.clear();

// DatePicker를 활성화합니다
picker.enable();

// DatePicker를 비활성화합니다
picker.disable();

// DatePicker 인스턴스를 제거합니다
picker.destroy();

다국어 지원

texts 옵션으로 텍스트를 커스터마이징할 수 있습니다.

JavaScript

const picker = new PodoDatePicker('#my-datepicker', {
  type: 'date',
  texts: {
    weekDays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
    months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
             'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
    yearSuffix: '',  // 년 -> 빈 문자열
    reset: 'Reset',
    apply: 'Apply'
  }
});