syncfusion-angular-calendar

Syncfusion Angular Calendar の実装

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

Calendar の概要

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

• 複数のカレンダー表示： 月（デフォルト）、年、10 年単位の表示をスムーズに切り替えられます
• 日付選択モード： 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

• 月表示（デフォルト表示）
• 年表示の実装
• 10 年単位の表示の実装
• 表示の切り替えと遷移
• 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

• 月のナビゲーションコントロール
• 年表示と 10 年単位の表示の切り替え
• 今日ボタン（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）
• キーボードショートカットのキー設定
• カレンダーモード（グレゴリオ暦、イスラム暦）
• 戻り値の型と説明

クイックスタートの例

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

注： 組み込みの日付範囲ピッカーを使用するには、代わりに DateRangePicker コンポーネントを使用してください。

パターン 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：年／ दशक表示のナビゲーション

異なるカレンダー表示へのナビゲーションを実装します。

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 Reactive Forms と連携します。

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	初期表示（月／年／10 年）	start="Month"
depth	CalendarView	表示の最大レベル	depth="Month"
showTodayButton	boolean	今日ボタンを表示します	[showTodayButton]="true"
locale	string	地域／言語コード	locale="fr-FR"
dayHeaderFormat	DayHeaderFormats	曜日の形式（短縮／最短／省略／完全）	dayHeaderFormat="Abbreviated"
weekNumber	boolean	週番号を表示します	[weekNumber]="true"
weekRule	WeekRule	年の第 1 週の規則（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	カレンダーモード（グレゴリオ暦／イスラム暦）	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 に準拠します
• 解決策：Reactive Forms とカレンダーイベントを使用します
• 参考：アクセシビリティとグローバリゼーション

ユースケース 4：国際対応の日付選択

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

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

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

関連スキル

• Syncfusion Angular コンポーネントの実装 - すべての Angular コンポーネントを対象としたメインライブラリガイド
• DatePicker - オーバーレイ機能を備えたカレンダーポップアップ
• Scheduler - イベントと予定を扱う高度なカレンダー
• DateRangePicker - 日付範囲の選択に特化したコンポーネント

---

次のステップ： 特定のニーズに応じて上記のリファレンスガイドを選ぶか、ユースケースに合った一般的なパターンのセクションをご覧ください。