# 機能設計書 25-DatePicker

## 概要

本ドキュメントは、AvaloniaフレームワークにおけるDatePickerコントロールの機能設計を記載する。DatePickerは、日付を選択するためのコントロールで、テキストボックスとポップアップカレンダーを組み合わせたUIを提供する。

### 本機能の処理概要

DatePickerは、ユーザーが日付を選択するためのUIコントロールである。テキストボックスによる直接入力と、ドロップダウンボタンからポップアップカレンダーを開いての選択の両方をサポートする。選択された日付は指定したフォーマットで表示される。

**業務上の目的・背景**：
業務アプリケーションにおいて日付入力は頻繁に発生する操作であり、キーボード入力とカレンダー選択の両方の手段を提供することで、ユーザーの入力効率と正確性を向上させる。

**機能の利用シーン**：
- フォームでの生年月日入力
- 予約・申込の日付指定
- レポートの対象日付選択
- タスクの期限設定
- 検索フィルターでの日付範囲指定

**主要な処理内容**：
1. テキストボックスへの日付入力と解析
2. ドロップダウンボタンによるカレンダーポップアップ表示
3. カレンダーでの日付選択とテキストボックスへの反映
4. 日付フォーマットに基づく表示制御（年/月/日の表示順序）
5. YearFormat/MonthFormat/DayFormatによるカスタム書式
6. SelectedDateChangedイベントの発行
7. ヘッダーバナーの表示

**関連システム・外部連携**：
- DatePickerPresenterによるカレンダーポップアップ表示
- DateTimeOffset型による日付管理

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | DatePicker | 主画面 | DatePickerコントロールのデモ |
| 18 | CalendarDatePicker | 関連 | 類似コントロールとしてCalendarDatePicker |

## 機能種別

UI操作 / 入力コントロール / 日付選択

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SelectedDate | DateTimeOffset? | No | 選択された日付 | MinYear〜MaxYear内 |
| MinYear | DateTimeOffset | No | 選択可能な最小年 | デフォルト: 1601 |
| MaxYear | DateTimeOffset | No | 選択可能な最大年 | MinYear以上 |
| DayVisible | bool | No | 日の列を表示するか | デフォルト: true |
| MonthVisible | bool | No | 月の列を表示するか | デフォルト: true |
| YearVisible | bool | No | 年の列を表示するか | デフォルト: true |
| DayFormat | string | No | 日のフォーマット | デフォルト: "d" |
| MonthFormat | string | No | 月のフォーマット | デフォルト: "MMMM" |
| YearFormat | string | No | 年のフォーマット | デフォルト: "yyyy" |
| Header | object | No | ヘッダーコンテンツ | - |

### 入力データソース

- ユーザーによるテキスト直接入力
- ユーザーによるカレンダーポップアップからの選択
- プログラムによるSelectedDate設定
- データバインディングによる日付制御

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SelectedDate | DateTimeOffset? | 選択された日付 |

### 出力先

- UI表示（テキストボックス、選択状態）
- SelectedDateChangedイベントの発行

## 処理フロー

### 処理シーケンス

```
1. 初期化
   └─ OnApplyTemplateでテンプレートパーツを取得
2. 入力検出
   ├─ テキスト入力: OnTextChanged
   └─ カレンダー選択: OnPopupOpened → 日付選択 → OnPopupClosed
3. 日付解析・検証
   └─ TryParseDateでテキストを日付に変換
4. 日付範囲検証
   └─ MinYear/MaxYear範囲チェック
5. SelectedDate更新
   └─ プロパティ変更
6. UI更新
   └─ フォーマットに従いテキスト表示更新
7. イベント発行
   └─ SelectedDateChanged
```

### フローチャート

```mermaid
flowchart TD
    A[入力開始] --> B{入力タイプ}
    B -->|テキスト入力| C[OnTextChanged]
    B -->|ドロップダウン| D[OnPopupOpened]
    C --> E[TryParseDate]
    E --> F{解析成功?}
    F -->|No| G[エラー表示]
    F -->|Yes| H{範囲内?}
    D --> I[カレンダー表示]
    I --> J[日付選択]
    J --> H
    H -->|No| K[範囲内に調整]
    H -->|Yes| L[SelectedDate更新]
    K --> L
    L --> M[UI更新]
    M --> N[SelectedDateChangedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 年範囲制限 | SelectedDateはMinYear〜MaxYear内に制限 | 常時適用 |
| BR-002 | フォーマット適用 | DayFormat/MonthFormat/YearFormatに従い表示 | 常時適用 |
| BR-003 | 列表示制御 | DayVisible/MonthVisible/YearVisibleで表示列を制御 | 常時適用 |
| BR-004 | 双方向バインディング | SelectedDateはデフォルトでTwoWayバインディング | 常時適用 |
| BR-005 | カレンダーポップアップ | IsDropDownOpenでポップアップの開閉を制御 | ドロップダウン操作時 |

### 計算ロジック

日付表示の組み立て：
```
DateTimeOffsetHelper.TryFormat(SelectedDate, DayFormat, MonthFormat, YearFormat, displayText)
カルチャに応じて年/月/日の順序を決定（DateTimeFormatInfo.ShortDatePattern参照）
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 無効な日付形式 | テキスト入力が日付として解析不可 | 元の値を維持、または擬似クラス:invalidを設定 |
| - | 範囲外日付 | MinYear/MaxYear範囲外の日付 | 範囲内にコエルス |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- カレンダーポップアップの表示は即座に行われる必要がある
- テキスト入力時の日付解析は入力完了時に実行

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

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

## 備考

- DateTimeOffsetを使用しているため、タイムゾーン情報も保持可能
- UWP/WinUIのDatePickerと類似のAPIを提供

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DatePicker.cs | `src/Avalonia.Controls/DateTimePickers/DatePicker.cs` | プロパティ定義 |
| 1-2 | DatePickerPresenter.cs | `src/Avalonia.Controls/DateTimePickers/DatePickerPresenter.cs` | カレンダーポップアップ表示 |

**読解のコツ**: DatePickerはDatePickerPresenterを使ってカレンダーポップアップを表示する。PickerBase/TimePickerBaseとは構造が異なる。

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

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

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

**主要処理フロー**:
1. **TemplatePart属性**: FlyoutButton、FlyoutContent、DayText、MonthText、YearText等を定義
2. **プロパティ定義**: DayFormat、MonthFormat、YearFormat、SelectedDate等
3. **イベント定義**: SelectedDateChanged

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

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

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

#### Step 4: 日付選択処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | DatePicker.cs | `src/Avalonia.Controls/DateTimePickers/DatePicker.cs` | OnSelectedDateChanged、OnFlyoutOpened |
| 4-2 | DatePickerPresenter.cs | `src/Avalonia.Controls/DateTimePickers/DatePickerPresenter.cs` | 日付選択UI |

**主要処理フロー**:
- Flybutボタンクリックでポップアップを開く
- DatePickerPresenterで日付を選択
- 選択確定でSelectedDateを更新

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

```
DatePicker
    │
    ├─ OnApplyTemplate
    │      ├─ テンプレートパーツ取得
    │      └─ SetSelectedDateText（初期表示）
    │
    ├─ OnFlyoutButtonClicked
    │      └─ ShowPickerFlyout
    │             └─ DatePickerPresenter表示
    │
    ├─ OnFlyoutConfirmed
    │      ├─ SelectedDate更新
    │      └─ SetSelectedDateText
    │
    └─ OnPropertyChanged
           └─ SelectedDate変更時
                  ├─ SetSelectedDateText
                  └─ RaiseSelectedDateChanged
```

### データフロー図

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

FlyoutButton ───────▶ ShowPickerFlyout
クリック                    │
                           ▼
                    DatePickerPresenter
                           │
                    日付スクロール選択
                           │
                           ▼
Accept/Dismiss ─────▶ OnFlyoutConfirmed
                           │
                           ▼
                    SelectedDate更新
                           │
                           ├─▶ SetSelectedDateText ──▶ UI表示更新
                           │
                           └─▶ SelectedDateChangedイベント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DatePicker.cs | `src/Avalonia.Controls/DateTimePickers/DatePicker.cs` | ソース | メインコントロールクラス |
| DatePickerPresenter.cs | `src/Avalonia.Controls/DateTimePickers/DatePickerPresenter.cs` | ソース | カレンダーポップアッププレゼンター |
| DateTimePickerPanel.cs | `src/Avalonia.Controls/DateTimePickers/DateTimePickerPanel.cs` | ソース | 年/月/日スクロールパネル |
| DatePicker.xaml | `src/Avalonia.Themes.Fluent/Controls/DatePicker.xaml` | テンプレート | Fluentテーマのテンプレート |
| DatePickerPresenter.xaml | `src/Avalonia.Themes.Fluent/Controls/DatePickerPresenter.xaml` | テンプレート | プレゼンターテンプレート |
