# 画面設計書 27-Date/Time Picker

## 概要

本ドキュメントは、Avalonia ControlCatalogサンプルアプリケーションにおけるDate/Time Pickerデモページの画面設計を定義するものです。

### 本画面の処理概要

本画面は、DatePickerおよびTimePickerコントロールの各種使用パターンをデモンストレーションするためのページです。日付選択、時刻選択、フォーマットカスタマイズ、12/24時間制切り替えなど、日時入力UIの実装方法を学習・検証できる環境を提供します。

**業務上の目的・背景**：日付・時刻の入力は業務アプリケーションにおいて頻繁に必要とされる機能です。予約システム、スケジュール管理、タイムトラッキング、有効期限設定など、様々な場面で使用されます。DatePicker/TimePickerは、タッチ操作とマウス操作の両方に対応し、プラットフォーム固有の日時フォーマットに自動対応する標準的なUIを提供します。

**画面へのアクセス方法**：ControlCatalogアプリケーションのメインウィンドウから、HamburgerMenuのナビゲーションで「Date/Time Picker」を選択することでアクセスできます。

**主要な操作・処理内容**：
1. 基本的なDatePickerの表示と日付選択
2. 日フォーマットカスタマイズ（d (ddd)形式）と年非表示
3. 基本的なTimePickerの表示と時刻選択
4. 秒入力の有効化（UseSeconds=True）
5. 分・秒の増分指定（MinuteIncrement, SecondIncrement）
6. 12時間制と24時間制の切り替え（ClockIdentifier）
7. バリデーションエラー状態の表示

**画面遷移**：MainViewからHamburgerMenuナビゲーションを通じて遷移。画面内での追加遷移なし。

**権限による表示制御**：特になし（サンプルアプリケーション）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 25 | DatePicker | 主機能 | 日付選択コントロールのデモ。カレンダーポップアップ |
| 26 | TimePicker | 主機能 | 時刻選択コントロールのデモ。時・分選択 |

## 画面種別

デモ / サンプル表示

## URL/ルーティング

HamburgerMenu内部ナビゲーション（直接URLルーティングなし）

## 入出力項目

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|----------|------|------|
| DatePicker | 入力 | DateTimeOffset? | - | 選択された日付 |
| DatePicker（フォーマット付き） | 入力 | DateTimeOffset? | - | 日フォーマットカスタマイズ、年非表示 |
| TimePicker | 入力 | TimeSpan? | - | 選択された時刻 |
| TimePicker（秒付き） | 入力 | TimeSpan? | - | 秒入力有効 |
| TimePicker（増分指定） | 入力 | TimeSpan? | - | 分・秒増分設定 |
| TimePicker（12時間制） | 入力 | TimeSpan? | - | AM/PM選択付き |
| TimePicker（24時間制） | 入力 | TimeSpan? | - | 24時間表示 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| DatePicker説明 | TextBlock | DatePickerの概要説明（動的設定） |
| TimePicker説明 | TextBlock | TimePickerの概要説明（動的設定） |
| 各セクションタイトル | TextBlock | 各デモセクションの説明 |
| XAMLコード例 | TextBlock | 各コントロールのXAMLコードサンプル |

## イベント仕様

### 1-DatePicker日付選択

DatePickerをクリックするとカレンダーポップアップが表示される。月・日・年のスピナーで日付を選択可能。ユーザーの日付設定に基づいて表示順序が動的に決定される。

### 2-DatePicker（フォーマット付き）日付選択

DayFormat="d (ddd)"により、日付が「1 (Mon)」形式で表示される。YearVisible="False"により年選択が非表示。

### 3-TimePicker時刻選択

TimePickerをクリックすると時・分選択ポップアップが表示される。スピナー形式で時刻を選択可能。

### 4-TimePicker（秒付き）時刻選択

UseSeconds="True"により、秒の入力が可能になる。時・分・秒の3つのスピナーが表示される。

### 5-TimePicker（増分指定）時刻選択

MinuteIncrement="15"、SecondIncrement="30"により、選択可能な値が制限される（例：分は0, 15, 30, 45のみ）。

### 6-TimePicker（12時間制）時刻選択

ClockIdentifier="12HourClock"により、AM/PM選択が表示される。時間は1-12の範囲で表示。

### 7-TimePicker（24時間制）時刻選択

ClockIdentifier="24HourClock"により、時間は0-23の範囲で表示される。AM/PM選択なし。

## データベース更新仕様

### 操作別データベース影響一覧

本画面はUIコントロールのデモであり、データベース操作は行いません。

## メッセージ仕様

本画面にはユーザー操作によるメッセージ表示はありません。説明テキストはコードビハインドで設定されます。

## 例外処理

- DataValidationErrors.Errorが設定されたDatePicker/TimePickerはエラー状態で表示される（デモ目的）

## 備考

- 日付・時刻の表示順序はユーザーのシステム設定に依存
- プラットフォームによってポップアップの見た目が異なる場合がある
- ClockIdentifierの値は"12HourClock"または"24HourClock"
- MinuteIncrement/SecondIncrementは1-59の範囲で設定可能

---

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

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

### 推奨読解順序

#### Step 1: 画面レイアウトを理解する

XAMLで各コントロールの設定パターンを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DateTimePickerPage.xaml | `samples/ControlCatalog/Pages/DateTimePickerPage.xaml` | DatePicker/TimePickerの各種属性設定、サンプルコード表示パターン |

**主要処理フロー**:
1. **行9-10**: 説明テキスト用TextBlock（動的設定）
2. **行16-31**: 基本DatePicker + XAMLサンプル表示
3. **行34-41**: DataValidationErrors付きDatePicker
4. **行43-59**: DayFormat/YearVisible設定DatePicker
5. **行63-78**: 基本TimePicker + XAMLサンプル表示
6. **行80-95**: UseSeconds="True"のTimePicker
7. **行97-104**: DataValidationErrors付きTimePicker
8. **行106-121**: MinuteIncrement設定TimePicker
9. **行123-138**: MinuteIncrement/SecondIncrement両方設定
10. **行140-155**: 12HourClock TimePicker
11. **行157-172**: 24HourClock TimePicker
12. **行174-189**: 12HourClock + UseSeconds
13. **行191-206**: 24HourClock + UseSeconds

#### Step 2: コードビハインドを理解する

説明テキストの動的設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DateTimePickerPage.xaml.cs | `samples/ControlCatalog/Pages/DateTimePickerPage.xaml.cs` | コンストラクタでの説明テキスト設定 |

**主要処理フロー**:
- **行7-18**: コンストラクタで DatePickerDesc.Text と TimePickerDesc.Text を設定

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

```
DateTimePickerPage (UserControl)
    │
    ├─ コンストラクタ
    │      └─ DatePickerDesc.Text = "..." (説明文)
    │      └─ TimePickerDesc.Text = "..." (説明文)
    │
    ├─ DatePicker群
    │      ├─ 基本DatePicker
    │      ├─ DataValidationErrors付き
    │      └─ DayFormat/YearVisible設定
    │
    └─ TimePicker群
           ├─ 基本TimePicker
           ├─ UseSeconds=True
           ├─ MinuteIncrement設定
           ├─ MinuteIncrement + SecondIncrement
           ├─ 12HourClock
           ├─ 24HourClock
           ├─ 12HourClock + UseSeconds
           └─ 24HourClock + UseSeconds
```

### データフロー図

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

ユーザー操作 ───────────▶ Picker展開 ─────────────────────▶ ポップアップ表示
                              │
                              ├─ スピナー操作 ─────────────▶ 値変更
                              │
                              └─ 確定操作 ──────────────────▶ SelectedDate/SelectedTime更新

システム設定 ───────────▶ 日付フォーマット ────────────────▶ 表示順序決定
                              │
                              └─ 時計形式 ──────────────────▶ 12/24時間制表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DateTimePickerPage.xaml | `samples/ControlCatalog/Pages/DateTimePickerPage.xaml` | XAML | 画面レイアウト定義 |
| DateTimePickerPage.xaml.cs | `samples/ControlCatalog/Pages/DateTimePickerPage.xaml.cs` | ソース | コードビハインド |
