React Date Range Picker (日付範囲ピッカー) の概要
Ignite UI for React Date Range Picker は、テキスト入力とカレンダー ポップアップを含む軽量なコンポーネントで、ユーザーが開始日と終了日を簡単に選択できます。日付範囲の制限や設定可能な日付フォーマットなど、さまざまなアプリケーション要件に合わせて高いカスタマイズ性を提供します。
Date Range Picker の例
以下は、カレンダーのポップアップを使用して開始日と終了日を選択できる IgrDateRangePicker コンポーネントのサンプルです。
作業の開始
IgrDateRangePicker の使用を開始するには、最初に次のコマンドを実行して Ignite UI for React をインストールする必要があります。
npm install igniteui-react
その後、次のように IgrDateRangePicker をインポートする必要があります。
import { IgrDateRangePicker } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';
これで、React IgrDateRangePicker の基本構成から始めることができます。
Ignite UI for React の完全な概要については、作業の開始トピックを参照してください。
使用方法
IgrDateRangePicker では、ドロップダウンやカレンダーのポップアップから日付範囲を選択するか、開始日と終了日それぞれの入力フィールドに直接入力することで、日付範囲を指定できます。
ピッカーは、日付を表示するために 「シングル インプット モード」 と 「2 インプット モード」 の 2 タイプのモードを提供します。シングル インプット モードでは、フィールドは編集不可で、日付範囲を入力して変更することはできません。一方で 2 インプット モードでは、開始日と終了日を別々の入力欄に入力して編集できます。
カレンダーが表示されている場合、開始日と終了日を選択することで日付範囲を指定できます。最初の日付を選択すると、開始日と終了日の両方がその日付に設定され、次に日付を選ぶと終了日として設定されます。すでに範囲が選択されている状態で別の日付をクリックすると、新しい範囲の選択が開始されます。
Date Range Picker の表示
デフォルトのシングル インプット モードで IgrDateRangePicker をインスタンス化するには、次のコードを使用します:
<IgrDateRangePicker/>
IgrDateRangePicker を 2 つの入力欄を使用するように切り替えるには、useTwoInputs プロパティを 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} />
);
値は属性として設定することもできます。この場合、値は 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 モードで表示されます。mode プロパティを dialog に設定することで、カレンダーを dialog モードで開くこともできます。
<IgrDateRangePicker mode='dialog'/>
キーボード ナビゲーション
IgrDateRangePicker は直感的なキーボード ナビゲーションに対応しており、マウスを使わずに値の増減や入力マスクのセクション間の移動が可能です。
使用可能なキーボード ナビゲーション オプションは、コンポーネントがシングル インプット モードか 2 インプット モードかによって異なります。
2 インプット モード:
| キー | 説明 |
|---|---|
| ← | カレットを 1 文字左に移動します |
| → | カレットを 1 文字右に移動します |
| CTRL + 左矢印 | カレットを現在の入力マスク セクションの先頭、またはすでに先頭にいる場合は前のセクションの先頭に移動します |
| CTRL + 右矢印 | カレットを現在の入力マスク セクションの末尾、またはすでに末尾にいる場合は次のセクションの末尾に移動します |
| ↑ | 現在フォーカスされている入力マスクのセクションの値を 1 ステップ増加させます |
| ↓</kbd | 現在フォーカスされている入力マスクのセクションの値を 1 ステップ減少させます |
| HOME | カレットを入力マスクの先頭に移動します |
| END | カレットを入力マスクの末尾に移動します |
| CTRL + ; | 現在の日付をコンポーネントの値として設定します |
シングル インプットおよび 2 インプット モードの両方:
| キー | 説明 |
|---|---|
| ALT + ↓</kbd | カレンダーのドロップダウンを開きます |
| ALT + ↑ | カレンダーのドロップダウンを閉じます |
キーボードを使用してカレンダー ポップアップ内を移動することもできます。ナビゲーションは IgrCalendar コンポーネントと同じです。
| キー | 説明 |
|---|---|
| ← + → + ↓ + ↑ | 月内の日付間を移動します |
| ENTER | 現在フォーカスされている日を選択します |
| PAGE UP | 前の月に移動します |
| PAGE DOWN | 次の月に移動します |
| SHIFT + PAGE UP | 前年に移動します |
| SHIFT + PAGE DOWN | 翌年に移動します |
| HOME | 表示されている月のうち、最も早い月の最初の日にフォーカスします (または 1 か月ビューの場合はその月の最初の日) |
| END | 表示されている月のうち、最も遅い月の最後の日にフォーカスします (または 1 か月ビューの場合はその月の最後の日) |
| Escape | カレンダーのポップアップを閉じます |
レイアウト
Label (ラベル)
シングル インプット モードの場合、label プロパティを使用して IgrDateRangePicker コンポーネントにラベルを設定できます。2 インプット モードでは、labelStart および labelEnd プロパティを使用して、それぞれ開始日および終了日の入力フィールドにラベルを設定できます。
<IgrDateRangePicker label='Date Range'/>
<IgrDateRangePicker useTwoInputs labelStart='Start Date' labelEnd='End Date'/>
Format (形式)
入力フィールドに表示される日付形式をカスタマイズすることも可能です。この目的のために使用できるプロパティは、locale、inputFormat、および displayFormat の 3 つです。
locale プロパティでは、使用するロケール識別子を指定でき、地域の慣習に基づいて日付の表示形式が決定されます。
たとえば、日付を日本形式で表示したい場合、locale プロパティを次のように設定します:
<IgrDateRangePicker locale='ja-JP'/>
日付形式を手動で定義したい場合は、カスタム形式の文字列を渡して inputFormat プロパティを使用できます。
<IgrDateRangePicker inputFormat='dd/MM/yy'/>
displayFormat プロパティはカスタム形式文字列も受け入れますが、入力フィールドがアイドル状態 (つまり、フォーカスされていない状態) の場合にのみ適用されます。フィールドにフォーカスがある場合、形式はデフォルト、または inputFormat で定義された形式に戻ります (両方のプロパティが使用されている場合)。
<IgrDateRangePicker inputFormat='dd/MM/yy' displayFormat='yy/MM/dd'/>
カレンダーのレイアウトと形式
さまざまなプロパティを使用して、ポップアップ カレンダーをさらにカスタマイズできます。
| 名前 | タイプ | 説明 |
|---|---|---|
orientation |
'vertical' または 'horizontal' | カレンダーを縦向きまたは横向きで表示するかを設定できます。 |
visibleMonths |
string | 一度に表示する月数 (1 または 2) を指定します。 |
showWeekNumbers |
string | カレンダーに週番号の列を表示するかどうかを設定します。 |
open |
boolean | カレンダー ピッカーが開いているかどうかを判断します。 |
keepOpenOnSelect |
boolean | 日付を選択した後もカレンダー ピッカーを開いたままにします。 |
keepOpenOnOutsideClick |
boolean | カレンダー ピッカーの外側をクリックしても、カレンダー ピッカーを開いたままにします。 |
weekStart |
string | 週の最初の曜日を設定します。 |
hideOutsideDays |
boolean | 現在の月ビューの範囲外の日を非表示にします。 |
hideHeader |
boolean | カレンダー ヘッダーを非表示にします (ダイアログ モードでのみ適用されます)。 |
headerOrientation |
'vertical' または 'horizontal' | カレンダーのヘッダーを縦方向または横方向に配置します (ダイアログ モードのみ)。 |
activeDate |
Date | カレンダーで最初にハイライト表示される日付を設定します。設定されていない場合は、現在の日付がアクティブ日付になります。 |
<IgrDateRangePicker orientation='vertical' visibleMonths={1} showWeekNumbers/>
Min (最小値) および Max (最大値)
min および max プロパティを使用して、定義した範囲外の日付を無効にすることで、ユーザーの入力を制限することもできます。これらのプロパティはバリデーターとして機能するため、範囲外の日付が手動で入力された場合でも、IgrDateRangePicker は無効になります。
<IgrDateRangePicker min={new Date('2025-05-06')} max={new Date('2025-05-10')}/>
カスタムおよび定義済みの日付範囲
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 日間までの範囲が自動的に選択されます。
無効日と特別な日
カレンダーで無効な日付を設定して、ユーザーが選択できる日付の範囲を絞り込むこともできます。無効にする日付を設定するには、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} />
);
フォーム
IgrDateRangePicker コンポーネントは、HTML フォーム要素とシームレスに使用することもできます。min、max、required プロパティはフォーム検証子として機能します。
追加構成
プロパティ
すでに紹介したプロパティに加えて、IgrDateRangePicker コンポーネントには動作をさらに細かく設定できるさまざまなプロパティが用意されています。
| 名前 | タイプ | 説明 |
|---|---|---|
disabled |
boolean | コンポーネントを無効にします。 |
nonEditable |
boolean | 入力フィールドでの入力を無効にします。 |
placeholder |
string | シングル インプット モード時のプレースホルダー テキスト。 |
placeholderStart |
string | 開始日入力 (2 インプット モード) のプレースホルダー テキスト。 |
placeholderEnd |
string | 終了日入力 (2 インプット モード) のプレースホルダー テキスト。 |
outlined |
boolean | Material テーマで、入力部分をアウトライン表示にするかどうかを設定します。 |
prompt |
string | 入力マスクで未入力部分に表示されるプロンプト文字。 |
resourceStrings |
IgcDateRangePickerResourceStrings | 日付範囲ピッカーとカレンダーをローカライズするためのリソース文字列。 |
スロット
IgrDateRangePicker コンポーネントでは、利用可能なスロットを使用して、カスタム コンテンツを追加したり、外観を変更したりすることも可能です。
シングル インプット モードでは、prefix および suffix スロットを使って、入力フィールドの前後にカスタム コンテンツを挿入できます。
<IgrDateRangePicker>
<IgrIcon slot='prefix' name='down_arrow_icon'></IgrIcon>
<IgrIcon slot='suffix' name='upload_icon'></IgrIcon>
</IgrDateRangePicker>
2 インプット モードでは、prefix-start、prefix-end、suffix-start、suffix-end スロットを使用して、それぞれの入力に対してカスタム コンテンツを追加できます。
clear-icon および calendar-icon スロットを使用すると、入力欄内のクリア ボタンとカレンダー ボタンのアイコンをカスタマイズできます。
<IgrDateRangePicker>
<IgrIcon slot="clear-icon" name="apps_icon"></IgrIcon>
<IgrIcon slot="calendar-icon" name="bin_icon"></IgrIcon>
</IgrDateRangePicker>
2 インプット モードでは、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 |
入力フィールドの下にコンテンツを描画します。 |
header-date |
カレンダー ヘッダーのデフォルトの現在の日付/範囲テキストを置き換えます。ダイアログ モードでのみ適用されます。 |
clear-icon-start |
開始入力 (2 インプット モード) のカスタム クリア アイコン。 |
clear-icon-end |
終了入力 (2 インプット モード) のカスタム クリア アイコン。 |
calendar-icon-start |
開始入力 (2 インプット モード) のカスタム カレンダー アイコン。 |
calendar-icon-end |
終了入力 (2 インプット モード) のカスタム カレンダー アイコン。 |
calendar-icon-open |
ピッカーが開いているときに表示されるアイコンまたはコンテンツ (2 インプット モードの両方に適用)。 |
calendar-icon-open-start |
開始入力 (2 インプット モード) の開いた状態で表示されるアイコンやコンテンツ。 |
calendar-icon-open-end |
終了入力 (2 インプット モード) の開いた状態で表示されるアイコンやコンテンツ。 |
メソッド
IgrDateRangePicker は、プロパティやスロットに加えて、次のメソッドも公開しています:
| 名前 | 説明 |
|---|---|
show |
カレンダー ピッカー コンポーネントを表示します。 |
hide |
カレンダー ピッカー コンポーネントを非表示にします。 |
toggle |
カレンダー ピッカーの表示／非表示を切り替えます。 |
clear |
入力フィールドをクリアして、ユーザー入力を削除します。 |
select |
ピッカーで日付範囲の値を選択します。 |
setCustomValidity |
カスタム検証メッセージを設定します。提供されたメッセージが空でない場合、入力は無効 (invalid) としてマークされます。 |
スタイル設定
IgrDateRangePicker コンポーネントは IgrCalendar コンポーネントを使用しているため、Calendar の CSS パーツも継承されており、両コンポーネントをシームレスにスタイル設定できます。Calendar コンポーネントで使用可能なすべての CSS パーツの一覧はこちらをご覧ください: カレンダーのスタイル設定。Calendar の CSS パーツに加えて、IgrDateRangePicker は以下のような独自の CSS パーツも提供しており、外観をさらにカスタマイズできます:
| 名前 | 説明 |
|---|---|
separator |
2 つの入力欄の間に表示されるセパレーター要素。 |
ranges |
カスタムおよび定義済み範囲を表示するラッパー。 |
label |
ターゲットの入力の上に表示されるラベルのラッパー。 |
container |
すべての主要な入力要素を保持するメイン ラッパー。 |
input |
ネイティブ入力要素。 |
prefix |
プレフィックス ラッパー。 |
suffix |
サフィックス ラッパー。 |
calendar-icon |
カレンダー アイコンのラッパー (閉じた状態)。 |
calendar-icon-start |
開始入力のカレンダー アイコンのラッパー (閉じた状態、2 インプット)。 |
calendar-icon-end |
終了入力のカレンダー アイコンのラッパー (閉じた状態、2 インプット)。 |
calendar-icon-open |
カレンダー アイコンのラッパー (開いた状態)。 |
calendar-icon-open-start |
開始入力のカレンダー アイコンのラッパー (開いた状態、2 インプット)。 |
calendar-icon-open-end |
終了入力のカレンダー アイコンのラッパー (開いた状態、2 インプット)。 |
clear-icon |
クリア アイコンのラッパー (シングル インプット)。 |
clear-icon-start |
開始入力 (2 入力) のクリア アイコン ラッパー。 |
clear-icon-end |
終了入力 (2 入力) のクリア アイコン ラッパー。 |
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);
}