React 날짜 범위 선택기 개요

Ignite UI for React 날짜 범위 선택기는 텍스트 입력과 달력 팝업을 포함하는 경량 구성 요소로, 사용자가 시작 날짜와 종료 날짜를 쉽게 선택할 수 있습니다. 다양한 애플리케이션 요구 사항에 맞게 사용자 정의가 가능하며 날짜 범위 제한, 구성 가능한 날짜 형식 등과 같은 기능을 제공합니다.

Date Range Picker Example

아래는 사용자가 시작일과 종료일을 선택할 수 있도록 캘린더 팝업을 통해 구성 요소를 시연IgrDateRangePicker 한 샘플입니다.

시작하기

IgrDateRangePicker사용하려면 먼저 다음 명령을 실행하여 Ignite UI for React을 설치해야 합니다:

npm install igniteui-react

그 다음에는 다음과 같이 필요한 CSS를IgrDateRangePicker 가져오세요:

import { IgrDateRangePicker } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

이제 ReactIgrDateRangePicker의 기본 구성부터 시작할 수 있습니다.

Ignite UI for React에 대한 완전한 소개는 '시작 주제'를 읽어보세요.

Usage

IgrDateRangePicker사용자는 드롭다운/캘린더 팝업에서 날짜 범위를 선택하거나 입력 필드에 직접 입력하여 시작일과 종료일을 선택할 수 있습니다.

선택기는 날짜 값을 표시하기 위한 두 가지 모드(단일 입력과 두 개의 입력)를 제공합니다. 단일 입력 모드에서는 필드를 편집할 수 없으며 입력하여 날짜 범위를 편집할 수 없습니다. 그러나 두 개의 입력 모드에서 사용자는 별도의 입력 필드를 입력하여 시작 날짜와 종료 날짜를 편집할 수 있습니다.

달력이 표시되면 시작 날짜와 종료 날짜를 모두 선택하여 날짜 범위를 선택할 수 있습니다. 날짜를 선택하면 시작 날짜와 종료 날짜가 모두 설정되며, 두 번째 날짜를 선택하면 종료 날짜가 설정됩니다. 범위가 이미 선택되어 있는 경우 달력에서 다른 날짜를 클릭하면 새 범위 선택이 시작됩니다.

Display Date Range Picker

기본 단일 입력 모드에서 aIgrDateRangePicker를 인스턴스화하려면 다음 코드를 사용하세요:

<IgrDateRangePicker/>

전환하려면IgrDateRangePicker 두 입력을 사용하려면 다음을 설정하세요.useTwoInputs property를true.

<IgrDateRangePicker useTwoInputs/>

Value

사용자가 선택하거나 타입을 입력하는 것 외에도, 범위IgrDateRangePicker 값은 속성을value 사용하여 설정할 수 있습니다. 값은 다음과 같은 형식을 따라야 한다는 점이 중요합니다: { start: startDate, end: endDate }, 여기서startDate와endDate는Date 선택한 범위를 나타내는 객체입니다.

const dateRangeRef = useRef<IgrDateRangePicker>();
let startDate = new Date(2025, 4, 6);
let endDate = new Date(2025, 4, 8);
useEffect (() => {
  dateRangeRef.current.value = { start: startDate, end: endDate }
}, [])

return (
  <IgrDateRangePicker ref={dateRangeRef} />
);

<IgrDateRangePicker value={{start: new Date('2025-01-01'), end: new Date('2025-01-02')}}/>

Read-only & Non-editable

읽기 전용으로 설정할IgrDateRangePicker 수도 있는데, 이는 타이핑과 달력 선택 모두에서 범위 값을 변경하지 못하게 하고, 키보드 내비게이션을 비활성화하며, 달력과 아이콘 아이콘이 시각적으로 비활성화되는 것처럼 보입니다. 이는 범위가 value 속성을 통해 할당되고 표시 전용으로 의도될 때 유용합니다. 이 동작을 활성화하려면 단순히 속성을 설정하면 됩니다.readOnly

<IgrDateRangePicker useTwoInputs readOnly/>

또는 이 속성을 사용할nonEditable 수도 있는데,readOnly이 속성은 입력 입력을 타이핑으로만 편집하지 못하게 하면서도 캘린더에서 선택하거나 아이콘 지우기만 허용합니다.

<IgrDateRangePicker useTwoInputs nonEditable/>

기본적으로 클릭하면IgrDateRangePicker 달력 팝업이 모드로dropdown 열립니다. 또는 속성을 로dialog 설정mode 하여 달력을 모드에서dialog 열 수도 있습니다.

<IgrDateRangePicker mode='dialog'/>

IgrDateRangePicker직관적인 키보드 내비게이션 기능을 제공하여, 사용자가 마우스 없이도 다양한 구성 요소 사이를 쉽게 늘리거나 감소하거나 점프할 수 있습니다.

사용 가능한 키보드 탐색 옵션은 구성 요소가 단일 입력 모드인지 두 입력 모드인지에 따라 달라집니다.

두 개의 입력 모드:

열쇠	설명
`←`	캐럿을 왼쪽으로 한 문자 이동합니다.
`→`	캐럿을 오른쪽으로 한 문자 이동합니다.
`CTRL` + `ArrowLeft`	캐럿을 현재 입력 마스크 섹션의 시작 부분으로 이동하거나 이미 시작 부분에 있는 경우 이전 섹션의 시작 부분으로 이동합니다
`CTRL` + `ArrowRight`	캐럿을 현재 입력 마스크 섹션의 끝으로 이동하거나 이미 끝에 있는 경우 다음 섹션의 끝으로 이동합니다.
`ArrowUp`	입력 마스크의 현재 "초점이 맞춰진" 부분을 한 단계씩 증가시킵니다
`ArrowDown`	입력 마스크의 현재 "초점이 맞춰진" 부분을 한 단계 감소시킵니다.
`집`	캐럿을 입력 마스크의 시작 부분으로 이동합니다.
`끝`	캐럿을 입력 마스크의 끝으로 이동합니다.
`CTRL` +`;`	현재 날짜를 구성 요소의 값으로 설정합니다.

단일 및 두 개의 입력 모드 모두:

열쇠	설명
`ALT` + `↓`	Opens the calendar dropdown
`ALT` + `↑`	Closes the calendar dropdown

키보드를 사용해 캘린더 팝업 내에서도 탐색할 수 있습니다. 내비게이션은 컴포넌트IgrCalendar와 동일합니다.

열쇠	설명
`↑` / `↓` / `←` / `→`	해당 월의 요일을 탐색합니다.
`ENTER`	현재 초점이 맞춰진 날짜를 선택합니다.
`페이지 업`	이전 달의 보기로 이동합니다.
`페이지 다운`	다음 달 보기로 이동합니다.
`SHIFT` + `PAGE UP`	전년도로 이동
`SHIFT` + `PAGE DOWN`	다음 해로 이동
`집`	보기에 있는 현재 달의 첫 번째 날(또는 두 개 이상의 개월 보기가 표시되는 경우 가장 빠른 달)에 초점을 맞춥니다.
`끝`	현재 표시된 달의 마지막 날에 초점을 맞춥니다. (또는 두 개 이상의 개월 보기가 표시되는 경우 최신 달)
`Escape`	캘린더 팝업을 닫습니다.

Layout

Label

단일 입력 모드일 때 컴IgrDateRangePicker 포넌트의 라벨label을 정의할 수 있습니다. 두 입력 모드에서는 와labelStart 속성을 사용labelEnd 해 각각 시작 날짜와 종료일 입력 필드에 라벨을 지정할 수 있습니다.

<IgrDateRangePicker label='Date Range'/>

<IgrDateRangePicker useTwoInputs labelStart='Start Date' labelEnd='End Date'/>

Format

입력란에 표시되는 날짜 형식을 커스터마이즈할 수도 있습니다. 이 목적을 위해 이용 가능한 세 가지 부동산이 있습니다:locale,inputFormat, 그리고displayFormat

이 속성은locale 원하는 지역 식별자를 설정할 수 있게 해주며, 이는 지역 관습에 따라 날짜 형식을 결정합니다. 예를 들어, 일본어 형식으로 날짜를 표시하려면 locale 속성을 다음과 같이 설정할 수 있습니다:

<IgrDateRangePicker locale='ja-JP'/>

날짜 형식을 수동으로 정의하고 싶다면, 커스텀 형식 문자열을 전달하여 속성을 사용할inputFormat 수 있습니다:

<IgrDateRangePicker inputFormat='dd/MM/yy'/>

이 속성은displayFormat 또한 커스텀 포맷 문자열을 허용하지만, 입력 필드가 유휴 상태(즉, 집중되지 않았을 때)에만 적용됩니다. 필드가 집중되면 두 속성이 함께 사용될 경우 기본 또는 정의inputFormat 된 형식으로 되돌아갑니다:

<IgrDateRangePicker inputFormat='dd/MM/yy' displayFormat='yy/MM/dd'/>

Calendar Layout and Formatting

You can further customize the pop-up calendar using various properties:

이름	유형	설명
`orientation`	'vertical' or 'horizontal'	달력을 세로로 표시할지 가로로 표시할지 여부를 설정할 수 있습니다.
`visibleMonths`	끈	한 번에 표시되는 개월 수를 1 또는 2 값으로 제어합니다.
`showWeekNumbers`	끈	달력에서 주 번호 열을 활성화하거나 비활성화합니다.
`open`	부울	일정 선택기가 열려 있는지 여부를 확인합니다.
`keepOpenOnSelect`	부울	날짜를 선택한 후 달력 선택기를 열어 둡니다.
`keepOpenOnOutsideClick`	부울	달력 선택기 바깥쪽을 클릭할 때 달력 선택기를 열어 둡니다.
`weekStart`	끈	주의 시작 요일을 설정합니다.
`hideOutsideDays`	부울	현재 월 보기를 벗어나는 날짜를 숨깁니다.
`hideHeader`	부울	달력 헤더를 숨깁니다(대화 상자 모드에서만 적용 가능).
`headerOrientation`	'vertical' or 'horizontal'	Aligns the calendar header vertically or horizontally (dialog mode only).
`activeDate`	날짜	달력에서 처음에 강조 표시된 날짜를 설정합니다. 설정하지 않으면 현재 날짜가 활성 날짜가 됩니다.

<IgrDateRangePicker orientation='vertical' visibleMonths={1} showWeekNumbers/>

Min & Max

또한 정의된 범위 밖의 달력 날짜를 비활성화하여 사용자 입력을 제한하는 property property 설정minmax도 가능합니다. 이 속성들은 검증자 역할을 하므로, 사용자가 수동으로 범위를 벗어난 날짜를 입력해도 유효IgrDateRangePicker 하지 않게 됩니다.

<IgrDateRangePicker min={new Date('2025-05-06')} max={new Date('2025-05-10')}/>

Custom & Predefined Date Ranges

또한 캘린더 팝업에 맞춤형 날짜 범위 칩을 추가해 더 빠른 범위 선택customRanges을 할 수도 있습니다. 예를 들어, 다가오는 7일간의 범위를 빠르게 선택할 수 있는 맞춤형 날짜 범위 칩을 만들 수 있으며, 그 범위는 현재 날짜로 끝납니다. 또한, 속성을 설정usePredefinedRanges 하면 미리 정의된 범위 칩 세트가 커스텀 칩과 함께 표시됩니다.

const today = new Date();
const nextSeven = new Date(
  today.getFullYear(),
  today.getMonth(),
  today.getDate() + 7
);
const nextWeek: CustomDateRange[] = [
  {
    label: "Next 7 days",
    dateRange: {
      start: today,
      end: nextSeven
    }
  }
];

return (
  <IgrDateRangePicker usePredefinedRanges customRanges={nextWeek} />
);

이제 새로 생성된 "다음 7일" 칩을 클릭하면 캘린더 팝업에서 오늘부터 다음 7일까지 범위가 자동으로 선택됩니다.

Disabled & Special dates

또한 사용자가 선택할 수 있는 날짜 범위를 좁히기 위해 달력에서 비활성화된 날짜를 설정할 수 있습니다. 비활성화 날짜를 설정하려면 해당disabledDates 속성을 사용할 수 있습니다.

const dateRangeRef = useRef<IgrDateRangePicker>();
const minDate = new Date(2025, 4, 5);
const maxDate = new Date(2025, 4, 15);
useEffect (() => {
  dateRangeRef.current.disabledDates = [
    {
      type: DateRangeType.Between,
      dateRange: [minDate, maxDate]
    }
  ] as DateRangeDescriptor[];
}, [])

return (
  <IgrDateRangePicker ref={dateRangeRef} />
);

이 부동산이disabledDates 제공하는 모든 가능성에 대한 자세한 정보는 여기에서 확인할 수 있습니다: 장애인 날짜

달력에 하나 이상의 특별한 날짜를 설정하고 싶을 때도 같은 방식으로 할 수 있습니다; 유일한 차이점은 부동산을 사용해야specialDates 한다는 점입니다. 특별 날짜

Forms

이IgrDateRangePicker 컴포넌트는 HTML 폼 요소와도 원활하게 사용할 수 있습니다. 이minmax, , , 그리고required 속성은 폼 검증자 역할을 합니다.

Additional configuration

Properties

이미 다룬 속성들 외에도, 이 컴포넌트는IgrDateRangePicker 동작을 더 설정할 수 있는 다양한 추가 속성을 제공합니다.

이름	유형	설명
`disabled`	부울	구성 요소를 비활성화합니다.
`nonEditable`	부울	입력 필드에 입력할 수 없습니다.
`placeholder`	끈	단일 입력 모드에 대한 자리 표시자 텍스트입니다.
`placeholderStart`	끈	시작 날짜 입력에 대한 자리 표시자 텍스트(두 입력 모드).
`placeholderEnd`	끈	종료 날짜 입력에 대한 자리 표시자 텍스트(두 입력 모드).
`outlined`	부울	입력 파트가 재질 테마에서 윤곽선 모양을 갖을지 여부를 결정합니다.
`prompt`	끈	입력 마스크의 채워지지 않은 부분에 사용되는 프롬프트 문자입니다.
`resourceStrings`	IgcDateRangePickerResourceStrings	날짜 범위 선택기 및 달력의 지역화를 위한 리소스 문자열Resource strings for localization of the date-range picker and the calendar.

Slots

또한 사용 가능한 슬롯을 이용해 커스텀 콘텐츠를 추가하거나 컴포넌트IgrDateRangePicker의 외관을 수정할 수 있습니다.

그리고prefix 슬롯은suffix 입력 필드 앞이나 후에 맞춤 콘텐츠를 삽입할 수 있게 해줍니다(단일 입력 모드에서만 가능):

<IgrDateRangePicker>
  <IgrIcon slot='prefix' name='down_arrow_icon'></IgrIcon>
  <IgrIcon slot='suffix' name='upload_icon'></IgrIcon>
</IgrDateRangePicker>

두 입력 모드에서는 대신 슬롯prefix-startprefix-endsuffix-startsuffix-end을 사용해 개별 입력을 타겟팅할 수 있습니다.

또 다른 유용한 슬롯 세트는clear-icon 입력 필드의 지우기와 달력 버튼 아이콘을 맞춤 설정할 수 있게 해주는 'andcalendar-icon '입니다:

<IgrDateRangePicker>
  <IgrIcon slot="clear-icon" name="apps_icon"></IgrIcon>
  <IgrIcon slot="calendar-icon" name="bin_icon"></IgrIcon>
</IgrDateRangePicker>

두 입력 모드에서는 슬롯을 사용separator 해 필드 간 기본 "to" 텍스트를 맞춤 설정할 수도 있습니다:

<IgrDateRangePicker useTwoInputs>
  <span slot='separator'>till</span>
</IgrDateRangePicker>

슬롯에서는actions 자신만의 논리로 커스텀 액션 버튼을 삽입할 수 있습니다. 예를 들어, 아래 버튼은 달력의 주 번호 열을 전환합니다:

const dateRangeRef = useRef<IgrDateRangePicker>();
const toggleWeekNumbers = () => {
  dateRangeRef.current.showWeekNumbers = !dateRangeRef.current.showWeekNumbers;
};

return (
  <IgrDateRangePicker ref={dateRangeRef}>
    <IgrButton slot="actions" onClick={toggleWeekNumbers}>Toggle Week Numbers</IgrButton>
  </IgrDateRangePicker>
);

이미 다룬 슬롯들 외에도, 다음 슬롯들도 구성 요소에서IgrDateRangePicker 이용 가능합니다:

이름	설명
`title`	일정 제목에 대한 콘텐츠를 렌더링합니다. 대화 상자 모드에서만 적용할 수 있습니다.
`helper-text`	Renders content below the input field(s).
`header-date`	달력 머리글의 기본 현재 날짜/범위 텍스트를 바꿉니다. 대화 상자 모드에서만 적용할 수 있습니다.
`clear-icon-start`	시작 입력에 대한 사용자 지정 지우기 아이콘(두 개의 입력 모드).
`clear-icon-end`	최종 입력에 대한 사용자 지정 지우기 아이콘(두 개의 입력 모드).
`calendar-icon-start`	시작 입력에 대한 사용자 지정 달력 아이콘(두 개의 입력 모드).
`calendar-icon-end`	끝 입력에 대한 사용자 지정 달력 아이콘(두 개의 입력 모드).
`calendar-icon-open`	선택기가 열려 있을 때 표시되는 아이콘 또는 콘텐츠(두 입력 모드의 두 입력에 모두 적용됨).
`calendar-icon-open-start`	시작 입력의 열린 상태에 대한 아이콘 또는 콘텐츠(두 개의 입력 모드).
`calendar-icon-open-end`	끝 입력의 열린 상태에 대한 아이콘 또는 콘텐츠(두 개의 입력 모드).

Methods

속성과 슬롯 외에도,IgrDateRangePicker 사용할 수 있는 몇 가지 방법도 소개합니다:

이름	설명
`show`	달력 선택기 구성 요소를 표시합니다.
`hide`	Hides the calendar picker component.
`toggle`	달력 선택기를 표시된 상태와 숨겨진 상태 사이에서 전환합니다.
`clear`	입력 필드를 지우고 사용자 입력을 제거합니다.
`select`	선택기에서 날짜 범위 값을 선택합니다.
`setCustomValidity`	사용자 지정 유효성 검사 메시지를 설정합니다. 제공된 메시지가 비어 있지 않으면 입력이 유효하지 않은 것으로 표시됩니다.

Styling

컴포넌트가IgrDateRangePicker 컴포넌트를IgrCalendar 사용하기 때문에 캘린더의 CSS 부분도 계승하여 두 컴포넌트를 매끄럽게 스타일링할 수 있습니다. 노출된 캘린더 CSS 부품 전체 목록은 여기에서 확인할 수 있습니다: 캘린더 스타일링. 캘린더의 CSS 파트들 외에도,IgrDateRangePicker 캘린더의 외관을 커스터마이즈할 수 있는 독특한 CSS 파트들도 공개합니다:

이름	설명
`separator`	두 입력 사이의 구분 기호 요소입니다.
`ranges`	사용자 지정 범위와 미리 정의된 범위를 렌더링하는 래퍼입니다.
`label`	대상 입력 위에 콘텐츠를 렌더링하는 레이블 래퍼입니다.
`container`	모든 기본 입력 요소를 보유하는 기본 래퍼입니다.
`input`	기본 입력 요소입니다.
`prefix`	접두사 래퍼.
`suffix`	접미사 래퍼.
`calendar-icon`	닫힌 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-start`	시작 입력(두 개의 입력)의 닫힌 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-end`	끝 입력(두 개의 입력)의 닫힌 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-open`	열린 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-open-start`	시작 입력(두 개의 입력)의 열린 상태에 대한 달력 아이콘 래퍼입니다.
`calendar-icon-open-end`	끝 입력(두 개의 입력)의 열린 상태에 대한 달력 아이콘 래퍼입니다.
`clear-icon`	지우기 아이콘 래퍼(단일 입력).
`clear-icon-start`	시작 입력(두 개의 입력)에 대한 지우기 아이콘 래퍼입니다.
`clear-icon-end`	끝 입력(두 개의 입력)에 대한 지우기 아이콘 래퍼입니다.
`actions`	작업 래퍼.
`helper-text`	대상 입력 아래의 콘텐츠를 렌더링하는 도우미 텍스트 래퍼입니다.

igc-date-range-picker::part(label) {
  color: var(--ig-gray-600);
}

igc-date-range-picker::part(calendar-icon-start),
igc-date-range-picker::part(calendar-icon-end) {
  background-color: var(--ig-primary-500);
  color: var(--ig-primary-500-contrast);
}

igc-date-range-picker::part(calendar-icon-open-start),
igc-date-range-picker::part(calendar-icon-open-end) {
  background-color: var(--ig-primary-700);
  color: var(--ig-primary-700-contrast);
}

igc-date-range-picker::part(clear-icon-start),
igc-date-range-picker::part(clear-icon-end) {
  background-color: var(--ig-error-500);
  color: var(--ig-error-500-contrast);
}

React 날짜 범위 선택기 개요

Date Range Picker Example

시작하기

Usage

Display Date Range Picker

Value

Read-only & Non-editable

Keyboard Navigation

Layout

Label

Format

Calendar Layout and Formatting

Min & Max

Custom & Predefined Date Ranges

Disabled & Special dates

Forms

Additional configuration

Properties

Slots

Methods

Styling

API References

Additional Resources

React 날짜 범위 선택기 개요

Date Range Picker Example

시작하기

Usage

Display Date Range Picker

Value

Read-only & Non-editable

Popup modes

Keyboard Navigation

Layout

Label

Format

Calendar Layout and Formatting

Min & Max

Custom & Predefined Date Ranges

Disabled & Special dates

Forms

Additional configuration

Properties

Slots

Methods

Styling

API References

Additional Resources