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';

이제 React IgrDateRangePicker의 기본 구성으로 시작할 수 있습니다.

Ignite UI for React에 대한 전체 소개를 보려면 시작하기 항목을 읽어보세요.

Usage

을 IgrDateRangePicker 통해 사용자는 드롭다운/달력 팝업에서 날짜 범위를 선택하거나 입력 필드(시작 날짜와 종료 날짜)에 직접 입력하여 시작 및 종료 날짜를 선택할 수 있습니다.

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

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

Display Date Range Picker

기본 단일 입력 모드에서 a IgrDateRangePicker를 인스턴스화하려면 다음 코드를 사용합니다.

<IgrDateRangePicker/>

두 개의 입력을 사용하도록 전환 IgrDateRangePicker 하려면 속성을 로 설정합니다 useTwoInputs. true

<IgrDateRangePicker useTwoInputs/>

Value

사용자가 선택하거나 입력하는 것 외에도 속성 을 value 사용하여 범위 IgrDateRangePicker 값을 설정할 수도 있습니다. 값은 {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} />
);

또한 값을 속성으로 설정할 수 있습니다. 이 경우 JSON으로 올바르게 구문 분석할 수 있는 개체를 나타내야 하며, 여기서 start 및 end 필드에는 ISO 8601 형식의 날짜 값이 있어야 합니다.

<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 + ArrowDown`	Opens the calendar dropdown
`Alt + ArrowUp`	Closes the calendar dropdown

키보드를 사용하여 캘린더 팝업 내에서 탐색할 수도 있습니다. 탐색은 구성 요소에서 IgrCalendar와 동일합니다.

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

Layout

Label

구성 요소가 단일 입력 모드에 있을 때 속성을 label 사용하여 구성 요소에 대한 IgrDateRangePicker 레이블을 정의할 수 있습니다. 두 가지 입력 모드에서는 및 labelEnd 속성을 사용하여 labelStart 각각 시작 날짜 및 종료 날짜 입력 필드에 대한 레이블을 정의할 수 있습니다.

<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

정의된 범위를 벗어난 달력 날짜를 사용하지 않도록 설정하여 사용자 입력을 제한하도록 및 속성을 설정할 min max 수도 있습니다. 이러한 속성은 유효성 검사기 역할을 하므로 사용자가 범위를 벗어난 날짜를 수동으로 입력하더라도 유효 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} />
);

이제 캘린더 팝업에서 새로 생성된 "Next 7 days" 칩을 클릭하면 오늘부터 다음 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} />
);

Forms

구성 요소는 IgrDateRangePicker HTML 양식 요소와 함께 원활하게 사용할 수도 있습니다. , min, max 및 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 모양을 수정할 수 있습니다.

and suffix 슬롯을 prefix 사용하면 입력 필드 앞이나 뒤에 사용자 지정 콘텐츠를 삽입할 수 있습니다(단일 입력 모드에서만 사용 가능).

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

두 개의 입력 모드에서는 대신 , prefix-start prefix-end,, suffix-start 및 suffix-end 슬롯을 사용하여 개별 입력을 대상으로 지정할 수 있습니다.

또 다른 유용한 슬롯 집합은 clear-icon and calendar-icon 이며, 이를 통해 입력 필드에 있는 clear 및 calendar 버튼의 아이콘을 사용자 지정할 수 있습니다.

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

두 개의 입력 모드에서는 슬롯을 사용하여 필드 사이의 기본 "to" 텍스트를 사용자 지정할 수도 있습니다. separator

<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