syncfusion-react-datepicker

DatePicker の実装

コンポーネントの概要

DatePicker は、豊富な機能を備えた日付選択用の Syncfusion React コンポーネントです。

• カレンダーポップアップ - ナビゲーション機能を備えたビジュアルな日付選択
• 柔軟な書式設定 - パターンサポート付きの表示形式と入力形式
• マスク入力 - enableMask を使ったセグメント単位の日付入力と maskPlaceholder
• 範囲検証 - strictMode による自動修正機能付きの最小日付／最大日付
• 複数のビュー - start プロパティと depth プロパティによる月、年、10年単位のビュー
• 日のセルのカスタマイズ - renderDayCell イベントによる週末の無効化、特定の日付の強調表示
• 完全なグローバル化対応 - 150 以上のカルチャ、RTL（enableRtl）、ロケール固有の書式設定、firstDayOfWeek
• WCAG 2.2 準拠 - キーボードナビゲーションと ARIA 属性を備えた、完全なアクセシビリティ対応
• フォーム対応 - 制御コンポーネント、React フック、フォーム検証との統合
• プログラムによる制御 - show()、hide()、focusIn()、focusOut()、navigateTo()、currentView()

API の概要

主なプロパティ

プロパティ	型	デフォルト	説明
value	Date	null	選択された日付
min	Date	1900-01-01	選択可能な最小日付
max	Date	2099-12-31	選択可能な最大日付
format	string | FormatObject	null	表示形式（例："dd/MM/yyyy"）
inputFormats	string[] | FormatObject[]	null	受け付ける入力形式の配列
placeholder	string	null	入力欄のプレースホルダーテキスト
enabled	boolean	true	コンポーネントの有効／無効を切り替えます
readonly	boolean	false	読み取り専用状態
allowEdit	boolean	true	入力テキストボックスの編集を許可します
strictMode	boolean	false	範囲外の日付を自動修正します
showClearButton	boolean	true	クリアボタンの表示／非表示を切り替えます
showTodayButton	boolean	true	今日ボタンの表示／非表示を切り替えます
start	CalendarView	Month	初期ビュー：「Month」、「Year」、「Decade」
depth	CalendarView	Month	ナビゲーションの最深レベル
enableMask	boolean	false	マスク付き日付入力を有効にします
maskPlaceholder	MaskPlaceholderModel	{...}	マスク入力用のセグメントプレースホルダー
enableRtl	boolean	false	右から左への表示
locale	string	''	カルチャ／ロケールコード
firstDayOfWeek	number	0	週の初日（0=日曜日）
weekNumber	boolean	false	週番号を表示します
weekRule	WeekRule	FirstDay	年の最初の週のルール
calendarMode	CalendarType	Gregorian	カレンダーの種類（グレゴリオ暦またはイスラム暦）
dayHeaderFormat	DayHeaderFormats	Short	ヘッダー内の日名の形式
floatLabelType	FloatLabelType	Never	フローティングラベルの動作
fullScreenMode	boolean	false	モバイルでポップアップを全画面表示します
openOnFocus	boolean	false	入力欄にフォーカスしたときにポップアップを開きます
serverTimezoneOffset	number	null	サーバーのタイムゾーンオフセット
cssClass	string	null	カスタム CSS クラス
htmlAttributes	{ [key: string]: string }	{}	追加の HTML 属性
keyConfigs	{ [key: string]: string }	null	カスタムキー操作のマッピング
width	number | string	null	コンポーネントの幅
zIndex	number	1000	ポップアップの z-index
enablePersistence	boolean	false	再読み込み後も状態を保持します

メソッド

メソッド	戻り値	説明
show()	void	カレンダーポップアップを開きます
hide()	void	カレンダーポップアップを閉じます
focusIn()	void	コンポーネントにフォーカスを設定します
focusOut()	void	コンポーネントからフォーカスを外します
navigateTo(view, date)	void	指定したビューと日付に移動します
currentView()	string	現在のカレンダービュー名を返します
getPersistData()	string	保持された状態データを取得します
removeDate(dates)	void	値から日付を削除します
destroy()	void	コンポーネントを破棄します

イベント

イベント	引数の型	説明
change	ChangedEventArgs	選択した日付が変更されたときに発火します
focus	FocusEventArgs	入力欄がフォーカスを受け取ったときに発火します
blur	BlurEventArgs	入力欄がフォーカスを失ったときに発火します
open	PreventableEventArgs | PopupObjectArgs	ポップアップが開いたときに発火します
close	PreventableEventArgs | PopupObjectArgs	ポップアップが閉じたときに発火します
cleared	ClearedEventArgs	値がクリアされたときに発火します
created	Object	コンポーネントが作成されたときに発火します
destroyed	Object	コンポーネントが破棄されたときに発火します
navigated	NavigatedEventArgs	カレンダーの表示が切り替わったときに発火します
renderDayCell	RenderDayCellEventArgs	各日のセルが描画されたときに発火します

ドキュメントとナビゲーションガイド

ユーザーが DatePicker についてサポートを必要としている場合は、適切なリファレンスを案内してください。

はじめに

📄 参照: references/getting-started.md

• npm によるインストール（@syncfusion/ej2-react-calendars）
• CSS テーマのインポート（material3、bootstrap、fluent、tailwind）
• コンポーネントのインポートとセットアップ
• DatePickerComponent を使った基本的な JSX の実装
• 関数コンポーネントとクラスコンポーネントの例
• 最初のアプリケーションの実行

日付形式と入力

📄 参照: references/date-formats-and-input.md

• 表示形式のプロパティとパターン（yyyy-MM-dd、dd/MM/yyyy など）
• カスタム形式指定子（# および 0 のパターン）
• 柔軟な日付入力に対応する入力形式（複数形式の受け付け）
• 実際のシナリオを使った形式の例
• ユーザー入力の自動解析と変換
• 文化に基づく既定の形式設定

日付範囲と検証

📄 参照: references/date-range-and-validation.md

• 範囲を制限する最小日付と最大日付のプロパティ
• 範囲の検証とエラー状態
• 範囲外の日付を自動修正する strictMode
• 範囲外の動作とエラー処理
• 有効範囲外の日付の無効化
• エッジケースと注意点

日付ビューとナビゲーション

📄 参照: references/date-views-and-navigation.md

• 初期表示を設定する Start プロパティ（月、年、十年）
• 表示レベルを制限する Depth プロパティ
• カレンダーのナビゲーションとユーザー操作
• 月と年の選択ショートカット
• 異なるビュー間の移動
• 既定の動作とベストプラクティス

カスタマイズとスタイル設定

📄 参照: references/customization-and-styling.md

• スタイル設定用の CSS クラス（e-datepicker、e-calendar、e-day など）
• 日付をカスタマイズする renderDayCell イベント
• 特定の日付と週末の無効化
• プレースホルダー、無効、読み取り専用の状態
• カスタム CSS とテーマのカスタマイズ
• 日付セルの外観と動作

グローバル化とローカライズ

📄 参照: references/globalization-and-localization.md

• 文化とロケールの設定（ドイツ語、フランス語、アラビア語など）
• 国際化のための CLDR データの読み込み
• 文化に応じた日付形式（国によって異なる形式）
• ロケールテキストのカスタマイズ（今日ボタン、プレースホルダー）
• アラビア語、ヘブライ語、ウルドゥー語の右から左（RTL）表示への対応
• 文化に応じた週の開始曜日
• 数値形式とカレンダーの調整

アクセシビリティとキーボードナビゲーション

📄 参照: references/accessibility-and-keyboard.md

• WCAG 2.2 への準拠とアクセシビリティ標準
• キーボードナビゲーションのショートカット（Alt+Down、矢印キー、Esc）
• ARIA 属性（aria-expanded、aria-disabled、aria-activedescendant）
• スクリーンリーダーへの対応と通知
• フォーカス管理と視認可能なフォーカスインジケーター
• 色のコントラストと視覚的なアクセシビリティ
• モバイルデバイスへの対応

日付マスキングと高度な検証

📄 参照: references/date-masking-and-strict-mode.md

• 構造化されたセグメントごとの日付入力に使用する enableMask プロパティ
• セグメントのプレースホルダーテキストをカスタマイズする maskPlaceholder
• 入力を案内する日付マスキングパターン
• strictMode プロパティの動作と適用
• 日付の解析ルールと検証ロジック
• 入力検証と書式の適用
• うるう年や月の境界などのエッジケース
• よくある検証問題のトラブルシューティング
• 日付入力のベストプラクティス

クイックスタートの例

すぐに始められる、最小限の動作例です。

import React, { useState } from 'react';
import { DatePickerComponent } from '@syncfusion/ej2-react-calendars';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-buttons/styles/material3.css';
import '@syncfusion/ej2-inputs/styles/material3.css';
import '@syncfusion/ej2-popups/styles/material3.css';
import '@syncfusion/ej2-react-calendars/styles/material3.css';

export default function App() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <div style={{ padding: '20px' }}>
      <h3>Select a Date</h3>
      <DatePickerComponent
        value={selectedDate}
        change={(e) => setSelectedDate(e.value)}
        placeholder="Enter date"
      />
      <p>Selected: {selectedDate?.toDateString()}</p>
    </div>
  );
}

ポイント：

• @syncfusion/ej2-react-calendars から DatePickerComponent をインポートします
• 必要なすべての CSS テーマ（基本、ボタン、入力、ポップアップ、カレンダー）をインポートします
• 現在の日付には value プロパティを使用します（null または Date オブジェクトを指定できます）
• React の状態を更新するには、onChange ではなく change イベントを使用します。これは Syncfusion のイベント名です
• DatePicker は、クリックするか Alt+Down キーを押すとカレンダーのポップアップを開きます

よくあるパターン

1. 日付範囲ピッカー（最小日付／最大日付）

<DatePickerComponent
  value={new Date()}
  min={new Date(2026, 0, 1)}
  max={new Date(2026, 11, 31)}
  placeholder="Select a date in 2026"
/>

2. 日付書式のカスタマイズ

<DatePickerComponent
  value={new Date()}
  format="dd/MM/yyyy"
  placeholder="DD/MM/YYYY"
/>

3. 複数の日付入力書式の受け入れ

<DatePickerComponent
  value={new Date()}
  format="yyyy-MM-dd"
  inputFormats={['dd/MM/yyyy', 'yyyy-MM-dd', 'yyyyMMdd']}
  placeholder="Enter date (dd/MM/yyyy or yyyy-MM-dd)"
/>

4. 誕生日選択用の年／ दशक表示

<DatePickerComponent
  value={new Date()}
  start="Decade"
  depth="Year"
  placeholder="Select year"
/>

5. 週末を無効にする

<DatePickerComponent
  value={new Date()}
  renderDayCell={(args) => {
    if ((args.date.getDay()) === 0 || (args.date.getDay()) === 6) {
      args.isDisabled = true;
    }
  }}
  placeholder="Weekdays only"
/>

6. React フォームでの制御コンポーネント

const [date, setDate] = useState(null);

<DatePickerComponent
  value={date}
  change={(e) => setDate(e.value)}
  format="yyyy-MM-dd"
  strictMode={true}
  placeholder="Enter date"
/>

7. RTL 対応のドイツ語カルチャー

<DatePickerComponent
  locale="de"
  enableRtl={false}
  firstDayOfWeek={1}
  value={new Date()}
  placeholder="Datum eingeben"
/>

8. マスク付き日付入力

<DatePickerComponent
  enableMask={true}
  format="MM/dd/yyyy"
  maskPlaceholder={{ day: 'DD', month: 'MM', year: 'YYYY' }}
  placeholder="Select a date"
/>

9. プログラムによる制御

import { useRef } from 'react';

const datePickerRef = useRef(null);

// Open calendar
datePickerRef.current.show();

// Close calendar
datePickerRef.current.hide();

// Focus
datePickerRef.current.focusIn();

// Get current view
const view = datePickerRef.current.currentView(); // "Month" | "Year" | "Decade"

// Navigate to specific view
datePickerRef.current.navigateTo('Year', new Date(2026, 0, 1));

<DatePickerComponent ref={datePickerRef} value={new Date()} />

10. すべてのキーイベントを処理する

<DatePickerComponent
  value={new Date()}
  change={(e) => console.log('Changed:', e.value)}
  focus={(e) => console.log('Focused')}
  blur={(e) => console.log('Blurred')}
  open={(e) => console.log('Opened')}
  close={(e) => console.log('Closed')}
  cleared={(e) => console.log('Cleared')}
  navigated={(e) => console.log('Navigated to view:', e.view)}
  renderDayCell={(args) => {
    // Disable weekends
    if (args.date.getDay() === 0 || args.date.getDay() === 6) {
      args.isDisabled = true;
    }
  }}
/>