syncfusion-angular-datepicker

Syncfusion Angular DatePicker の実装

Syncfusion Angular DatePicker は、日付の書式設定、検証、日付範囲、および完全なアクセシビリティ（WCAG 2.2）に対応した、使いやすいカレンダーインターフェースを提供します。このスキルでは、基本的な実装パターンから高度な機能まで、必要な内容をすべて解説します。

コンポーネントの概要

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

• カレンダー UI またはテキスト入力による日付の選択
• 複数の日付形式（カルチャー対応、カスタムパターン）
• 日付範囲の検証（最小値／最大値、厳密モード）
• 日付入力を補助する入力マスク
• 複数のカレンダービュー（月 → 年 → 10 年単位での移動）
• アクセシビリティ（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

• 開始ビューの設定（月／年／10 年単位）
• 選択範囲を限定する深度ビューの制限
• カレンダービュー間の移動
• 月と年の選択パターン
• 各種ビュー設定のユースケース

マスクと編集

📄 参照先: 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	カレンダーの種類（例：Gregorian、Islamic）
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	年の第1週の規則
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. 誕生日／生年月日の選択： 最小値／最大値の検証、マスク付き入力、年をすばやく選択できる decade 開始ビュー
2. ミーティングのスケジュール設定： 日付範囲（今日から90日後まで）、カスタムの稼働日の検証、フォームとの統合
3. ホテル／航空券の予約： 最小値／最大値の日付、双方向の日付バインディング、検証付きのリアクティブフォーム
4. 申請フォーム： 生年月日、ライセンスの有効期限、アクセシビリティ要件に準拠した予約日
5. 国際的な申請： ロケールに応じた書式設定、RTL サポート、文化圏固有のカレンダー

---

次のステップ：

• ユースケースに該当するリファレンスファイルを読みます
• 一般向けアプリを構築する場合は、アクセシビリティ要件を確認します
• アクセシビリティ対応が必要な場合は、キーボード操作でテストします
• 複数の文化圏に対応する場合は、CLDR のローカライズを設定します