syncfusion-angular-timepicker

Syncfusion Angular TimePicker の実装

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

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

基本的な実装

📄 参照： references/basic-implementation.md

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

時刻の設定

📄 参照： references/time-configuration.md

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

イベントとコールバック

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

• ChangeEventArgs を使用した change イベント
• focus／blur イベントの処理
• ポップアップの open／close イベント
• created／destroyed のライフサイクルイベント
• クリアボタン使用時の 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、Space、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：リアクティブフォームとの統合

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

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 ドキュメント全体を確認する

---

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