# 機能設計書 26-TimePicker

## 概要

本ドキュメントは、AvaloniaフレームワークにおけるTimePickerコントロールの機能設計を記載する。TimePickerは、時刻を選択するためのコントロールで、時・分・秒をスクロールで選択するUIを提供する。

### 本機能の処理概要

TimePickerは、ユーザーが時刻を選択するためのUIコントロールである。時間・分・AM/PM（12時間制の場合）をドロップダウンボタンからポップアップで選択する形式を提供する。24時間制と12時間制の両方に対応し、分の刻み（MinuteIncrement）を設定可能。

**業務上の目的・背景**：
業務アプリケーションにおいて時刻入力は予約システムやスケジュール管理で頻繁に発生する操作であり、直感的な時刻選択UIが必要である。

**機能の利用シーン**：
- 予約・アポイントメントの時刻指定
- アラーム・リマインダーの設定
- スケジュールの開始/終了時刻設定
- 勤怠管理の出退勤時刻入力
- イベントの時刻指定

**主要な処理内容**：
1. 時間・分・AM/PMのスクロール選択
2. 24時間制/12時間制の切り替え
3. MinuteIncrementによる分の刻み設定（1/5/10/15/30分など）
4. ClockIdentifierによる時間形式指定
5. SelectedTimeChangedイベントの発行
6. ヘッダーバナーの表示

**関連システム・外部連携**：
- TimePickerPresenterによる時刻選択ポップアップ表示
- TimeSpan型による時刻管理

**権限による制御**：
本コントロールには権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 63 | TimePicker | 主画面 | TimePickerコントロールのデモ |

## 機能種別

UI操作 / 入力コントロール / 時刻選択

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SelectedTime | TimeSpan? | No | 選択された時刻 | 00:00:00 〜 23:59:59 |
| MinuteIncrement | int | No | 分の刻み | 1〜59、60を割り切れる値を推奨、デフォルト: 1 |
| ClockIdentifier | string | No | 時計形式（"12HourClock"/"24HourClock"） | デフォルト: カルチャ依存 |
| Header | object | No | ヘッダーコンテンツ | - |

### 入力データソース

- ユーザーによる時間・分・AM/PMスクロール選択
- プログラムによるSelectedTime設定
- データバインディングによる時刻制御

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SelectedTime | TimeSpan? | 選択された時刻 |

### 出力先

- UI表示（時刻表示、選択状態）
- SelectedTimeChangedイベントの発行

## 処理フロー

### 処理シーケンス

```
1. 初期化
   └─ OnApplyTemplateでテンプレートパーツを取得
2. 入力検出
   └─ FlyoutButtonクリック → ポップアップ表示
3. 時刻選択
   ├─ 時間スクロール選択
   ├─ 分スクロール選択（MinuteIncrement単位）
   └─ AM/PM選択（12時間制の場合）
4. 選択確定
   └─ Accept/Dismissボタンによる確定/キャンセル
5. SelectedTime更新
   └─ プロパティ変更
6. UI更新
   └─ 時刻表示テキストの更新
7. イベント発行
   └─ SelectedTimeChanged
```

### フローチャート

```mermaid
flowchart TD
    A[FlyoutButtonクリック] --> B[ポップアップ表示]
    B --> C[TimePickerPresenter]
    C --> D{ClockIdentifier?}
    D -->|12HourClock| E[時間/分/AM-PM選択]
    D -->|24HourClock| F[時間/分選択]
    E --> G[Accept/Dismiss]
    F --> G
    G -->|Accept| H[SelectedTime更新]
    G -->|Dismiss| I[変更なし]
    H --> J[UI更新]
    J --> K[SelectedTimeChangedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 時間範囲 | SelectedTimeは00:00:00〜23:59:59の範囲 | 常時適用 |
| BR-002 | 分刻み | 分はMinuteIncrement単位で選択可能 | 常時適用 |
| BR-003 | 時計形式 | ClockIdentifierに基づき12時間制/24時間制を切り替え | 常時適用 |
| BR-004 | 双方向バインディング | SelectedTimeはデフォルトでTwoWayバインディング | 常時適用 |

### 計算ロジック

分リストの生成：
```
for (int i = 0; i < 60; i += MinuteIncrement) {
    minuteList.Add(i);
}
```

12時間制への変換：
```
hour12 = (hour24 % 12) == 0 ? 12 : hour24 % 12
period = hour24 >= 12 ? "PM" : "AM"
```

## データベース操作仕様

本コントロールはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 無効な時刻 | SelectedTimeが範囲外 | コエルスして範囲内に調整 |
| - | 無効なMinuteIncrement | 1未満または60以上 | デフォルト値(1)を使用 |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- ポップアップの表示は即座に行われる必要がある
- スクロール選択時のレスポンスは滑らか

## セキュリティ考慮事項

本コントロールにはセキュリティ上の特別な考慮事項はない。

## 備考

- UWP/WinUIのTimePickerと類似のAPIを提供
- TimeSpanを使用しているため、日付情報は含まない

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

TimePicker関連の型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TimePicker.cs | `src/Avalonia.Controls/DateTimePickers/TimePicker.cs` | プロパティ定義 |
| 1-2 | TimePickerPresenter.cs | `src/Avalonia.Controls/DateTimePickers/TimePickerPresenter.cs` | 時刻選択ポップアップ |

**読解のコツ**: TimePickerはTimePickerPresenterを使って時刻選択ポップアップを表示する。

#### Step 2: エントリーポイントを理解する

TimePickerクラスの主要プロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TimePicker.cs | `src/Avalonia.Controls/DateTimePickers/TimePicker.cs` | プロパティ定義 |

**主要処理フロー**:
1. **TemplatePart属性**: FlyoutButton、FlyoutContent、HourText、MinuteText、PeriodText等を定義
2. **プロパティ定義**: SelectedTime、MinuteIncrement、ClockIdentifier、Header等
3. **イベント定義**: SelectedTimeChanged

#### Step 3: テンプレート適用処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TimePicker.cs | `src/Avalonia.Controls/DateTimePickers/TimePicker.cs` | OnApplyTemplate |

**主要処理フロー**:
- テンプレートパーツの取得とイベントハンドラの設定
- 初期表示状態の設定
- Flyoutの設定

#### Step 4: 時刻選択処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TimePicker.cs | `src/Avalonia.Controls/DateTimePickers/TimePicker.cs` | OnSelectedTimeChanged |
| 4-2 | TimePickerPresenter.cs | `src/Avalonia.Controls/DateTimePickers/TimePickerPresenter.cs` | 時刻選択UI |

**主要処理フロー**:
- FlyoutButtonクリックでポップアップを開く
- TimePickerPresenterで時刻を選択
- 選択確定でSelectedTimeを更新

### プログラム呼び出し階層図

```
TimePicker
    │
    ├─ OnApplyTemplate
    │      ├─ テンプレートパーツ取得
    │      └─ SetSelectedTimeText（初期表示）
    │
    ├─ OnFlyoutButtonClicked
    │      └─ ShowPickerFlyout
    │             └─ TimePickerPresenter表示
    │
    ├─ OnFlyoutConfirmed
    │      ├─ SelectedTime更新
    │      └─ SetSelectedTimeText
    │
    └─ OnPropertyChanged
           └─ SelectedTime変更時
                  ├─ SetSelectedTimeText
                  └─ RaiseSelectedTimeChanged
```

### データフロー図

```
[入力]                    [処理]                         [出力]

FlyoutButton ───────▶ ShowPickerFlyout
クリック                    │
                           ▼
                    TimePickerPresenter
                           │
                    時間/分/AM-PM選択
                           │
                           ▼
Accept/Dismiss ─────▶ OnFlyoutConfirmed
                           │
                           ▼
                    SelectedTime更新
                           │
                           ├─▶ SetSelectedTimeText ──▶ UI表示更新
                           │
                           └─▶ SelectedTimeChangedイベント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TimePicker.cs | `src/Avalonia.Controls/DateTimePickers/TimePicker.cs` | ソース | メインコントロールクラス |
| TimePickerPresenter.cs | `src/Avalonia.Controls/DateTimePickers/TimePickerPresenter.cs` | ソース | 時刻選択ポップアッププレゼンター |
| DateTimePickerPanel.cs | `src/Avalonia.Controls/DateTimePickers/DateTimePickerPanel.cs` | ソース | 時/分スクロールパネル |
| TimePicker.xaml | `src/Avalonia.Themes.Fluent/Controls/TimePicker.xaml` | テンプレート | Fluentテーマのテンプレート |
| TimePickerPresenter.xaml | `src/Avalonia.Themes.Fluent/Controls/TimePickerPresenter.xaml` | テンプレート | プレゼンターテンプレート |
