syncfusion-angular-datetimepicker

Syncfusion Angular 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 と Standalone コンポーネントのセットアップ
• CSS テーマのインポートと依存関係
• 基本的な datetimepicker の実装
• コンポーネントの初期化とアプリケーションの実行
• 開発サーバーのセットアップ

基本的な実装

📄 参照： references/basic-implementation.md

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

日付と時刻の設定

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

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

カレンダーと時刻の表示

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

• カレンダーの表示モード（month、year、decade）
• 表示を制御する start プロパティと depth プロパティ
• タイムピッカーポップアップの設定
• 時刻のステップ間隔と粒度
• 時刻スクロール用の ScrollTo 位置
• Today ボタンと clear ボタンの動作

イベントとコールバック

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

• ChangedEventArgs を使った change イベント
• focus／blur イベントの処理
• ポップアップの open／close イベント
• created／destroyed ライフサイクルイベント
• カレンダーのナビゲーション用 navigate イベント
• 日付のスタイルをカスタマイズする RenderDayCell
• clear ボタンの使用時に発生する 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：リアクティブフォームとの統合

datetimepicker を Angular Reactive Forms と統合します。

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	初期カレンダービュー（月／年／10 年）
depth	CalendarView	カレンダービューの最大レベル
locale	string	書式設定に使用するロケール（例：'en-US'、'de-DE'）

一般的なユースケース

予約システム

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

イベントスケジュール

• イベントの開始日時と終了日時を選択します
• renderDayCellで週末の日付を無効にします
• 一般的な所要時間（30、60分）にはステップ間隔を使用します
• API送信用に出力をフォーマットします

シフト管理

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

請求と請求書

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

次のステップ

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

---

始める準備はできましたか？ インストールとセットアップの手順については、references/getting-started.mdをご覧ください。