syncfusion-angular-calendars

Syncfusion Angular Calendar の実装

カレンダー

Angular アプリケーションで Syncfusion Essential JS 2 Calendar コンポーネントを実装するための包括的なガイドです。日付ピッカーの作成、カレンダービューの管理、イベントの処理、スタイルのカスタマイズについて説明します。

Calendar の概要

Syncfusion Angular Calendar コンポーネントは、次の機能を提供する日付選択ウィジェットです。

• 複数のカレンダービュー： Month（デフォルト）、Year、Decade の各ビューでスムーズに移動できます
• 日付選択モード： isMultiSelection プロパティを使用して、単一または複数の日付を選択できます
• ナビゲーション制御： navigateTo() メソッドを使用して、ビューをプログラムで切り替えられます
• 日付操作メソッド： addDate() と removeDate() を使用して、複数選択を管理できます
• 包括的なイベントシステム： change、created、navigated、renderDayCell、destroyed イベント
• ローカライズのサポート： ロケールに応じた書式、曜日ヘッダーの書式、週の開始曜日
• アクセシビリティ： WCAG 2.2 に完全準拠、キーボード操作、RTL をサポート
• 豊富なカスタマイズ機能： CSS クラス、カスタムレンダリング、日付セルのカスタマイズ
• 永続化： ページの再読み込み後も任意で状態を保持できます

パッケージ： @syncfusion/ej2-angular-calendars

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

ニーズに応じて、以下のリファレンスを参照してください。

はじめに

📄 参照： references/getting-started.md

• パッケージのインストールとモジュールの設定
• CSS テーマのインポートと依存関係
• 基本的なカレンダーの実装
• Angular でのコンポーネントの初期化
• 実行とテストの設定

カレンダービュー

📄 参照： references/calendar-views.md

• Month ビュー（デフォルト表示）
• Year ビューの実装
• Decade ビューの実装
• ビューの移動と切り替え
• start プロパティの使用方法
• ビューを制限する depth プロパティ

日付の選択

📄 参照： references/date-selection.md

• 単一の日付の選択
• 複数の日付の選択（isMultiSelection）
• 単一の日付に使用する value プロパティ
• 複数の日付に使用する values 配列
• 最小／最大日付の制約
• 日付範囲の検証

イベントとメソッド

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

• イベントハンドラー（change、created、navigated、renderDayCell、destroyed）
• 複数選択に使用する addDate() メソッド
• 複数選択に使用する removeDate() メソッド
• プログラムによるナビゲーションに使用する navigateTo()
• アクティブなビューを取得する currentView()
• 永続化データを取得する getPersistData()
• カレンダーウィジェットを破棄する destroy()
• 日付のスタイルをカスタマイズする RenderDayCell

カレンダーのナビゲーション

📄 参照： references/calendar-navigation.md

• 月のナビゲーションコントロール
• Year ビューと Decade ビューの切り替え
• 今日ボタン（showTodayButton）
• firstDayOfWeek プロパティ
• 週番号の表示（weekNumber）
• キーボードショートカットとナビゲーション

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

📄 参照： references/accessibility-and-globalization.md

• WCAG 2.2 および Section 508 への準拠
• WAI-ARIA 属性とロール
• キーボード操作（矢印キー、Enter、スペースバー）
• スクリーンリーダーとの互換性
• ローカライズ（locale プロパティ）
• 曜日ヘッダーの書式（Short、Narrow、Abbreviated、Wide）
• RTL（右から左への表記）のサポート

スタイルとカスタマイズ

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

• CSS クラスのカスタマイズ（.e-calendar、.e-day-cell、.e-selected）
• テーマの選択（Material、Bootstrap、Tailwind、Fabric）
• ダークモードの実装
• renderDayCell による日付セルのカスタムスタイル
• 無効な日付のスタイル設定
• ホバー状態とフォーカス状態

API リファレンス

📄 参照： references/api-reference.md

• プロパティの完全なリファレンス（value、values、isMultiSelection、min、max、start、depth、showTodayButton、locale、dayHeaderFormat、weekNumber、weekRule、firstDayOfWeek、cssClass、enableRtl、enabled、calendarMode、keyConfigs、enablePersistence、serverTimezoneOffset）
• すべてのメソッドシグネチャと使用例（addDate、removeDate、navigateTo、currentView、getPersistData、destroy）
• イベント引数の型（ChangedEventArgs、NavigatedEventArgs、RenderDayCellEventArgs）
• キーボードショートカットのキー設定
• カレンダーモード（Gregorian、Islamic）
• 戻り値の型と説明

クイックスタートの例

// app.component.ts
import { Component } from '@angular/core';
import { ChangedEventArgs } from '@syncfusion/ej2-calendars';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Single date selection
  selectedDate: Date = new Date();
  
  // Multiple date selection
  selectedDates: Date[] = [
    new Date(2026, 2, 15),
    new Date(2026, 2, 20),
    new Date(2026, 2, 25)
  ];
  
  // Calendar configuration
  minDate: Date = new Date(2020, 0, 1);
  maxDate: Date = new Date(2030, 11, 31);
  
  // Event handler
  onCalendarChange(args: ChangedEventArgs): void {
    console.log('Selected date:', args.value);
  }
}

<div style="padding: 20px; font-family: Arial, sans-serif;">
  <h2>Single Date Selection</h2>
  <ejs-calendar 
    [(ngModel)]="selectedDate"
    [min]="minDate"
    [max]="maxDate"
    (change)="onCalendarChange($event)">
  </ejs-calendar>
  <p>Selected: {{ selectedDate | date:'medium' }}</p>

  <h2>Multiple Date Selection</h2>
  <ejs-calendar 
    [(ngModel)]="selectedDates"
    [isMultiSelection]="true"
    [showTodayButton]="true">
  </ejs-calendar>
  <p>Selected dates: {{ selectedDates.length }} dates</p>
</div>

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

:host ::ng-deep .e-calendar {
  margin: 20px 0;
}

:host ::ng-deep .e-selected {
  background-color: #3f51b5;
  color: white;
}

よくあるパターン

パターン 1：カスタム日付範囲（2 つのカレンダーインスタンス）

Calendar コンポーネントには、範囲選択機能が組み込まれていません。min／max の制約と change イベントを使用して、2 つの Calendar インスタンスでカスタムの日付範囲ピッカーを実装します。

export class AppComponent {
  startDate: Date = new Date();
  endDate: Date = new Date();
  
  onStartDateChange(args: ChangedEventArgs): void {
    this.startDate = args.value;
    // Ensure end date is not before start date
    if (this.endDate < this.startDate) {
      this.endDate = this.startDate;
    }
  }
  
  onEndDateChange(args: ChangedEventArgs): void {
    this.endDate = args.value;
  }
  
  getDaysInRange(): number {
    const timeDiff = this.endDate.getTime() - this.startDate.getTime();
    return Math.ceil(timeDiff / (1000 * 3600 * 24)) + 1;
  }
}

<ejs-calendar [(ngModel)]="startDate" (change)="onStartDateChange($event)"></ejs-calendar>
<ejs-calendar [(ngModel)]="endDate" [min]="startDate" (change)="onEndDateChange($event)"></ejs-calendar>

パターン 2：日付を無効にしたカレンダー

renderDayCell イベントを使用して、特定の日付（週末や祝日など）を無効にします。

export class AppComponent {
  holidays: Date[] = [
    new Date(2026, 11, 25), // Christmas
    new Date(2026, 0, 1),   // New Year
  ];
  
  onRenderDayCell(args: RenderDayCellEventArgs): void {
    // Disable weekends
    if (args.date.getDay() === 0 || args.date.getDay() === 6) {
      args.isDisabled = true;
    }
    
    // Disable holidays
    if (this.isHoliday(args.date)) {
      args.isDisabled = true;
    }
  }
  
  private isHoliday(date: Date): boolean {
    return this.holidays.some(holiday => 
      holiday.toDateString() === date.toDateString()
    );
  }
}

パターン 3：追加／削除による複数選択

複数の選択済み日付をプログラムで管理します。

export class AppComponent {
  @ViewChild('calendar') calendarRef!: CalendarComponent;
  selectedDates: Date[] = [];
  
  addDateToSelection(date: Date): void {
    // Check if already selected
    if (!this.selectedDates.some(d => 
        d.toDateString() === date.toDateString())) {
      this.calendarRef.addDate(date);
    }
  }
  
  removeDateFromSelection(date: Date): void {
    this.calendarRef.removeDate(date);
  }
  
  clearAllDates(): void {
    if (this.selectedDates.length > 0) {
      this.calendarRef.removeDate(this.selectedDates);
    }
  }
}

パターン 4：年／10 年単位のビュー移動

異なるカレンダービューへの移動を実装します。

export class AppComponent {
  @ViewChild('calendar') calendarRef!: CalendarComponent;
  
  navigateToYear(year: number): void {
    const dateInYear = new Date(year, 0, 1);
    this.calendarRef.navigateTo('Year', dateInYear);
  }
  
  navigateToDecade(startYear: number): void {
    const dateInDecade = new Date(startYear, 0, 1);
    this.calendarRef.navigateTo('Decade', dateInDecade);
  }
  
  getCurrentView(): string {
    return this.calendarRef.currentView();
  }
}

パターン 5：リアクティブフォームとの連携

Calendar を Angular リアクティブフォームと連携させます。

export class AppComponent implements OnInit {
  dateForm: FormGroup;
  
  constructor(private fb: FormBuilder) {
    this.dateForm = this.fb.group({
      eventDate: [new Date(), Validators.required],
      eventName: ['', Validators.required]
    });
  }
  
  ngOnInit(): void {
    // Subscribe to date changes
    this.dateForm.get('eventDate')?.valueChanges.subscribe(date => {
      console.log('Event date changed:', date);
    });
  }
  
  submitForm(): void {
    if (this.dateForm.valid) {
      console.log('Form values:', this.dateForm.value);
    }
  }
}

<form [formGroup]="dateForm" (ngSubmit)="submitForm()">
  <div>
    <label for="eventDate">Event Date:</label>
    <ejs-calendar 
      id="eventDate"
      formControlName="eventDate">
    </ejs-calendar>
  </div>
  
  <div>
    <label for="eventName">Event Name:</label>
    <input 
      id="eventName"
      type="text"
      formControlName="eventName">
  </div>
  
  <button type="submit" [disabled]="!dateForm.valid">Submit</button>
</form>

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

プロパティ	型	説明	例
value	Date	選択された単一の日付	[value]="selectedDate"
values	Date[]	選択された複数の日付	[values]="selectedDates"
isMultiSelection	boolean	複数の日付選択を有効にする	[isMultiSelection]="true"
min	Date	選択可能な最小の日付	[min]="minDate"
max	Date	選択可能な最大の日付	[max]="maxDate"
start	CalendarView	初期ビュー（Month／Year／Decade）	start="Month"
depth	CalendarView	最大ビュー階層	depth="Month"
showTodayButton	boolean	今日ボタンを表示する	[showTodayButton]="true"
locale	string	文化／言語コード	locale="fr-FR"
dayHeaderFormat	DayHeaderFormats	曜日の表示形式（Short／Narrow／Abbreviated／Wide）	dayHeaderFormat="Abbreviated"
weekNumber	boolean	週番号を表示する	[weekNumber]="true"
weekRule	WeekRule	年の最初の週の規則（FirstDay／FirstFullWeek／FirstFourDayWeek）	weekRule="FirstFourDayWeek"
firstDayOfWeek	number	週の最初の曜日（0＝日曜日、1＝月曜日）	[firstDayOfWeek]="1"
cssClass	string	カスタム CSS クラス	cssClass="custom-calendar"
enableRtl	boolean	RTL レイアウトを有効にする	[enableRtl]="true"
enabled	boolean	コンポーネントを有効／無効にする	[enabled]="true"
calendarMode	CalendarType	カレンダーモード（Gregorian／Islamic）	calendarMode="Islamic"
keyConfigs	{ [key: string]: string }	カスタムキーボードショートカット	[keyConfigs]="keyConfigs"
enablePersistence	boolean	ページ再読み込み後も状態を保持する	[enablePersistence]="true"
serverTimezoneOffset	number | null	初期日付の処理に使用するサーバーのタイムゾーンオフセット	[serverTimezoneOffset]="330"

一般的なユースケース

ユースケース 1：イベント予約システム

• ユーザーがイベントの開始日と終了日を選択します
• 過去の日付と週末を無効にします
• 解決策：最小日付／最大日付と renderDayCell を組み合わせて、無効化ロジックを実装します
• 参考：カレンダービュー + イベントとメソッド

ユースケース 2：カンファレンスのスケジュール

• 複数の強調表示された日付（カンファレンス開催日）を表示します
• 計画を立てるために、年／年代を移動できるようにします
• 解決策：isMultiSelection を使用し、日付を強調表示して、ビュー間を移動します
• 参考：日付の選択 + カレンダーのナビゲーション

ユースケース 3：アクセシブルな予約フォーム

• キーボード操作に対応したカレンダーをフォームに統合します
• スクリーンリーダーに対応し、WCAG 2.2 に準拠します
• 解決策：リアクティブフォームとカレンダーイベントを使用します
• 参考：アクセシビリティとグローバリゼーション

ユースケース 4：多言語対応の日付ピッカー

• 複数の言語と日付形式に対応します
• アラビア語とヘブライ語では RTL 表示にします
• 解決策：locale プロパティとローカライズを使用します
• 参考：アクセシビリティとグローバリゼーション

ユースケース 5：動的な日付の制約

• ビジネスロジック（空き状況、休日）に基づいて日付を無効にします
• ユーザーの選択に基づいて制約を更新します
• 解決策：動的なロジックを使用して renderDayCell を設定します
• 参考：イベントとメソッド + カレンダービュー

DatePicker

Syncfusion Angular DatePicker は、書式設定、検証、日付範囲、および完全なアクセシビリティ（WCAG 2.2）に対応した、個別の日付を選択するための使いやすいカレンダーインターフェースを提供します。このスキルでは、実装に不可欠なパターンと高度な機能をすべて紹介します。

コンポーネントの概要

DatePicker は、テキスト入力とポップアップカレンダーピッカーを組み合わせたものです。ユーザーは日付を直接入力することも、カレンダーから選択することもできます。主な機能は次のとおりです。

• 日付の選択：カレンダー UI またはテキスト入力から選択できます
• 複数の日付形式：カルチャーに対応した形式やカスタムパターンを使用できます
• 日付範囲の検証：最小値／最大値、厳格モードに対応します
• 入力マスク：日付入力をガイドします
• 複数のカレンダービュー：月 → 年 → 年代の順に移動できます
• アクセシビリティ：WCAG 2.2、ARIA、キーボード操作、RTL に対応します
• 国際化：CLDR データと 100 以上のカルチャーに対応します
• フォーム連携：FormValidator、リアクティブフォーム、テンプレート駆動フォームに対応します

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

はじめに

📄 参照： references/getting-started.md

• Angular 21 以降のスタンドアロンアーキテクチャでのインストールとセットアップ
• パッケージの依存関係とインポート
• DatePicker の基本的な実装
• CSS テーマのインポート
• 最小限の動作するサンプル

日付形式と解析

📄 参照： references/date-formats-and-parsing.md

• 標準的な日付形式パターン（yyyy-MM-dd、dd/MM/yyyy など）
• カルチャー固有の既定の形式
• カスタム日付形式の作成
• parseDate メソッドと formatDate メソッド
• 動的な形式の切り替え

日付範囲と検証

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

• 日付範囲の制約（min／max プロパティ）の設定
• 範囲外の日付の処理とエラー状態
• null 日付の検証と strictMode
• 無効な日付の検出
• 実際の利用場面に応じた日付制約のパターン

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

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

• 開始ビュー（月／年／年代）の設定
• 選択範囲を制限するための深度ビューの制限
• カレンダービュー間の移動
• 月と年の選択パターン
• さまざまなビュー設定のユースケース

マスキングと編集

📄 参照： references/masking-and-editing.md

• ガイド付き入力のための日付入力マスキングの有効化
• 日付形式に基づくマスクパターン
• マスク入力でのキーボード操作（上下左右の矢印キー）
• カスタムマスクプレースホルダー
• ロケールに対応したマスクプレースホルダーテキスト

スタイリングとカスタマイズ

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

• ラッパー要素と入力要素の CSS カスタマイズ
• DatePicker アイコンのスタイリングとカスタマイズ
• モバイルデバイスでの全画面モード
• プレースホルダーと読み取り専用状態のカスタマイズ
• ダークモードと Theme Studio の統合

アクセシビリティとフォーム

📄 参照： references/accessibility-and-forms.md

• WCAG 2.2 への準拠とアクセシビリティ標準
• ARIA 属性（aria-expanded、aria-disabled、aria-activedescendant）
• キーボード操作のサポート（矢印キー、Enter、Escape）
• スクリーンリーダーのサポートとセマンティックマークアップ
• 日付検証のための FormValidator 統合
• リアクティブフォームとテンプレート駆動フォームのパターン
• カスタム検証ルール

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

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

• 文化圏固有の形式設定のための CLDR データの読み込み
• 文化圏に対応した日付の解析と形式設定
• ロケール設定と L10n セットアップ
• 文化圏ごとの週の開始曜日（週データ）
• 右から左へ記述する言語（RTL）のサポート
• 多言語の例
• タイムゾーンを考慮した日付処理

テストと品質保証

📄 参照： references/testing-guide.md

• Jasmine/Karma による単体テスト：解析、バリデーター、イベント
• Cypress による E2E テスト：カレンダー操作、フォームフロー
• axe-core によるアクセシビリティテストとキーボード操作の確認

高度なパターン

📄 参照： references/advanced-patterns.md

• 連動する日付ピッカー（利用可能日の連動）
• ビジネスロジックに基づく動的な日付範囲
• ブラックアウト日／利用不可日の設定と繰り返し日付の処理
• 高度なシナリオにおけるテストと検証のパターン

クイックスタートの例

Angular 21 以降のスタンドアロンコンポーネントでの基本的な DatePicker の実装：

import { Component } from '@angular/core';
import { DatePickerModule } from '@syncfusion/ej2-angular-calendars';

@Component({
  selector: 'app-datepicker-demo',
  standalone: true,
  imports: [DatePickerModule],
  template: `
    <ejs-datepicker
      placeholder="Select date"
      [(ngModel)]="selectedDate"
      (change)="onDateChange($event)">
    </ejs-datepicker>
    <p>Selected: {{ selectedDate | date:'fullDate' }}</p>
  `
})
export class DatePickerDemoComponent {
  selectedDate: Date | null = null;

  onDateChange(event: any) {
    console.log('Date changed:', event.value);
  }
}

セットアップ手順：

1. @syncfusion/ej2-angular-calendars パッケージをインストールします
2. コンポーネントに DatePickerModule をインポートします
3. プロパティを指定して <ejs-datepicker> 要素を追加します
4. [(ngModel)]（双方向バインディング）でコンポーネント変数にバインドします

動作：

• DatePicker がカレンダーアイコンとともに表示されます
• クリックするとポップアップカレンダーが開きます
• カレンダーから日付を選択するか、直接入力します
• 選択した日付でコンポーネント変数が更新されます
• 日付を選択すると change イベントが発生します

よくあるパターン

1. 日付範囲の検証

ユーザーが特定の開始日と終了日の間の日付を選択できるように制限します：

minDate = new Date(2024, 0, 1);  // Jan 1, 2024
maxDate = new Date(2024, 11, 31); // Dec 31, 2024

<ejs-datepicker
  [min]="minDate"
  [max]="maxDate"
  placeholder="Select date in 2024">
</ejs-datepicker>

使用例： 航空券の予約、ホテルの予約、予定の調整

2. カスタム日付形式

アプリケーション固有の形式で日付を表示します：

dateFormat = 'dd/MM/yyyy';  // European format

<ejs-datepicker
  [format]="dateFormat"
  placeholder="DD/MM/YYYY">
</ejs-datepicker>

3. マスク付き日付入力

視覚的なマスクと矢印キーによる操作で、ユーザーの入力を支援します：

<ejs-datepicker
  [enableMask]="true"
  [maskPlaceholder]="'day'"
  format="dd/MM/yyyy">
</ejs-datepicker>

キーボード操作： 上下の矢印キーで各セグメントの値を増減し、左右の矢印キーでセグメント間を移動します

4. 日付範囲の選択（最小値／最大値あり）

予約シナリオで過去の日付を選択できないようにします：

minDate = new Date(); // Today
maxDate: Date;

constructor() {
  // Set max to 90 days from today
  this.maxDate = new Date();
  this.maxDate.setDate(this.maxDate.getDate() + 90);
}

5. リアクティブフォームとの統合

リアクティブフォームの検証機能を備えた DatePicker：

import { ReactiveFormsModule, FormBuilder, Validators } from '@angular/forms';

export class FormComponent {
  form = this.fb.group({
    birthDate: [null, [Validators.required]],
  });

  constructor(private fb: FormBuilder) {}
}

<form [formGroup]="form">
  <ejs-datepicker
    formControlName="birthDate"
    placeholder="Birth date">
  </ejs-datepicker>
  <span *ngIf="form.get('birthDate')?.hasError('required')">
    Birth date is required
  </span>
</form>

API リファレンス（プロパティ、メソッド、イベント）

プロパティ

プロパティ	型	説明
allowEdit	boolean	テキストボックスを編集可能にするかどうか（デフォルトは true）
calendarMode	CalendarType	カレンダーの種類（例：グレゴリオ暦、イスラム暦）
cssClass	string	カスタムスタイル用のルート CSS クラス
dayHeaderFormat	DayHeaderFormats	曜日ヘッダーの形式（Short/Narrow/Abbreviated/Wide）
depth	CalendarView	許可される最も深いカレンダービュー（Month/Year/Decade）
enableMask	boolean	マスク付きの日付入力を有効にする
enablePersistence	boolean	再読み込み後もコンポーネントの状態を保持する
enableRtl	boolean	右から左への表示を有効にする
enabled	boolean	コンポーネントを有効または無効にする（無効にするには false を設定）
firstDayOfWeek	number	週の最初の曜日（0-6）
floatLabelType	FloatLabelType	string
format	string|FormatObject	値の表示形式
fullScreenMode	boolean	モバイルでポップアップを全画面表示する
htmlAttributes	{ [key:string]: string }	ルート要素に追加する HTML 属性
inputFormats	string[]|FormatObject[]	解析時に受け入れる入力形式
keyConfigs	{ [key:string]: string }	カスタムキーアクションのマッピング
locale	string	グローバルなカルチャ設定を上書きする（例：'en-US'）
maskPlaceholder	MaskPlaceholderModel	マスク付き入力のプレースホルダーテキスト
max	Date	選択可能な最も遅い日付
min	Date	選択可能な最も早い日付
openOnFocus	boolean	入力欄にフォーカスしたときにポップアップを開く
placeholder	string	入力欄のプレースホルダーテキスト
readonly	boolean	入力欄を読み取り専用にする（入力不可）
serverTimezoneOffset	number	サーバーのタイムゾーンオフセット（分）（任意）
showClearButton	boolean	クリアアイコンを表示／非表示にする
showTodayButton	boolean	ポップアップに今日ボタンを表示／非表示にする
start	CalendarView	ポップアップを開いたときの初期ビュー
strictMode	boolean	厳密な解析／検証を適用する
value	Date	選択された日付の値
weekNumber	boolean	カレンダーに週番号を表示する
weekRule	WeekRule	年の最初の週のルール
width	number|string	コンポーネントの幅
zIndex	number	ポップアップの Z-index

メソッド

• currentView() — 現在のカレンダービュー名を返します
• destroy() — コンポーネントのインスタンスを破棄します
• focusIn() — 入力欄にフォーカスします
• focusOut() — 入力欄からフォーカスを外します
• getPersistData() — 保持されたプロパティの文字列を返します
• hide() — カレンダーのポップアップを非表示にします
• navigateTo(view: CalendarView, date?: Date) — 指定したビュー／日付に移動します
• removeDate(dates: Date|Date[]) — 値から日付を削除します
• show() — カレンダーのポップアップを表示します

イベント

• blur — 入力欄からフォーカスが外れたときに発生します
• change — 値が変更されたときに発生します（ChangedEventArgs を提供します）
• cleared — クリアボタンが使用されたときに発生します
• close — ポップアップが閉じたときに発生します（キャンセル可能）
• created — コンポーネント作成時のライフサイクルイベント
• destroyed — コンポーネント破棄時のライフサイクルイベント
• focus — 入力欄にフォーカスしたときに発生します
• navigated — カレンダーが別のビューに移動したときに発生します
• open — ポップアップが開いたときに発生します（キャンセル可能）
• renderDayCell — 各日のセルのレンダリング時に発生します（セルの無効化／カスタマイズに便利です）

よくある使用例

1. 誕生日／生年月日の選択： 最小値／最大値の検証、マスク付き入力、年をすばやく選択するための開始ビューとしての10年表示
2. 会議のスケジュール設定： 日付範囲（今日から90日後まで）、稼働日のカスタム検証、フォームとの連携
3. ホテル／航空券の予約： 最小値／最大値の日付、双方向の日付バインディング、検証付きリアクティブフォーム
4. 申請フォーム： アクセシビリティ要件に準拠した生年月日、ライセンスの有効期限、予約日
5. 国際向けアプリケーション： ロケールに応じた書式設定、RTL のサポート、カルチャ固有のカレンダー

DateRangePicker

Angular アプリケーションに Syncfusion Essential JS 2 DateRangePicker コンポーネントを実装するための包括的なガイドです。日付範囲ピッカーの作成、範囲選択の処理、イベントの管理、スタイルのカスタマイズ方法を学びます。

DateRangePicker の概要

Syncfusion Angular DateRangePicker コンポーネントは、次の機能を備えた日付選択専用ウィジェットです。

• 2 つのカレンダー表示： カレンダーを同期しながら開始日と終了日を選択できます
• プリセット範囲： 「過去 7 日間」「今月」「先月」「カスタム」などの定義済みオプション
• 範囲の検証： 最小／最大日付、無効な範囲、必須の範囲長
• 日付の書式設定： 区切り文字やパターンを指定して、日付形式をカスタマイズできます
• イベントシステム： created、destroyed、change、select、rangeSelected、open、close、renderDayCell イベント
• キーボードショートカット： Tab、矢印キー、Enter、Escape による完全なキーボードアクセシビリティ
• ローカライズ対応： ロケール固有の日付書式、曜日ヘッダー、月名
• アクセシビリティ： WCAG 2.2 に完全準拠し、ARIA 属性とスクリーンリーダーに対応
• 柔軟なカスタマイズ： CSS クラス、カスタムテンプレート、日付セルのレンダリング
• モバイル向けの最適化： タッチ操作に適したインターフェース、レスポンシブデザイン、全画面モード

パッケージ： @syncfusion/ej2-angular-calendars

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

ニーズに応じて、次のリファレンスを参照してください。

はじめに

📄 参照： references/getting-started.md

• パッケージのインストールとモジュールの設定
• CSS テーマのインポートと依存関係
• DateRangePicker の基本的な実装
• Angular でのコンポーネントの初期化
• 開始日と終了日の設定
• 実行環境とテスト環境の設定

日付範囲の選択

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

• クリックによる範囲選択
• 日付の順次選択（開始日をクリックしてから終了日をクリック）
• 日付範囲の値のバインディング（startDate、endDate プロパティ）
• 最小／最大日付の制約
• 範囲の検証とエラー処理
• 無効な日付範囲
• 選択のクリア

プリセット範囲

📄 参照： references/preset-ranges.md

• 定義済みの範囲オプション（過去 7 日間、先月など）
• カスタムプリセットの設定
• プリセットのプログラムによる適用
• 動的なプリセットの生成
• プリセット変更イベント
• プリセットと制約の組み合わせ

イベントとメソッド

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

• イベントハンドラー（change、select、rangeSelected、open、close）
• 範囲選択イベントの詳細（startDate、endDate、daySpan）
• プログラム用メソッド（show()、hide()、getSelectedRange()）
• 作成時および破棄時のライフサイクルイベント
• カスタムスタイル設定用の RenderDayCell
• メソッドの戻り値の型とパラメーター

日付の書式設定と制約

📄 参照： references/date-formatting-and-constraints.md

• 日付形式のパターンと区切り文字
• 複数形式への対応（format と inputFormats）
• 最小／最大日付の制約
• 最小／最大日数の検証
• 無効な日付の設定
• 書式エラーの処理
• ロケール固有の書式

キーボード操作とアクセシビリティ

📄 参照： references/keyboard-navigation-and-accessibility.md

• Tab と Shift+Tab による移動
• 矢印キーによる日付の移動
• Enter による範囲の選択と確定
• Escape によるピッカーの終了
• Alt キーのショートカット
• スクリーンリーダーへの対応
• ARIA ラベルとロール
• WCAG 2.2 AA への準拠
• フォーカス管理

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

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

• CSS クラスのカスタマイズ（.e-daterangepicker、.e-calendar、.e-range-header）
• テーマの選択（Material、Bootstrap、Tailwind、Fabric）
• ダークモードの実装
• renderDayCell による日付セルのカスタムスタイル設定
• 無効な日付のスタイル設定
• プリセットボタンのスタイル設定
• ホバー状態とフォーカス状態
• レスポンシブレイアウトのカスタマイズ

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

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

• 日付の書式設定に使用するロケールプロパティ
• アラビア語、ヘブライ語の RTL（右から左）表示に対応
• 曜日ヘッダーの書式（Short、Narrow、Abbreviated、Wide）
• 月名と曜日名のローカライズ
• カスタムロケールへの対応
• タイムゾーンの処理
• 日付書式のローカライズ

API リファレンス

📄 参照: references/api-reference.md

• 説明付きの全プロパティリファレンス
• 戻り値の型を含むすべてのメソッドシグネチャ
• イベント引数の型と構造
• 型インターフェイス（RangeEventArgs、NavigatingEventArgs など）
• CSS クラスとスタイル設定用フック
• ブラウザーのサポート状況

クイックスタートの例

// app.component.ts
import { Component } from '@angular/core';
import { RangeEventArgs } from '@syncfusion/ej2-calendars';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Date range properties
  startDate: Date = new Date(2026, 2, 1);  // March 1, 2026
  endDate: Date = new Date(2026, 2, 31);   // March 31, 2026
  
  // Constraints
  minDate: Date = new Date(2020, 0, 1);
  maxDate: Date = new Date(2030, 11, 31);
  
  // Range display
  selectedRange: string = '';
  
  // Event handler
  onRangeChange(args: RangeEventArgs): void {
    console.log('Start Date:', args.startDate);
    console.log('End Date:', args.endDate);
    console.log('Days in range:', args.daySpan);
    this.updateRangeDisplay();
  }
  
  updateRangeDisplay(): void {
    if (this.startDate && this.endDate) {
      const start = this.startDate.toLocaleDateString();
      const end = this.endDate.toLocaleDateString();
      this.selectedRange = `${start} - ${end}`;
    }
  }
}

<div style="padding: 20px; font-family: Arial, sans-serif;">
  <h2>DateRangePicker Example</h2>
  
  <div style="margin-bottom: 20px;">
    <label for="dateRange">Select Date Range:</label>
    <ejs-daterangepicker 
      id="dateRange"
      placeholder="Select a date range"
      [startDate]="startDate"
      [endDate]="endDate"
      [min]="minDate"
      [max]="maxDate"
      (change)="onRangeChange($event)">
    </ejs-daterangepicker>
  </div>
  
  <div *ngIf="selectedRange" style="padding: 10px; background-color: #f0f0f0;">
    <p><strong>Selected Range:</strong> {{ selectedRange }}</p>
  </div>
</div>

/* app.component.css */
@import '../node_modules/@syncfusion/ej2-base/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-inputs/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-buttons/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-popups/styles/material3.css';
@import '../node_modules/@syncfusion/ej2-calendars/styles/material3.css';

:host ::ng-deep .e-daterangepicker {
  margin: 10px 0;
  width: 100%;
}

:host ::ng-deep .e-range-header {
  background-color: #3f51b5;
  color: white;
}

よく使われるパターン

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

よく使われる日付範囲をすばやく選択するためのボタンです。

export class AppComponent {
  presets: any[] = [
    { label: 'Today', start: new Date(), end: new Date() },
    { label: 'Last 7 Days', start: this.getDateDaysAgo(7), end: new Date() },
    { label: 'Last 30 Days', start: this.getDateDaysAgo(30), end: new Date() },
    { label: 'This Month', start: this.getFirstDayOfMonth(), end: new Date() },
    { label: 'Last Month', start: this.getFirstDayOfLastMonth(), end: this.getLastDayOfLastMonth() }
  ];
  
  startDate: Date = new Date();
  endDate: Date = new Date();
  
  selectPreset(preset: any): void {
    this.startDate = preset.start;
    this.endDate = preset.end;
  }
  
  private getDateDaysAgo(days: number): Date {
    const date = new Date();
    date.setDate(date.getDate() - days);
    return date;
  }
  
  private getFirstDayOfMonth(): Date {
    return new Date(new Date().getFullYear(), new Date().getMonth(), 1);
  }
  
  private getFirstDayOfLastMonth(): Date {
    const date = new Date();
    return new Date(date.getFullYear(), date.getMonth() - 1, 1);
  }
  
  private getLastDayOfLastMonth(): Date {
    const date = new Date();
    return new Date(date.getFullYear(), date.getMonth(), 0);
  }
}

<div>
  <div style="margin-bottom: 10px;">
    <button *ngFor="let preset of presets" 
            (click)="selectPreset(preset)"
            style="margin-right: 5px; padding: 8px 12px;">
      {{ preset.label }}
    </button>
  </div>
  
  <ejs-daterangepicker 
    [startDate]="startDate"
    [endDate]="endDate">
  </ejs-daterangepicker>
</div>

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

カスタム制約を使用して日付範囲を検証します。

export class AppComponent {
  @ViewChild('daterangepicker') drp!: DateRangePickerComponent;
  
  startDate: Date = new Date();
  endDate: Date = new Date();
  rangeError: string = '';
  
  minDate: Date = new Date(2020, 0, 1);
  maxDate: Date = new Date(2030, 11, 31);
  minDays: number = 1;      // At least 1 day
  maxDays: number = 90;     // At most 90 days
  
  onRangeChange(args: RangeEventArgs): void {
    this.rangeError = '';
    
    // Validate date range
    if (args.daySpan < this.minDays) {
      this.rangeError = `Range must be at least ${this.minDays} day(s)`;
      return;
    }
    
    if (args.daySpan > this.maxDays) {
      this.rangeError = `Range cannot exceed ${this.maxDays} days`;
      return;
    }
    
    this.startDate = args.startDate;
    this.endDate = args.endDate;
  }
  
  isRangeValid(): boolean {
    return this.rangeError === '';
  }
}

パターン 3：リアクティブフォームとの統合

DateRangePicker をリアクティブフォームに統合します。

export class AppComponent implements OnInit {
  reportForm: FormGroup;
  
  constructor(private fb: FormBuilder) {
    this.reportForm = this.fb.group({
      reportName: ['', Validators.required],
      startDate: [new Date(2026, 0, 1), Validators.required],
      endDate: [new Date(), Validators.required]
    });
  }
  
  ngOnInit(): void {
    this.reportForm.get('startDate')?.valueChanges.subscribe(date => {
      console.log('Start date changed:', date);
      this.validateDateRange();
    });
    
    this.reportForm.get('endDate')?.valueChanges.subscribe(date => {
      console.log('End date changed:', date);
      this.validateDateRange();
    });
  }
  
  validateDateRange(): void {
    const start = this.reportForm.get('startDate')?.value;
    const end = this.reportForm.get('endDate')?.value;
    
    if (start && end && start > end) {
      this.reportForm.get('endDate')?.setErrors({ 'invalidRange': true });
    } else {
      this.reportForm.get('endDate')?.setErrors(null);
    }
  }
  
  submitForm(): void {
    if (this.reportForm.valid) {
      console.log('Form values:', this.reportForm.value);
    }
  }
}

<form [formGroup]="reportForm" (ngSubmit)="submitForm()">
  <div>
    <label>Report Name:</label>
    <ejs-textbox 
      formControlName="reportName"
      placeholder="Enter report name">
    </ejs-textbox>
  </div>
  
  <div>
    <label>Report Period:</label>
    <ejs-daterangepicker 
      [formControl]="reportForm.get('startDate')"
      [endDate]="reportForm.get('endDate')?.value">
    </ejs-daterangepicker>
  </div>
  
  <button type="submit" [disabled]="!reportForm.valid">Generate Report</button>
</form>

パターン 4：動的な範囲制約

ビジネスロジックに応じて範囲制約を更新します。

export class AppComponent {
  startDate: Date = new Date();
  endDate: Date = new Date();
  
  // Dynamic constraints
  minDate: Date = new Date();
  maxDate: Date = new Date();
  
  reportType: string = 'daily';
  
  onReportTypeChange(type: string): void {
    this.reportType = type;
    this.updateConstraints();
  }
  
  private updateConstraints(): void {
    const today = new Date();
    
    switch (this.reportType) {
      case 'daily':
        // Last 7 days only
        this.minDate = new Date(today.getTime() - 7 * 24 * 60 * 60 * 1000);
        this.maxDate = today;
        break;
      
      case 'monthly':
        // Last 12 months
        this.minDate = new Date(today.getFullYear() - 1, today.getMonth(), 1);
        this.maxDate = today;
        break;
      
      case 'yearly':
        // Last 5 years
        this.minDate = new Date(today.getFullYear() - 5, 0, 1);
        this.maxDate = today;
        break;
    }
  }
}

パターン 5：無効化する日付範囲

特定の日付範囲（祝日や選択不可の日付）を無効化します。

export class AppComponent {
  disabledRanges: Array<{start: Date, end: Date}> = [
    { start: new Date(2026, 11, 20), end: new Date(2026, 11, 31) }, // Christmas season
    { start: new Date(2026, 0, 1), end: new Date(2026, 0, 3) }      // New Year
  ];
  
  startDate: Date = new Date();
  endDate: Date = new Date();
  
  onRenderDayCell(args: RenderDayCellEventArgs): void {
    // Disable dates in disabled ranges
    for (const range of this.disabledRanges) {
      if (args.date >= range.start && args.date <= range.end) {
        args.isDisabled = true;
        break;
      }
    }
  }
}

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

プロパティ	型	説明	例
startDate	Date	範囲の開始日	[startDate]="start"
endDate	Date	範囲の終了日	[endDate]="end"
value	Date[] or DateRange	選択した日付範囲（配列またはオブジェクト）	[(ngModel)]="dateRange"
min	Date	選択可能な最小日付	[min]="minDate"
max	Date	選択可能な最大日付	[max]="maxDate"
minDays	number	範囲の最小日数	[minDays]="1"
maxDays	number	範囲の最大日数	[maxDays]="90"
format	string	日付の表示形式	format="dd/MM/yyyy"
separator	string	範囲の区切り文字	separator=" to "
placeholder	string	プレースホルダーテキスト	placeholder="Select date range"
presets	PresetsModel[]	事前定義された範囲のオプション	[presets]="presets"
strictMode	boolean	厳密な日付検証	[strictMode]="true"
readonly	boolean	読み取り専用の入力フィールド	[readonly]="false"
enabled	boolean	コンポーネントの有効化／無効化	[enabled]="true"
locale	string	文化／言語コード	locale="en-US"
enableRtl	boolean	RTL レイアウトを有効化	[enableRtl]="false"
cssClass	string	カスタム CSS クラス	cssClass="custom-drp"
width	number | string	コンポーネントの幅	width="300px"
allowEdit	boolean	テキストの手動入力を許可	[allowEdit]="true"
openOnFocus	boolean	入力欄へのフォーカス時にピッカーを開く	[openOnFocus]="true"
showClearButton	boolean	クリアボタンを表示	[showClearButton]="true"
depth	CalendarView	カレンダービューの深さ	depth="Month"

一般的な使用例

使用例 1：レポートの日付範囲の選択

• ユーザーがレポート生成の日付範囲を選択します
• 最小／最大の日付制約を適用します
• プリセット範囲（過去 7 日間、先月など）をサポートします
• 解決策：開始日／終了日と、プリセットおよび最小／最大の制約を組み合わせます
• 参照：プリセット範囲 + 日付の書式設定と制約

使用例 2：予約システムの日付範囲

• 予約のチェックイン日とチェックアウト日を選択します
• 過去の日付と予約不可の日付を無効にします
• 範囲内の日数を表示します
• 解決策：最小日付制約、無効な範囲を指定する renderDayCell、日数を計算する daySpan を使用します
• 参照：日付範囲の選択 + イベントとメソッド

使用例 3：分析用の日付フィルター

• 分析ダッシュボードの日付範囲を選択します
• すばやく選択できる複数のプリセットオプションを用意します
• レスポンシブでモバイルに使いやすいインターフェイスを提供します
• 解決策：レスポンシブなスタイル設定とタッチ操作の最適化を組み合わせて、プリセットを使用します
• 参照：プリセット範囲 + スタイル設定とカスタマイズ

使用例 4：アクセシブルなフォームフィールド

• DateRangePicker を、キーボードで完全に操作できるフォームに組み込みます
• スクリーンリーダーに対応し、WCAG 2.2 に準拠します
• 解決策：リアクティブフォームと組み合わせ、適切な ARIA ラベルを使用します
• 参照：キーボード操作とアクセシビリティ

使用例 5：国際化に対応した日付ピッカー

• 複数の言語と日付形式をサポートします
• アラビア語やヘブライ語では RTL 表示にします
• ロケール固有の書式設定に対応します
• 解決策：locale プロパティと書式設定のカスタマイズを使用します
• 参照：グローバリゼーションとローカリゼーション

DatetimePicker

Angular アプリケーションで Syncfusion Essential JS 2 DatetimePicker コンポーネントを実装するための包括的なガイドです。日付と時刻を選択するインターフェイスの作成、カレンダーとタイムピッカーの管理、イベントの処理、スタイルのカスタマイズについて説明します。

DatetimePicker の概要

Syncfusion Angular DatetimePicker コンポーネントは、次の機能を備えた日付と時刻の統合選択ウィジェットです。

• 日付と時刻の統合選択： 日付用のカレンダーポップアップと時刻選択用のタイムピッカードロップダウン
• 柔軟な書式設定： カスタムの日付形式と時刻形式、およびロケールに応じた書式設定
• カレンダービュー： 月（既定）、年、10 年単位のビューとスムーズな移動
• 時刻間隔： 時刻選択用の設定可能な間隔（15、30、60 分など）
• 範囲の制約： 厳密な検証に対応した最小／最大の日付と時刻
• 包括的なイベントシステム： change、focus、blur、open、close、created、destroyed、navigated、renderDayCell イベント
• マスク入力のサポート： ユーザーの入力を補助する任意のマスク入力形式
• 状態保持と RTL： 再読み込み後も状態を保持し、右から左へ記述する言語をサポート
• 高度な機能： 厳密モード検証、フローティングラベル、キーボードのカスタマイズ、タイムゾーンのサポート
• アクセシビリティ： WCAG 2.2 への完全準拠、キーボード操作、WAI-ARIA のサポート
• テーマのサポート： Material、Bootstrap、Tailwind、Fabric と、ライト／ダークの各バリエーション
• モバイル向け最適化： モバイルデバイスでの全画面表示と、タッチ操作に適したインターフェイス

パッケージ： @syncfusion/ej2-angular-datetimepickers

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

ニーズに応じて、以下のリファレンスを参照してください。

はじめに

📄 参照： references/getting-started.md

• npm と ng add によるパッケージのインストール
• NgModule とスタンドアロンコンポーネントのセットアップ
• CSS テーマのインポートと依存関係
• DatetimePicker の基本的な実装
• コンポーネントの初期化とアプリケーションの実行
• 開発サーバーのセットアップ

基本的な実装

📄 参照： references/basic-implementation.md

• ngModel を使用したシンプルな日時ピッカー
• 双方向データバインディングのパターン
• 読み取り専用状態と無効状態
• 基本的な検証と制約
• イベント処理の基本
• ViewChild によるコンポーネントへのアクセス

日付と時刻の設定

📄 参照： references/date-time-configuration.md

• 日付形式のカスタマイズ（format プロパティ）
• 時刻形式の設定（timeFormat プロパティ）
• ISO 日付文字列の処理
• 日付範囲の制約（min/max dates）
• 時刻範囲の制約（minTime/maxTime）
• 複数の入力形式の解析（inputFormats）

カレンダーと時刻のビュー

📄 参照： references/calendar-and-time-views.md

• カレンダーの表示モード（月、年、10年）
• ビューを制御する start プロパティと depth プロパティ
• 時刻ピッカーのポップアップ設定
• 時刻の間隔と粒度
• 時刻のスクロール位置を指定する ScrollTo
• 今日ボタンとクリアボタンの動作

イベントとコールバック

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

• ChangedEventArgs を使用する Change イベント
• フォーカス／ブラーイベントの処理
• ポップアップの開閉イベント
• 作成／破棄のライフサイクルイベント
• カレンダーの移動に使用する Navigate イベント
• 日付のスタイルをカスタマイズする RenderDayCell
• クリアボタン使用時の Cleared イベント

メソッドと命令型アクセス

📄 参照： references/methods-and-imperative-access.md

• ViewChild アクセスとコンポーネント参照
• アクティブなカレンダービューを取得する currentView()
• プログラムで移動する navigateTo()
• フォーカスを管理する focusIn/focusOut
• クリーンアップとリソース解放に使用する destroy()
• 状態を永続化する getPersistData()

高度な機能

📄 参照： references/advanced-features.md

• マスクのプレースホルダーを使用するマスク入力モード
• ページの再読み込み後も状態を保持
• RTL（右から左）言語のサポート
• フローティングラベルの種類と動作
• 厳密モードでの検証とエラー状態
• キーボードショートカットとキー設定
• タイムゾーンオフセットの処理
• モバイルデバイス向けの全画面モード
• クリアボタンの表示と動作

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

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

• CSS クラスのカスタマイズ（cssClass プロパティ）
• テーマの選択と切り替え
• ダークモードの実装
• コンポーネントの幅と z-index の設定
• HTML 属性の追加（htmlAttributes）
• カレンダーモードの選択（グレゴリオ暦とイスラム暦）
• 曜日ヘッダーの形式オプション
• 無効な日付とスタイル状態

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

📄 参照： references/accessibility-and-globalization.md

• WCAG 2.2 および Section 508 の準拠基準
• WAI-ARIA 属性とロール
• キーボード操作（矢印、Enter、スペース、Escape）
• スクリーンリーダーとの互換性と読み上げ
• ローカライズと locale プロパティの使用
• 曜日ヘッダーの形式のバリエーション
• 週の開始曜日のカスタマイズ
• 週番号と週の規則
• RTL のテキスト方向のサポート

API リファレンス

📄 参照： references/api-reference.md

• 型とデフォルト値を含むすべてのプロパティのリファレンス
• パラメーターと戻り値の型を含むすべてのメソッドシグネチャ
• イベント引数の型を含むすべてのイベント
• プロパティの説明とユースケース
• メソッドの例と一般的なパターン
• 型インターフェイスと列挙型
• キーボードショートカットのキー設定
• プロパティごとの包括的なガイド

クイックスタートの例

// app.component.ts
import { Component } from '@angular/core';
import { ChangedEventArgs } from '@syncfusion/ej2-datetimepickers';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Simple datetime value
  dateTimeValue: Date = new Date();
  
  // Configuration
  minDate: Date = new Date(2020, 0, 1);
  maxDate: Date = new Date(2030, 11, 31);
  dateFormat: string = 'dd/MM/yyyy hh:mm a';
  timeFormat: string = 'hh:mm a';
  
  // Event handler
  onDateTimeChange(args: ChangedEventArgs): void {
    console.log('Selected DateTime:', args.value);
    console.log('Event Type:', args.type);
  }
  
  onPopupOpen(): void {
    console.log('Popup opened');
  }
  
  onPopupClose(): void {
    console.log('Popup closed');
  }
}

<div style="padding: 20px;">
  <h2>Select Date & Time</h2>
  
  <ejs-datetimepicker
    id="datetimepicker"
    [value]="dateTimeValue"
    [format]="dateFormat"
    [timeFormat]="timeFormat"
    [min]="minDate"
    [max]="maxDate"
    placeholder="Select date and time"
    (change)="onDateTimeChange($event)"
    (open)="onPopupOpen()"
    (close)="onPopupClose()">
  </ejs-datetimepicker>
  
  <p *ngIf="dateTimeValue">
    Selected: {{ dateTimeValue | date:'medium' }}
  </p>
</div>

よく使われるパターン

パターン 1：日時範囲の選択

予約やイベントで使用する開始日時と終了日時を選択します。

export class AppComponent {
  startDateTime: Date = new Date();
  endDateTime: Date = new Date(Date.now() + 3600000); // +1 hour
  
  onStartChange(args: ChangedEventArgs): void {
    // Ensure end is after start
    if (this.endDateTime <= args.value) {
      this.endDateTime = new Date((args.value as Date).getTime() + 3600000);
    }
  }
}

パターン 2：営業時間のみ

時間の選択を営業時間（午前 9 時～午後 5 時）に制限します。

export class AppComponent {
  minTime: Date = new Date(2026, 2, 24, 9, 0);  // 9:00 AM
  maxTime: Date = new Date(2026, 2, 24, 17, 0); // 5:00 PM
  
  datetimeValue: Date = new Date(2026, 2, 24, 10, 0);
}

<ejs-datetimepicker
  [value]="datetimeValue"
  [minTime]="minTime"
  [maxTime]="maxTime"
  timeFormat="hh:mm a">
</ejs-datetimepicker>

パターン 3：入力をガイドするマスク入力

マスク入力を使用して、日時形式に沿った入力をガイドします。

export class AppComponent {
  datetimeValue: Date;
  maskPlaceholder = {
    day: 'dd',
    month: 'mm',
    year: 'yyyy',
    hour: 'hh',
    minute: 'mm',
    second: 'ss'
  };
}

<ejs-datetimepicker
  [value]="datetimeValue"
  [enableMask]="true"
  [maskPlaceholder]="maskPlaceholder"
  format="dd/MM/yyyy hh:mm:ss">
</ejs-datetimepicker>

パターン 4：リアクティブフォームとの統合

日時ピッカーを Angular リアクティブフォームと統合します。

import { FormBuilder, FormGroup, Validators } from '@angular/forms';

export class AppComponent {
  appointmentForm: FormGroup;
  
  constructor(private fb: FormBuilder) {
    this.appointmentForm = this.fb.group({
      appointmentDateTime: [
        new Date(),
        [Validators.required]
      ]
    });
  }
  
  submitForm(): void {
    if (this.appointmentForm.valid) {
      console.log(this.appointmentForm.value);
    }
  }
}

<form [formGroup]="appointmentForm">
  <ejs-datetimepicker
    formControlName="appointmentDateTime"
    format="dd/MM/yyyy hh:mm a">
  </ejs-datetimepicker>
  
  <button (click)="submitForm()" [disabled]="!appointmentForm.valid">
    Submit
  </button>
</form>

パターン 5：日付の無効化

週末と特定の日付を無効にします。

export class AppComponent {
  datetimeValue: Date;
  
  onRenderDayCell(args: RenderDayCellEventArgs): void {
    // Disable weekends (0 = Sunday, 6 = Saturday)
    if ((args.date as Date).getDay() === 0 || (args.date as Date).getDay() === 6) {
      args.isDisabled = true;
    }
    
    // Disable specific dates
    const disabledDates = [5, 15, 25]; // 5th, 15th, 25th of each month
    if (disabledDates.includes((args.date as Date).getDate())) {
      args.isDisabled = true;
    }
  }
}

<ejs-datetimepicker
  [value]="datetimeValue"
  (renderDayCell)="onRenderDayCell($event)">
</ejs-datetimepicker>

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

プロパティ	型	目的
value	Date	双方向バインディング用の選択された日時の値
format	string	日付の表示形式（例：'dd/MM/yyyy hh:mm a'）
timeFormat	string	ポップアップでの時刻の表示形式（例：'hh:mm a'）
min	Date	選択可能な最小日付
max	Date	選択可能な最大日付
minTime	Date	選択可能な最小時刻
maxTime	Date	選択可能な最大時刻
step	number	時間間隔（分）（15、30、60）
enabled	boolean	コンポーネントの有効化／無効化
readonly	boolean	入力を読み取り専用にします（ポップアップからのみ選択可能）
placeholder	string	入力欄のプレースホルダーテキスト
enableMask	boolean	マスク入力モードを有効にします
strictMode	boolean	有効な値のみを許可します
enableRtl	boolean	右から左に記述する言語をサポートします
enablePersistence	boolean	ページの再読み込み後も値を保持します
start	CalendarView	初期カレンダービュー（Month／Year／Decade）
depth	CalendarView	カレンダービューの最大レベル
locale	string	書式設定に使用するロケール（例：'en-US'、'de-DE'）

一般的なユースケース

予約システム

• 営業時間の制約付きで日付範囲を選択します
• 最小／最大時刻に基づいて利用可能な時間枠を表示します
• 必須バリデーターを使用してフォームの検証を処理します
• 選択した日時の確認を表示します

イベントのスケジュール設定

• イベントの開始日時と終了日時を選択します
• renderDayCell を使用して週末の日付を無効にします
• 一般的な所要時間（30、60 分）には間隔を使用します
• API 送信用に出力を書式設定します

シフト管理

• シフトの開始時刻と終了時刻を選択します
• シフト時刻の制約（最小／最大時刻）を適用します
• 日付の切り替わり（深夜をまたぐシフト）を処理します
• 複数のタイムゾーンオフセットをサポートします

請求とインボイス

• 請求書の日付と時刻を選択します
• 過去の日付のみに制限します
• ユーザーのロケール形式で表示します
• ISO 形式でエクスポートします

次のステップ

1. 「はじめに」から始める → コンポーネントをインストールして設定します
2. 基本的な実装を作成する → シンプルな日時ピッカーを作成します
3. イベント処理を追加する → ユーザーの操作に応答します
4. 高度な機能を実装する → マスク入力、永続化、RTL を追加します
5. 外観をカスタマイズする → テーマとカスタムスタイルを適用します
6. アクセシビリティを確保する → キーボードとスクリーンリーダーをサポートします
7. API を参照する → 必要に応じて API の完全なドキュメントを確認します

TimePicker

Angular アプリケーションで Syncfusion Essential JS 2 TimePicker コンポーネントを実装するための包括的なガイドです。時刻選択インターフェイスの作成、時刻入力の管理、イベント処理、スタイルのカスタマイズについて説明します。

タイムピッカーの概要

Syncfusion Angular TimePicker コンポーネントは、専用の時刻選択ウィジェットで、次の機能を備えています。

• 時刻の選択： 選択可能な、間隔を設定できる時刻のポップアップリスト
• 柔軟な書式設定： カスタム時刻書式、スケルトンオプション、ロケールに応じた書式設定
• 時刻の間隔： 時刻選択のステップ間隔（15、30、60 分など）を設定可能
• 範囲の制約： 厳密な検証と境界値の制限を備えた最小／最大時刻
• 包括的なイベントシステム： change、focus、blur、open、close、created、destroyed、cleared、itemRender イベント
• マスク入力のサポート： ユーザーの入力を補助する、オプションのマスク入力書式
• 状態の保持と RTL： 再読み込み後も状態を保持し、右から左に記述する言語をサポート
• 高度な機能： 厳密モードの検証、フローティングラベル、キーボードのカスタマイズ、タイムゾーンサポート
• アクセシビリティ： WCAG 2.2 に完全準拠し、キーボードナビゲーションと WAI-ARIA をサポート
• テーマのサポート： Material、Bootstrap、Tailwind、Fabric と、ライト／ダークの各バリエーション
• モバイル向けに最適化： モバイルデバイスでの全画面モードと、タッチ操作に適したインターフェース

パッケージ： @syncfusion/ej2-angular-calendars

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

ニーズに応じて、次のリファレンスをお読みください。

はじめに

📄 参照： references/getting-started.md

• npm および ng add によるパッケージのインストール
• NgModule と Standalone コンポーネントのセットアップ
• CSS テーマのインポートと依存関係
• タイムピッカーの基本的な実装
• コンポーネントの初期化とアプリケーションの実行
• 開発サーバーのセットアップ

基本的な実装

📄 参照： references/basic-implementation.md

• ngModel を使用したシンプルなタイムピッカー
• 双方向データバインディングのパターン
• 読み取り専用状態と無効状態
• 基本的な検証と制約
• イベント処理の基礎
• ViewChild によるコンポーネントへのアクセス

時刻の設定

📄 参照： references/time-configuration.md

• 時刻書式のカスタマイズ（format プロパティ）
• TimeFormatObject とスケルトンオプション
• ステップ間隔と時刻の粒度
• 最小／最大時刻の制約
• 時刻のスクロール位置を指定する ScrollTo
• ポップアップリストの設定

イベントとコールバック

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

• ChangeEventArgs を使用した Change イベント
• Focus／blur イベントの処理
• ポップアップの open／close イベント
• 作成／破棄時のライフサイクルイベント
• クリアボタンの使用時に発生する Cleared イベント
• 時刻書式をカスタマイズする ItemRender

メソッドと命令型アクセス

📄 参照： references/methods-and-imperative-access.md

• ViewChild によるアクセスとコンポーネント参照
• show() で時刻のポップアップを開く
• hide() で時刻のポップアップを閉じる
• focusIn／focusOut によるフォーカス管理
• 状態を保持する getPersistData()

高度な機能

📄 参照： references/advanced-features.md

• マスクプレースホルダーを使用したマスク入力モード
• ページの再読み込み後も状態を保持
• RTL（右から左に記述する言語）のサポート
• フローティングラベルの種類と動作
• 厳密モードの検証とエラー状態
• キーボードショートカットとキー設定
• タイムゾーンオフセットの処理
• モバイルデバイス向けの全画面モード
• クリアボタンの表示と動作
• ポップアップを開くトリガーとしての OpenOnFocus

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

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

• CSS クラスのカスタマイズ（cssClass プロパティ）
• テーマの選択と切り替え
• ダークモードの実装
• コンポーネントの幅と z-index の設定
• HTML 属性の挿入（htmlAttributes）
• プレースホルダーと有効状態のスタイル設定
• 無効な日付のスタイルと外観

アクセシビリティとグローバリゼーション

📄 参照： references/accessibility-and-globalization.md

• WCAG 2.2 および Section 508 の準拠基準
• WAI-ARIA 属性とロール
• キーボードナビゲーション（矢印、Enter、スペース、Escape）
• スクリーンリーダーとの互換性と通知
• ローカライズと locale プロパティの使用
• 時刻形式のバリエーション
• RTL テキスト方向のサポート

API リファレンス

📄 参照： references/api-reference.md

• 型とデフォルト値を含むプロパティの完全なリファレンス
• パラメーターと戻り値の型を含むすべてのメソッドシグネチャ
• イベント引数の型を含むすべてのイベント
• プロパティの説明とユースケース
• メソッドの例と一般的なパターン
• 型インターフェイスと列挙型
• キーボードショートカットの主要な設定
• プロパティごとの包括的なガイド

クイックスタートの例

// app.component.ts
import { Component } from '@angular/core';
import { ChangeEventArgs } from '@syncfusion/ej2-calendars';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  // Simple time value
  timeValue: Date = new Date();
  
  // Configuration
  minTime: Date = new Date(2026, 2, 24, 8, 0);   // 8:00 AM
  maxTime: Date = new Date(2026, 2, 24, 20, 0);  // 8:00 PM
  format: string = 'hh:mm a';
  step: number = 30;  // 30-minute intervals
  
  // Event handler
  onTimeChange(args: ChangeEventArgs): void {
    console.log('Selected Time:', args.value);
    console.log('Selected Text:', args.text);
    console.log('Is User Interaction:', args.isInteracted);
  }
  
  onPopupOpen(): void {
    console.log('Time popup opened');
  }
  
  onPopupClose(): void {
    console.log('Time popup closed');
  }
}

<div style="padding: 20px;">
  <h2>Select a Time</h2>
  
  <ejs-timepicker
    id="timepicker"
    [value]="timeValue"
    [format]="format"
    [min]="minTime"
    [max]="maxTime"
    [step]="step"
    placeholder="Select time"
    (change)="onTimeChange($event)"
    (open)="onPopupOpen()"
    (close)="onPopupClose()">
  </ejs-timepicker>
  
  <p *ngIf="timeValue">
    Selected Time: {{ timeValue | date:'shortTime' }}
  </p>
</div>

一般的なパターン

パターン 1：営業時間内の時刻選択

営業時間（午前 9 時〜午後 6 時）の範囲内で時刻を選択します。

export class AppComponent {
  minTime: Date = new Date(2026, 2, 24, 9, 0);   // 9:00 AM
  maxTime: Date = new Date(2026, 2, 24, 18, 0);  // 6:00 PM
  timeValue: Date = new Date(2026, 2, 24, 10, 0);
  format: string = 'hh:mm a';
  step: number = 15;  // 15-minute intervals
}

<ejs-timepicker
  [value]="timeValue"
  [min]="minTime"
  [max]="maxTime"
  [step]="step"
  [format]="format"
  placeholder="Select appointment time">
</ejs-timepicker>

パターン 2：24 時間形式

時刻を 24 時間形式で表示します。

export class AppComponent {
  timeValue: Date = new Date();
  format: string = 'HH:mm';  // 24-hour format
  step: number = 30;
}

<ejs-timepicker
  [value]="timeValue"
  [format]="format"
  [step]="step"
  placeholder="Select time (24-hour)">
</ejs-timepicker>

パターン 3：入力をガイドするマスク入力

マスク入力を使用して、ユーザーの時刻入力をガイドします。

export class AppComponent {
  timeValue: Date;
  enableMask: boolean = true;
  maskPlaceholder = {
    hour: 'hh',
    minute: 'mm',
    second: 'ss'
  };
  format: string = 'hh:mm:ss a';
}

<ejs-timepicker
  [value]="timeValue"
  [enableMask]="enableMask"
  [maskPlaceholder]="maskPlaceholder"
  format="hh:mm:ss a">
</ejs-timepicker>

パターン 4：リアクティブフォームとの統合

タイムピッカーを Angular のリアクティブフォームと統合します。

import { FormBuilder, FormGroup, Validators } from '@angular/forms';

export class AppComponent {
  appointmentForm: FormGroup;
  
  constructor(private fb: FormBuilder) {
    this.appointmentForm = this.fb.group({
      appointmentTime: [
        new Date(),
        [Validators.required]
      ]
    });
  }
  
  submitForm(): void {
    if (this.appointmentForm.valid) {
      console.log(this.appointmentForm.value);
    }
  }
}

<form [formGroup]="appointmentForm">
  <ejs-timepicker
    formControlName="appointmentTime"
    format="hh:mm a"
    placeholder="Select time">
  </ejs-timepicker>
  
  <button (click)="submitForm()" [disabled]="!appointmentForm.valid">
    Submit
  </button>
</form>

パターン 5：時間範囲の選択

所要時間の開始時刻と終了時刻を選択します。

export class AppComponent {
  startTime: Date = new Date();
  endTime: Date = new Date(Date.now() + 3600000);  // +1 hour
  
  onStartTimeChange(args: ChangeEventArgs): void {
    // Ensure end time is after start time
    if (args.value && this.endTime <= args.value) {
      this.endTime = new Date(args.value.getTime() + 3600000);  // +1 hour
    }
  }
}

<div>
  <label>Start Time:</label>
  <ejs-timepicker
    [value]="startTime"
    format="hh:mm a"
    (change)="onStartTimeChange($event)">
  </ejs-timepicker>
  
  <label>End Time:</label>
  <ejs-timepicker
    [value]="endTime"
    [min]="startTime"
    format="hh:mm a">
  </ejs-timepicker>
</div>

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

プロパティ	型	目的
value	Date	双方向バインディングに使用する選択時刻の値
format	string	時刻の表示形式（例：'hh:mm a'）
min	Date	選択可能な最小時刻
max	Date	選択可能な最大時刻
step	number	時間間隔（分）（15、30、60）
enabled	boolean	コンポーネントを有効化／無効化
readonly	boolean	入力を読み取り専用にする（ポップアップからのみ選択可能）
placeholder	string	入力欄のプレースホルダーテキスト
enableMask	boolean	マスク入力モードを有効化
strictMode	boolean	有効な値のみを適用
enableRtl	boolean	右から左に記述する言語をサポート
enablePersistence	boolean	ページの再読み込み後も値を保持
scrollTo	Date	時刻リストのデフォルトのスクロール位置
locale	string	書式設定に使用するロケール（例：'en-US'、'de-DE'）
cssClass	string	スタイル設定用のカスタム CSS クラス
width	string	コンポーネントの幅
zIndex	number	ポップアップの Z インデックス
showClearButton	boolean	クリアアイコンを表示／非表示
openOnFocus	boolean	入力欄にフォーカスしたときにポップアップを開く
floatLabelType	string	フローティングラベルの動作（Never／Always／Auto）

一般的なユースケース

予約システム

• リストから利用可能な時間枠を選択
• 最小時刻と最大時刻を使って営業時間内に制限
• 15 分または 30 分の間隔を使用
• 必須バリデーターでフォーム検証を処理
• 選択した時刻を確認表示

シフト管理

• シフトの開始時刻と終了時刻を選択
• シフトの時間制約を適用
• 複数のタイムゾーンオフセットをサポート
• 深夜をまたぐシフトの切り替わりを処理
• 時刻を ISO 形式でエクスポート

会議のスケジュール設定

• 営業時間の制約内で会議の時刻を選択
• 標準的な所要時間に合わせて 30 分間隔を使用
• ユーザーのロケール形式で時刻を表示
• 検証によって二重予約を防止
• 空き状況を確認するため、カレンダーコンポーネントと同期

時間記録

• 出勤時刻と退勤時刻を記録
• 営業時間内に制限
• すばやく入力できるようマスク入力を使用
• 監査証跡用に時刻を保持
• 給与計算との連携用に時刻をエクスポート

イベント登録

• イベント参加の時間枠を選択
• 利用可能な時間範囲を表示
• 修正時にクリアボタンを使用
• 複数の時刻形式をサポート
• 支援技術向けのアクセシビリティ

次のステップ

1. 「はじめに」から開始 → コンポーネントをインストールして設定します
2. 基本的な実装を構築 → シンプルな時刻ピッカーを作成します
3. イベント処理を追加 → ユーザーの操作に応答します
4. 高度な機能を実装 → マスク入力、永続化、RTL を追加します
5. 外観をカスタマイズ → テーマとカスタムスタイルを適用します
6. アクセシビリティを確保 → キーボードとスクリーンリーダーに対応します
7. API を参照 → 必要に応じて API の完全なドキュメントを確認します