syncfusion-react-calendars

Syncfusion React カレンダーの実装

カレンダー

Syncfusion React の CalendarComponent は、高度にカスタマイズ可能なカレンダー UI コントロールで、ユーザーが単一または複数の日付を選択できます。複数のビュー（月、年、10 年）、ナビゲーション、週番号、無効な日付、カスタム日付セルのレンダリング、ローカライズ、RTL サポート、および完全なアクセシビリティ（WCAG 2.2 準拠）に対応しています。

クイックスタート（React）

インストール

npm install @syncfusion/ej2-react-calendars @syncfusion/ej2-base

基本的な例（App.jsx）

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

export default function App() {
  const [value, setValue] = useState(new Date());
  const onChange = (args) => setValue(args.value || args);

  return (
    <div style={{ padding: 20 }}>
      <h3>Select a date</h3>
      <CalendarComponent value={value} change={onChange} />
      <p>Selected: {value.toDateString()}</p>
    </div>
  );
}

注意：

• change イベントを使用して、選択した日付を React の状態と同期します。
• コントロールのスタイルを設定するため、テーマ CSS を一度だけ（グローバルまたはコンポーネントレベルで）インポートします。

ガイダンスとパターン

• 制御コンポーネント： React の状態を信頼できる唯一の情報源として維持し、change イベントで value を更新します。
• 複数選択： isMultiSelection={true} と values プロパティを使用し、addDate()／removeDate() メソッドを使います。
• プログラムによるナビゲーション： ref を使って navigateTo(view, date) を呼び出します。両方の引数が必要です（references/getting-started-react.md を参照）。
• 日付範囲： 範囲選択には DateRangePicker（別のコンポーネント）を使用します。Calendar 自体には、範囲を組み込みでハイライトするモードはありません。
• アクセシビリティ： role="region" を持つラッパー要素と、通知用の独立した aria-live 領域を使用します。これらは Calendar の直接のプロパティではありません。
• 週番号： weekNumber={true} で有効にします（正しいプロパティ名です）。

参考資料

現在のタスクに合った参考資料を参照してください。

はじめに

📄 参照： references/getting-started-react.md

• インストールと npm のセットアップ
• React コンポーネントの例
• CSS／テーマのインポート
• ref とメソッドの使用

日付の選択

📄 参照： references/date-selection.md

• 単一の日付の選択
• 複数の日付と範囲
• 最小値／最大値の制約
• 特定の日付の無効化

カレンダービュー

📄 参照： references/calendar-views.md

• 月、年、10 年のビュー
• ビュー間の移動
• 初期値と深度の制御
• プログラムによるナビゲーション

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

📄 参照： references/styling-customization.md

• テーマの選択と切り替え
• CSS クラスのカスタマイズ
• カスタム日付セルのレンダリング
• RTL とレスポンシブデザイン

イベントとメソッド

📄 参照： references/events-methods.md

• イベントハンドラー（change、created、renderDayCell）
• ref と命令型メソッドの使用
• 高度な renderDayCell フック
• イベント追跡のパターン

アクセシビリティとグローバル化

📄 参照： references/accessibility-globalization.md

• WCAG 2.1 準拠
• キーボードナビゲーション
• ARIA 属性
• ロケールのサポートと RTL
• アクセシビリティのテスト

API リファレンス（クイック参照）

📄 参照： references/api-reference.md

• プロパティ、イベント、メソッドの一覧
• 一般的な列挙型と型
• 上流のドキュメントへのリンク

トラブルシューティングとヒント

• スタイルが適用されない： CSS のインポート先が node_modules/@syncfusion/ej2-calendars/styles/ であり、コンポーネントのスタイルより前に読み込まれていることを確認します。
• React の状態が一致しない： value プロパティと change イベントを使用して React の状態を同期します。フレームワーク固有のバインディングには依存しないでください。
• 複数の日付選択が機能しない： isMultiSelection={true} を設定し、初期配列には value ではなく values を使用していることを確認します。
• navigateTo が機能しない： このメソッドには 2 つの引数が必要です。navigateTo(view: CalendarView, date: Date)。
• 「Cannot find module」： npm install @syncfusion/ej2-react-calendars @syncfusion/ej2-base を実行し、package.json を確認します。
• 週番号が表示されない： weekNumber={true} を使用します（showWeekNumber ではありません）。

DatePicker

Syncfusion React の DatePickerComponent は、単一の日付を選択するためのカレンダーポップアップを備えた、直感的な入力コントロールです。柔軟な書式設定、マスク入力、最小／最大日付の検証、厳密モード、複数の入力形式、カスタム日付レンダリング、ローカライズに対応し、制御された React コンポーネントとしてシームレスに統合できます。

コンポーネントの概要

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	年の第 1 週のルール
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 プロパティ（月、年、10年）
• ビュー階層を制限する 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 テーマ（base、buttons、inputs、popups、calendars）をすべてインポートします
• 現在の日付には 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. 生年月日の選択に使う年／10年表示

<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;
    }
  }}
/>

DateRangePicker

Syncfusion React の DateRangePickerComponent を使うと、ユーザーは開始日と終了日の範囲を選択できます。プリセット、検証、カスタム形式、区切り文字の設定、モバイルの全画面モード、高度な範囲制約（minDays、maxDays、min、max）が標準でサポートされています。

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

はじめに

📄 参照: references/getting-started.md

• npm によるインストール（@syncfusion/ej2-react-calendars）
• CSS のインポートとテーマの設定
• DateRangePicker の基本的な実装
• クラスコンポーネントと関数コンポーネントの設定
• コンポーネントの初期化と構造
• 開発サーバーの起動
• よくある問題のトラブルシューティング

日付範囲の選択

📄 参照: references/date-range-selection.md

• 開始日と終了日のプロパティ
• 日付範囲の検証パターン
• 最小日付と最大日付の制約
• 無効な日付の設定
• 日付範囲のプリセット（過去 7 日間、過去 30 日間など）
• 値のバインドと双方向の更新
• 読み取り専用状態と無効状態
• プレースホルダーとラベル

日付範囲の書式設定

📄 参照： references/date-range-formatting.md

• 日付書式文字列のオプション（MM/dd/yyyy、dd-MMM-yyyy など）
• 表示形式と入力形式
• ロケールに基づく日付書式設定
• 開始日と終了日の間に指定するカスタム区切り文字
• フロートラベルの種類（Never、Always、Auto）
• プレースホルダーテキストのカスタマイズ
• DOM 属性用の htmlAttributes

イベントとメソッド

📄 参照： references/events-and-methods.md

• イベントハンドラー（change、open、close、blur、focus、select）
• イベント引数の構造
• メソッド（show、hide、focusIn、focusOut、reset、destroy）
• useRef による命令的な制御
• ライフサイクルイベント（created、destroyed）
• イベントのパターンとベストプラクティス
• 値のクリアと状態のリセット
• DateRangeSelectingEvent と ChangedEventArgs

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

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

• cssClass による CSS クラスのカスタマイズ
• テーマのオプション（Material、Bootstrap、Fluent、Tailwind、Fabric）
• モバイルデバイス向けの全画面モード
• RTL（右から左へ記述する言語）への対応
• プリセット範囲のカスタマイズ
• Z-index の管理
• 幅と高さの設定
• アクセシビリティ機能と ARIA 属性

API リファレンス

📄 参照： references/api-reference.md

• すべてのプロパティ一覧（35 件以上）
• すべてのメソッドとシグネチャ（8 メソッド）
• すべてのイベントとイベント引数（12 イベント）
• 型定義とインターフェイス
• デフォルト値と制約
• 各プロパティとメソッドのユースケース

高度なパターン

📄 参照： references/advanced-patterns.md

• 日付範囲の検証を伴うフォーム送信
• キーボードショートカットとキー操作
• サーバーのタイムゾーンオフセット処理
• 永続化と localStorage
• 複数コンポーネントの連携（開始日と終了日のバインディング）
• 遅延読み込みによるパフォーマンスの最適化
• エラー処理と検証のパターン
• 複雑な日付範囲のシナリオ（会計年度、四半期）

クイックスタート

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-buttons/styles/material3.css';
import '@syncfusion/ej2-lists/styles/material3.css';
import '@syncfusion/ej2-inputs/styles/material3.css';
import '@syncfusion/ej2-popups/styles/material3.css';
import '@syncfusion/ej2-calendars/styles/material3.css';

function App() {
  const [selectedRange, setSelectedRange] = React.useState<[Date, Date] | null>(null);

  const handleDateRangeChange = (e: any) => {
    setSelectedRange([e.startDate, e.endDate]);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h2>Select Date Range</h2>
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select a range"
        change={handleDateRangeChange}
      />
      {selectedRange && (
        <p>
          Selected: {selectedRange[0]?.toLocaleDateString()} - {selectedRange[1]?.toLocaleDateString()}
        </p>
      )}
    </div>
  );
}

export default App;

一般的なパターン

パターン 1：プリセットオプション付きの日付範囲

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function ReportingDashboard() {
  const [dateRange, setDateRange] = React.useState<[Date, Date] | null>(null);

  const getDateRangePresets = () => {
    const today = new Date();
    const yesterday = new Date(today);
    yesterday.setDate(today.getDate() - 1);
    
    const last7Days = new Date(today);
    last7Days.setDate(today.getDate() - 7);
    
    const last30Days = new Date(today);
    last30Days.setDate(today.getDate() - 30);
    
    const thisMonth = new Date(today.getFullYear(), today.getMonth(), 1);
    const lastMonth = new Date(today.getFullYear(), today.getMonth(), 0);

    return [
      { text: 'Today', value: [today, today] },
      { text: 'Yesterday', value: [yesterday, yesterday] },
      { text: 'Last 7 Days', value: [last7Days, today] },
      { text: 'Last 30 Days', value: [last30Days, today] },
      { text: 'This Month', value: [thisMonth, today] },
      { text: 'Last Month', value: [new Date(today.getFullYear(), today.getMonth() - 1, 1), lastMonth] },
    ];
  };

  const handlePresetClick = (start: Date, end: Date) => {
    setDateRange([start, end]);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h3>Analytics Report</h3>
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select report date range"
        startDate={dateRange?.[0]}
        endDate={dateRange?.[1]}
        change={(e: any) => setDateRange([e.startDate, e.endDate])}
      />
      
      <div style={{ marginTop: '15px' }}>
        {getDateRangePresets().map((preset) => (
          <button
            key={preset.text}
            onClick={() => handlePresetClick(preset.value[0], preset.value[1])}
            style={{ marginRight: '10px', padding: '5px 10px' }}
          >
            {preset.text}
          </button>
        ))}
      </div>
    </div>
  );
}

export default ReportingDashboard;

パターン 2：検証付きの日付範囲

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function BookingForm() {
  const [dateRange, setDateRange] = React.useState<[Date, Date] | null>(null);
  const [validationError, setValidationError] = React.useState<string>('');

  const minDate = new Date();
  const maxDate = new Date();
  maxDate.setDate(maxDate.getDate() + 90); // 90 days from now

  const handleDateRangeChange = (e: any) => {
    setValidationError('');
    
    if (!e.startDate || !e.endDate) {
      return;
    }

    const start = new Date(e.startDate);
    const end = new Date(e.endDate);

    // Validation checks
    if (start > end) {
      setValidationError('Start date must be before end date');
      return;
    }

    const daysDifference = (end.getTime() - start.getTime()) / (1000 * 60 * 60 * 24);
    if (daysDifference > 30) {
      setValidationError('Date range cannot exceed 30 days');
      return;
    }

    setDateRange([start, end]);
  };

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (dateRange && !validationError) {
      console.log('Booking dates:', {
        checkIn: dateRange[0].toLocaleDateString(),
        checkOut: dateRange[1].toLocaleDateString(),
      });
    }
  };

  return (
    <form onSubmit={handleSubmit} style={{ padding: '20px', maxWidth: '500px' }}>
      <h3>Book Your Stay</h3>
      
      <label style={{ display: 'block', marginBottom: '8px' }}>
        Select Check-in and Check-out Dates (Max 30 days)
      </label>
      
      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select check-in and check-out"
        min={minDate}
        max={maxDate}
        startDate={dateRange?.[0]}
        endDate={dateRange?.[1]}
        change={handleDateRangeChange}
        style={{ width: '100%', marginBottom: '8px' }}
      />

      {validationError && (
        <div style={{ color: 'red', marginBottom: '10px', fontSize: '14px' }}>
          ⚠️ {validationError}
        </div>
      )}

      <ButtonComponent 
        type="submit" 
        isPrimary={true} 
        disabled={!dateRange || !!validationError}
      >
        Book Now
      </ButtonComponent>
    </form>
  );
}

export default BookingForm;

パターン 4：イベント処理と状態管理

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function EventTrackingExample() {
  const [dateRange, setDateRange] = React.useState<[Date, Date] | null>(null);
  const [eventLog, setEventLog] = React.useState<string[]>([]);

  const handleSelect = (e: any) => {
    setEventLog(prev => [
      ...prev, 
      `Selected: ${e.startDate?.toLocaleDateString()} to ${e.endDate?.toLocaleDateString()}`
    ]);
  };

  const handleChange = (e: any) => {
    setDateRange([e.startDate, e.endDate]);
    setEventLog(prev => [...prev, `Changed: ${new Date().toLocaleTimeString()}`]);
  };

  const handleOpen = (e: any) => {
    setEventLog(prev => [...prev, `Popup opened at ${new Date().toLocaleTimeString()}`]);
  };

  const handleClose = (e: any) => {
    setEventLog(prev => [...prev, `Popup closed at ${new Date().toLocaleTimeString()}`]);
  };

  const clearLog = () => {
    setEventLog([]);
  };

  return (
    <div style={{ padding: '20px', display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '20px' }}>
      <div>
        <h3>DateRangePicker</h3>
        <DateRangePickerComponent
          id="daterangepicker"
          placeholder="Select date range"
          select={handleSelect}
          change={handleChange}
          open={handleOpen}
          close={handleClose}
        />
      </div>

      <div style={{ padding: '10px', border: '1px solid #ccc', borderRadius: '4px' }}>
        <h3>Event Log</h3>
        <button 
          onClick={clearLog}
          style={{ 
            padding: '5px 10px', 
            marginBottom: '10px',
            backgroundColor: '#f0f0f0',
            border: '1px solid #ccc',
            cursor: 'pointer'
          }}
        >
          Clear Log
        </button>
        <ul style={{ maxHeight: '300px', overflowY: 'auto', margin: 0, paddingLeft: '20px' }}>
          {eventLog.map((event, idx) => (
            <li key={idx} style={{ marginBottom: '5px', fontSize: '12px' }}>
              {event}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}

export default EventTrackingExample;

パターン 5：カスタム日付範囲形式

import { DateRangePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function DateFormatDemo() {
  const [formatType, setFormatType] = React.useState<'short' | 'long' | 'custom'>('short');
  const [dateRange, setDateRange] = React.useState<[Date, Date] | null>(null);

  const getFormat = () => {
    switch (formatType) {
      case 'short':
        return 'M/d/yyyy';
      case 'long':
        return 'MMMM d, yyyy';
      case 'custom':
        return 'dd-MMM-yy';
      default:
        return 'M/d/yyyy';
    }
  };

  return (
    <div style={{ padding: '20px' }}>
      <h3>Date Range Format Options</h3>
      
      <div style={{ marginBottom: '15px' }}>
        <label style={{ marginRight: '10px' }}>Format Type:</label>
        {(['short', 'long', 'custom'] as const).map((format) => (
          <label key={format} style={{ marginRight: '15px' }}>
            <input
              type="radio"
              name="format"
              value={format}
              checked={formatType === format}
              onChange={(e) => setFormatType(e.target.value as any)}
            />
            {format.charAt(0).toUpperCase() + format.slice(1)}
          </label>
        ))}
      </div>

      <div style={{ marginBottom: '10px', padding: '10px', backgroundColor: '#f5f5f5' }}>
        <strong>Format String:</strong> {getFormat()}
      </div>

      <DateRangePickerComponent
        id="daterangepicker"
        placeholder="Select date range"
        format={getFormat()}
        startDate={dateRange?.[0]}
        endDate={dateRange?.[1]}
        change={(e: any) => setDateRange([e.startDate, e.endDate])}
      />

      {dateRange && (
        <div style={{ marginTop: '15px', padding: '10px', backgroundColor: '#e8f5e9' }}>
          <p>
            <strong>Formatted Output:</strong> {dateRange[0].toLocaleDateString('en-US')} - {dateRange[1].toLocaleDateString('en-US')}
          </p>
        </div>
      )}
    </div>
  );
}

export default DateFormatDemo;

主要な Props リファレンス

• Prop: startDate: 型: Date — デフォルト: null — 範囲の初期開始日です。
• Prop: endDate: 型: Date — デフォルト: null — 範囲の初期終了日です。
• Prop: min: 型: Date — デフォルト: new Date(1900, 0, 1) — 選択可能な最小日付です。
• Prop: max: 型: Date — デフォルト: new Date(2099, 11, 31) — 選択可能な最大日付です。
• Prop: value: 型: Date[] | DateRange — デフォルト: null — 開始日と終了日を取得または設定します。
• Prop: format: 型: string | RangeFormatObject — デフォルト: null — 日付の表示形式と入力形式です。
• Prop: placeholder: 型: string — デフォルト: null — 入力欄のプレースホルダーテキストです。
• Prop: enabled: 型: boolean — デフォルト: true — コンポーネントを有効または無効にします（disabled ではなく enabled を使用してください）。
• Prop: readonly: 型: boolean — デフォルト: false — 読み取り専用状態にし、編集を禁止します。
• Prop: allowEdit: 型: boolean — デフォルト: true — 入力欄のテキストを手動で編集できるようにします。
• Prop: cssClass: 型: string — デフォルト: '' — ルート要素にカスタム CSS クラスを追加します。
• Prop: floatLabelType: 型: FloatLabelType | string — デフォルト: Never — フローティングラベルの動作です（Never、Always、Auto）。
• Prop: separator: 型: string — デフォルト: '-' — 入力欄で開始日と終了日の間に表示する区切り文字列です。
• Prop: locale: 型: string — デフォルト: 'en-US' — 書式設定とローカライズに使用するロケールです。
• Prop: inputFormats: 型: string[] | RangeFormatObject[] — デフォルト: null — 入力値の解析に使用できる形式です。
• Prop: keyConfigs: 型: object — デフォルト: null — カスタムキーボードショートカットのマッピングです。
• Prop: firstDayOfWeek: 型: number — デフォルト: null — カレンダー表示で週の始まりとなる曜日です。
• Prop: dayHeaderFormat: 型: DayHeaderFormats — デフォルト: Short — ヘッダーに表示する曜日名の形式です。
• Prop: start: 型: CalendarView — デフォルト: Month — ポップアップを開いたときの初期カレンダー表示です。
• Prop: depth: 型: CalendarView — デフォルト: Month — カレンダーのナビゲーションで移動できる最大の深さです。
• Prop: weekNumber: 型: boolean — デフォルト: false — カレンダーの各週に週番号を表示します。
• Prop: weekRule: 型: WeekRule — デフォルト: FirstDay — 年の最初の週を定義するルールです。
• Prop: minDays: 型: number — デフォルト: null — 選択範囲で許可される最小日数です。
• Prop: maxDays: 型: number — デフォルト: null — 選択範囲で許可される最大日数です。
• Prop: strictMode: 型: boolean — デフォルト: false — true の場合、有効な範囲のみ入力できます。
• Prop: showClearButton: 型: boolean — デフォルト: true — クリアボタンの表示を切り替えます。
• Prop: fullScreenMode: 型: boolean — デフォルト: false — モバイルで全画面ポップアップを使用します。
• Prop: htmlAttributes: 型: { [key: string]: string } — デフォルト: {} — コンポーネント要素に適用する追加の HTML 属性です。
• Prop: serverTimezoneOffset: 型: number — デフォルト: null — 初期値の処理に使用するサーバーのタイムゾーンオフセット（分）です。
• Prop: width: 型: number | string — デフォルト: '' — コンポーネントの入力欄の幅です。
• Prop: zIndex: 型: number — デフォルト: 1000 — ポップアップ要素の z-index です。

---

次のステップ：

• references/getting-started.mdを読んで、最初の DateRangePicker をインストールしてセットアップします
• references/date-range-selection.mdで、範囲選択のパターンを確認します
• references/date-range-formatting.mdで、書式設定のオプションを確認します
• references/advanced-patterns.mdで、複雑なケースを確認します
• references/api-reference.mdで、API ドキュメント全体を参照します

DateTimePicker

Syncfusion React の DateTimePickerComponent は、日付と時刻の選択を単一のコントロールに統合します。カレンダーと時刻リストのポップアップ、カスタマイズ可能な時刻間隔、マスキング、厳密な検証、タイムゾーン処理、書式のカスタマイズ、完全なキーボードアクセシビリティを提供します。

ドキュメント（以下の順に参照してください）

• 📄 参照：references/getting-started.md — インストール、モジュールの設定、CSS のインポート、基本的な使い方
• 📄 参照：references/api-reference.md — すべてのプロパティ、メソッド、イベント
• 📄 参照：references/date-time-selection.md — 選択パターンと制約
• 📄 参照：references/time-configuration.md — 間隔、minTime/maxTime、スクロール動作
• 📄 参照：references/events-and-methods.md — イベントハンドラーとメソッドの使用方法
• 📄 参照：references/styling-and-customization.md — テーマと cssClass の使用方法
• 📄 参照：references/advanced-features.md — マスク入力、厳密モード、カレンダーモード、タイムゾーン処理
• 📄 参照：references/accessibility.md — キーボードと ARIA に関するガイダンス

クイックスタート（React + TypeScript）

1. パッケージをインストールします：

npm install @syncfusion/ej2-react-calendars

2. スタイルをインポートします（index.css またはコンポーネントの CSS 内）：

@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-calendars/styles/material3.css';

3. 最小限の動作例（App.tsx）：

import React, { useState } from 'react';
import { DateTimePickerComponent } from '@syncfusion/ej2-react-calendars';

export default function App() {
  const [value, setValue] = useState<Date | null>(new Date());

  return (
    <div style={{ padding: 20 }}>
      <h3>Choose date and time</h3>
      <DateTimePickerComponent
        value={value}
        change={(e) => setValue((e as any).value)}
        format="dd/MM/yyyy hh:mm a"
        step={15}
        placeholder="Select date and time"
      />
      <p>Selected: {value ? value.toString() : 'none'}</p>
    </div>
  );
}

よく使われるパターン

• 値の制御：value をバインドし、change 時に更新します。
• 範囲の制限：日付には min と max、時刻には minTime/maxTime を使用します。
• マスク入力：enableMask を有効にし、maskPlaceholder を指定します。
• ローカライズ：locale を設定するか、グローバルなカルチャ設定を使用します。
• キーボード優先：カスタムショートカットには keyConfigs を指定します。

主なプロパティの概要（すべての項目については API リファレンスを参照してください）

• value、min、max、step、format、enableMask、placeholder、cssClass、locale、readonly、enabled。

主なイベント

• change、open、close、created、destroyed、navigated、blur、focus、renderDayCell。

次の手順

• すべてのリファレンスファイルが作成され、公式の Syncfusion API に照らして検証されています（references/api-reference.md を参照してください）。
• 次に、テストケースガイドと検証チェックを実行してから、自動化された例を作成するか、リクエストに応じてプラットフォーム固有の注記を追加してください。
• テストの実行、completion-status.json の更新、または公開可能な成果物の作成を依頼してください。

TimePicker

Syncfusion React の TimePickerComponent は、時刻を選択するための軽量で機能豊富なコントロールです。12 時間／24 時間形式、時刻の間隔設定、最小／最大の制約、マスク入力、ローカライズ、全画面モードに対応し、React フォームにも簡単に統合できます。

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

はじめに

📄 参照： references/getting-started.md

• npm によるインストール（@syncfusion/ej2-react-calendars）
• app.module.ts での CalendarModule の設定
• CSS のインポートとテーマの設定
• TimePicker の基本的な実装
• useRef によるコンポーネントの登録
• 開発サーバーの起動
• よくあるトラブルシューティング

時刻の形式と表示

📄 参照： references/time-format-and-display.md

• 書式文字列のオプション（24 時間形式、12 時間形式）
• skeleton プロパティを持つ TimeFormatObject
• ロケールに基づく時刻の書式設定
• プレースホルダーテキストのカスタマイズ
• フロートラベルの種類（Never、Always、Auto）
• DOM 属性に対する htmlAttributes
• enableMask によるマスク入力
• マスクプレースホルダーの設定

時間範囲と選択

📄 参照： references/time-range-and-selection.md

• 時刻の最小値と最大値の制約
• 時刻の間隔（15、30、60 分）
• ScrollTo のデフォルト位置
• 値のバインディングと双方向更新
• 読み取り専用状態と無効状態
• OpenOnFocus の動作
• 時刻ポップアップリストの表示項目
• 間隔を指定した時刻

イベントとメソッド

📄 参照： references/events-and-methods.md

• イベントハンドラー（change、open、close、blur、focus）
• イベント引数の構造
• メソッド（show、hide、focusIn、focusOut）
• useRef による命令型制御
• ライフサイクルイベント（created、destroyed）
• イベントのパターンとベストプラクティス
• 値のクリアと状態のリセット
• カスタム書式設定のための ItemRender

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

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

• cssClass による CSS クラスのカスタマイズ
• テーマのオプション（Material、Bootstrap、Fluent、Tailwind）
• モバイルデバイス向けの全画面モード
• RTL（右から左へ記述する言語）のサポート
• 厳密モードの検証
• Z-index の管理
• 幅と高さの設定
• アクセシビリティ機能
• Theme Studio との統合

API リファレンス

📄 参照： references/api-reference.md

• プロパティの完全な一覧（26 個）
• シグネチャ付きのすべてのメソッド（5 個）
• イベント引数付きのすべてのイベント（9 個）
• 型定義とインターフェース
• デフォルト値と制約
• 各プロパティのユースケース

高度なパターン

📄 参照： references/advanced-patterns.md

• 検証を伴うフォーム送信
• キーボードショートカットと keyConfigs
• サーバーのタイムゾーンオフセットの処理
• 永続化と localStorage
• 複数コンポーネントの統合
• パフォーマンスの最適化
• エラー処理のパターン
• 複雑な検証のシナリオ

クイックスタート

import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';
import '@syncfusion/ej2-base/styles/material3.css';
import '@syncfusion/ej2-calendars/styles/material3.css';

function App() {
  const [selectedTime, setSelectedTime] = React.useState(new Date('1/1/2018 9:00 AM'));

  const handleChange = (e: any) => {
    setSelectedTime(e.value);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h2>Select Time</h2>
      <TimePickerComponent
        value={selectedTime}
        change={handleChange}
        placeholder="Select a time"
      />
      <p>Selected: {selectedTime ? selectedTime.toLocaleTimeString() : 'None'}</p>
    </div>
  );
}

export default App;

一般的なパターン

パターン 1：最小値と最大値を設定した Time Picker

import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function AppointmentScheduler() {
  const [appointmentTime, setAppointmentTime] = React.useState(new Date('1/1/2018 9:00 AM'));

  const minTime = new Date('1/1/2018 8:00 AM');
  const maxTime = new Date('1/1/2018 5:00 PM');

  return (
    <div>
      <h3>Select Appointment Time (8 AM - 5 PM)</h3>
      <TimePickerComponent
        value={appointmentTime}
        min={minTime}
        max={maxTime}
        step={30}
        change={(e: any) => setAppointmentTime(e.value)}
        placeholder="Choose time"
      />
    </div>
  );
}

export default AppointmentScheduler;

パターン 2：Time Picker の送信を含むフォーム

import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import { ButtonComponent } from '@syncfusion/ej2-react-buttons';
import * as React from 'react';

function ScheduleForm() {
  const [formData, setFormData] = React.useState({
    startTime: new Date('1/1/2018 9:00 AM'),
    endTime: new Date('1/1/2018 5:00 PM'),
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    console.log('Schedule data:', {
      startTime: formData.startTime?.toLocaleTimeString(),
      endTime: formData.endTime?.toLocaleTimeString(),
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <h3>Schedule Meeting</h3>
      
      <label>Start Time:</label>
      <TimePickerComponent
        value={formData.startTime}
        change={(e: any) => setFormData(prev => ({ ...prev, startTime: e.value }))}
      />

      <label style={{ marginTop: '10px' }}>End Time:</label>
      <TimePickerComponent
        value={formData.endTime}
        min={formData.startTime}
        change={(e: any) => setFormData(prev => ({ ...prev, endTime: e.value }))}
      />

      <ButtonComponent type="submit" isPrimary={true} style={{ marginTop: '15px' }}>
        Schedule
      </ButtonComponent>
    </form>
  );
}

export default ScheduleForm;

パターン 3：カスタム書式の Time Picker

import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function TimeFormatDemo() {
  const [time12hr, setTime12hr] = React.useState(new Date('1/1/2018 2:30 PM'));
  const [time24hr, setTime24hr] = React.useState(new Date('1/1/2018 14:30'));

  return (
    <div style={{ padding: '20px' }}>
      <div>
        <h4>12-Hour Format (hh:mm a)</h4>
        <TimePickerComponent
          value={time12hr}
          format="hh:mm a"
          change={(e: any) => setTime12hr(e.value)}
        />
        <p>Value: {time12hr?.toLocaleTimeString('en-US', { hour12: true })}</p>
      </div>

      <div style={{ marginTop: '20px' }}>
        <h4>24-Hour Format (HH:mm)</h4>
        <TimePickerComponent
          value={time24hr}
          format="HH:mm"
          change={(e: any) => setTime24hr(e.value)}
        />
        <p>Value: {time24hr?.toLocaleTimeString('en-US', { hour12: false })}</p>
      </div>
    </div>
  );
}

export default TimeFormatDemo;

パターン 4：イベント処理と状態管理

import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function EventTrackingExample() {
  const [selectedTime, setSelectedTime] = React.useState<Date | null>(null);
  const [eventLog, setEventLog] = React.useState<string[]>([]);

  const handleChange = (e: any) => {
    setSelectedTime(e.value);
    setEventLog(prev => [...prev, `Changed: ${e.value?.toLocaleTimeString()}`]);
  };

  const handleOpen = (e: any) => {
    setEventLog(prev => [...prev, 'Popup opened']);
  };

  const handleClose = (e: any) => {
    setEventLog(prev => [...prev, 'Popup closed']);
  };

  return (
    <div style={{ padding: '20px' }}>
      <h3>Time Picker with Event Tracking</h3>
      <TimePickerComponent
        value={selectedTime}
        change={handleChange}
        open={handleOpen}
        close={handleClose}
        placeholder="Select time to track events"
      />

      <div style={{ marginTop: '20px', padding: '10px', border: '1px solid #ccc' }}>
        <h4>Event Log:</h4>
        <ul>
          {eventLog.map((event, idx) => (
            <li key={idx}>{event}</li>
          ))}
        </ul>
      </div>
    </div>
  );
}

export default EventTrackingExample;

パターン 5：マスク付き時刻入力

import { TimePickerComponent } from '@syncfusion/ej2-react-calendars';
import * as React from 'react';

function MaskedTimePickerExample() {
  const [maskedTime, setMaskedTime] = React.useState(new Date('1/1/2018 10:30 AM'));

  return (
    <div style={{ padding: '20px' }}>
      <h3>Masked Time Input</h3>
      <TimePickerComponent
        value={maskedTime}
        enableMask={true}
        format="hh:mm a"
        maskPlaceholder={{
          hour: 'HH',
          minute: 'MM',
          second: 'SS',
        }}
        change={(e: any) => setMaskedTime(e.value)}
        placeholder="Enter time (HH:MM AM/PM)"
      />
      <p>Masked input helps users enter time in correct format</p>
    </div>
  );
}

export default MaskedTimePickerExample;

主なプロパティのリファレンス

プロパティ	型	デフォルト	用途
value	Date	null	現在選択されている時刻の値
format	string	カルチャーに基づく	時刻の表示形式（例：「HH:mm」、「hh:mm a」）
min	Date	00:00	選択可能な最小時刻
max	Date	00:00	選択可能な最大時刻
step	number	30	リスト項目間の時間間隔（分）
enabled	boolean	true	コンポーネントの有効／無効
readonly	boolean	false	読み取り専用状態（編集不可）
placeholder	string	-	入力欄のプレースホルダーテキスト
openOnFocus	boolean	false	入力欄にフォーカスしたときにポップアップを開く
enableMask	boolean	false	マスク入力モードを有効にする
enableRtl	boolean	false	右から左へのレイアウトを有効にする
strictMode	boolean	false	入力を検証し、有効な時刻に制限する
showClearButton	boolean	true	クリアボタンを表示／非表示にする
fullScreenMode	boolean	false	モバイルの全画面モード
cssClass	string	-	スタイル設定用のカスタム CSS クラス
floatLabelType	string	Never	フロートラベルの位置
allowEdit	boolean	true	手動での入力編集を許可する
locale	string	'en-US'	時刻の書式設定に使用するロケール
scrollTo	Date	-	ポップアップのデフォルトのスクロール位置
width	string/number	-	コンポーネントの幅
zIndex	number	1000	ポップアップの Z-index
serverTimezoneOffset	number	-	処理に使用するサーバーのタイムゾーンオフセット
htmlAttributes	object	{}	カスタム HTML 属性

---

次のステップ：

• references/getting-started.mdを読んで、最初の TimePicker をインストールして設定します
• references/time-format-and-display.mdで書式設定のオプションを確認します
• references/time-range-and-selection.mdで時刻の制約を確認します
• references/advanced-patterns.mdで複雑なシナリオを確認します