# 機能設計書 91-DataTemplate

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるデータテンプレート（DataTemplate）機能の設計仕様を記述します。データテンプレートは、データオブジェクトをビジュアル要素として表現するための仕組みであり、MVVM（Model-View-ViewModel）パターンにおける重要な構成要素です。

### 本機能の処理概要

DataTemplate機能は、任意のデータオブジェクトに対応するUIコントロールを動的に生成・管理する仕組みを提供します。これにより、データとビューの分離を実現し、柔軟で再利用可能なUI構築が可能になります。

**業務上の目的・背景**：MVVMパターンを採用するアプリケーションでは、ビジネスデータ（ViewModelやModel）を画面に表示する際、データの型に応じた適切なビジュアル表現が必要です。DataTemplateは、この「データ→ビジュアル」の変換ルールを定義し、一貫性のあるUI表現と保守性の高いコードベースを実現します。ListBoxやComboBox等のItemsControlでリスト表示を行う際、各アイテムの表示方法を統一的に制御できます。

**機能の利用シーン**：
- ListBox、TreeView、DataGrid等でのリストアイテム表示
- ContentControlでのデータバインディング表示
- 異なる型のデータに対して異なるテンプレートを適用する場面
- 再利用可能なデータ表示パターンの定義

**主要な処理内容**：
1. IDataTemplateインターフェースによるテンプレートマッチング（Match関数）
2. テンプレートからControlインスタンスの生成（Build関数）
3. データ型に基づく適切なテンプレートの選択
4. コントロールのリサイクル（IRecyclingDataTemplate）による性能最適化
5. 階層データ用のツリーデータテンプレート（ITreeDataTemplate）
6. DataTemplatesコレクションによる複数テンプレートの管理

**関連システム・外部連携**：XAMLマークアップシステムと連携し、宣言的なテンプレート定義を可能にします。また、データバインディングシステムと統合され、DataContextの変更に応じた動的なUI更新を実現します。

**権限による制御**：本機能はUI表示に関する機能であり、特別な権限制御はありません。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面共通 | 主機能 | ItemsControlを使用する全ての画面でデータ表示に利用 |

## 機能種別

ビジュアル生成処理 / テンプレートマッチング / UI構築

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| data | object? | Yes | テンプレート適用対象のデータオブジェクト | null許容 |
| match | Func<object?, bool> | No | マッチング条件を判定するデリゲート | nullの場合は例外 |
| build | Func<object?, INameScope, Control?> | Yes | コントロール生成用デリゲート | nullの場合は例外 |
| supportsRecycling | bool | No | リサイクル対応フラグ（デフォルトfalse） | - |

### 入力データソース

- DataContext経由で設定されるViewModelやModelオブジェクト
- ItemsSource経由でバインドされるコレクション要素
- XAMLで定義されたDataTemplate/ControlTemplate

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Control | Control? | 生成されたUIコントロール |
| Match結果 | bool | テンプレートがデータにマッチするかどうか |

### 出力先

- ビジュアルツリーへのコントロール挿入
- ContentPresenter / ItemsPresenter への表示

## 処理フロー

### 処理シーケンス

```
1. データオブジェクトの受信
   └─ DataContext変更またはItemsSourceバインド
2. テンプレートマッチング
   └─ DataTemplatesコレクションを走査しMatch()で適合判定
3. テンプレートの選択
   └─ 最初にマッチしたテンプレートを使用
4. コントロール生成
   └─ Build()メソッドでControlインスタンスを作成
5. DataContext設定
   └─ 生成されたControlにデータオブジェクトを設定
6. ビジュアルツリーへの挿入
   └─ 親コンテナにコントロールを追加
```

### フローチャート

```mermaid
flowchart TD
    A[データオブジェクト受信] --> B{DataTemplatesコレクション走査}
    B --> C{Match成功?}
    C -->|Yes| D[テンプレート選択]
    C -->|No| E{次のテンプレートあり?}
    E -->|Yes| B
    E -->|No| F[デフォルトテンプレート使用]
    D --> G{リサイクル可能?}
    F --> G
    G -->|Yes| H{既存コントロールあり?}
    G -->|No| I[新規コントロール生成]
    H -->|Yes| J[既存コントロール再利用]
    H -->|No| I
    I --> K[DataContext設定]
    J --> K
    K --> L[ビジュアルツリー挿入]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-91-01 | 型マッチング | ITypedDataTemplateの場合、DataTypeプロパティに基づいて型チェック | DataTypeが設定されている場合 |
| BR-91-02 | デフォルトテンプレート | マッチするテンプレートがない場合、FuncDataTemplate.Defaultを使用 | テンプレート未発見時 |
| BR-91-03 | リサイクル優先 | supportsRecycling=trueの場合、既存コントロールを再利用 | IRecyclingDataTemplate実装時 |
| BR-91-04 | DataType必須検証 | DataTemplatesコレクション内のテンプレートはDataType必須 | DataTemplatesに追加時 |

### 計算ロジック

テンプレートマッチングはDataTemplatesコレクションの登録順に評価され、最初にMatch()がtrueを返したテンプレートが使用されます。

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

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

本機能はデータベース操作を伴いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidOp-01 | InvalidOperationException | DataTemplates内のテンプレートにDataTypeが未設定 | DataTypeプロパティを設定する |
| ArgNull-01 | ArgumentNullException | matchデリゲートがnull | 有効なマッチング関数を指定 |

### リトライ仕様

エラー発生時のリトライは行いません。

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

本機能はUI処理のため、トランザクション管理は不要です。

## パフォーマンス要件

- IRecyclingDataTemplateの使用により、大量データのスクロール時にコントロール再利用で性能向上
- VirtualizingStackPanelとの組み合わせで仮想化対応

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

特別なセキュリティ要件はありません。

## 備考

FuncDataTemplate.Defaultは、データがnullでない場合にTextBlockを生成し、ToString()の結果を表示します。

---

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

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

### 推奨読解順序

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

まず、データテンプレートのインターフェース階層を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IDataTemplate.cs | `src/Avalonia.Controls/Templates/IDataTemplate.cs` | 基本インターフェース。Match()とBuild()の2つのメソッドを定義 |
| 1-2 | ITypedDataTemplate.cs | `src/Avalonia.Controls/Templates/ITypedDataTemplate.cs` | DataTypeプロパティを持つ型付きテンプレート |
| 1-3 | IRecyclingDataTemplate.cs | `src/Avalonia.Controls/Templates/IRecyclingDataTemplate.cs` | コントロールリサイクルをサポートするテンプレート |
| 1-4 | ITreeDataTemplate.cs | `src/Avalonia.Controls/Templates/ITreeDataTemplate.cs` | 階層データ用テンプレート |

**読解のコツ**: C#のインターフェース継承を確認し、ITemplate<object?, Control?>からの継承関係を把握してください。

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

テンプレートの実装クラスを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | FuncDataTemplate.cs | `src/Avalonia.Controls/Templates/FuncDataTemplate.cs` | 関数ベースのデータテンプレート実装 |

**主要処理フロー**:
1. **14-32行目**: Default静的プロパティ - デフォルトテンプレートの定義
2. **57-76行目**: コンストラクタ - 型ベースのマッチング設定
3. **88-96行目**: コンストラクタ - カスタムマッチング関数の設定
4. **105-108行目**: Match() - データマッチング判定
5. **123-126行目**: Build(data, existing) - リサイクル対応のコントロール生成

#### Step 3: コレクション管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | DataTemplates.cs | `src/Avalonia.Controls/Templates/DataTemplates.cs` | テンプレートコレクション |

**主要処理フロー**:
- **20-31行目**: バリデーション - DataType必須チェック

#### Step 4: 拡張メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | DataTemplateExtensions.cs | `src/Avalonia.Controls/Templates/DataTemplateExtensions.cs` | テンプレート検索の拡張メソッド |
| 4-2 | TemplateExtensions.cs | `src/Avalonia.Controls/Templates/TemplateExtensions.cs` | テンプレート適用の拡張メソッド |

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

```
IDataTemplate (インターフェース)
    │
    ├─ FuncDataTemplate
    │      ├─ Match() → _matchデリゲート実行
    │      └─ Build() → _buildデリゲート実行
    │
    ├─ FuncDataTemplate<T>
    │      └─ 型パラメータによる型安全なマッチング
    │
    └─ FuncTreeDataTemplate
           └─ ItemsSelector() → 子要素取得

DataTemplates (コレクション)
    │
    └─ IAvaloniaListItemValidator<IDataTemplate>
           └─ Validate() → DataType必須チェック
```

### データフロー図

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

データオブジェクト ───▶ IDataTemplate.Match() ───▶ マッチ結果(bool)
         │
         ├─ マッチ成功 ─▶ IDataTemplate.Build() ───▶ Control
         │
         └─ マッチ失敗 ─▶ 次のテンプレートへ
                          または
                          FuncDataTemplate.Default ───▶ TextBlock
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| IDataTemplate.cs | `src/Avalonia.Controls/Templates/IDataTemplate.cs` | ソース | 基本インターフェース |
| ITypedDataTemplate.cs | `src/Avalonia.Controls/Templates/ITypedDataTemplate.cs` | ソース | 型付きテンプレートインターフェース |
| IRecyclingDataTemplate.cs | `src/Avalonia.Controls/Templates/IRecyclingDataTemplate.cs` | ソース | リサイクル対応インターフェース |
| ITreeDataTemplate.cs | `src/Avalonia.Controls/Templates/ITreeDataTemplate.cs` | ソース | ツリーデータ用インターフェース |
| FuncDataTemplate.cs | `src/Avalonia.Controls/Templates/FuncDataTemplate.cs` | ソース | 関数ベース実装 |
| FuncDataTemplate`1.cs | `src/Avalonia.Controls/Templates/FuncDataTemplate`1.cs` | ソース | ジェネリック版実装 |
| FuncTreeDataTemplate.cs | `src/Avalonia.Controls/Templates/FuncTreeDataTemplate.cs` | ソース | ツリーテンプレート実装 |
| DataTemplates.cs | `src/Avalonia.Controls/Templates/DataTemplates.cs` | ソース | テンプレートコレクション |
| DataTemplateExtensions.cs | `src/Avalonia.Controls/Templates/DataTemplateExtensions.cs` | ソース | 拡張メソッド |
| IDataTemplateHost.cs | `src/Avalonia.Controls/Templates/IDataTemplateHost.cs` | ソース | テンプレートホストインターフェース |
| ITemplate`1.cs | `src/Avalonia.Controls/Templates/ITemplate`1.cs` | ソース | 基底テンプレートインターフェース |
| ITemplate`2.cs | `src/Avalonia.Controls/Templates/ITemplate`2.cs` | ソース | 2型パラメータテンプレート |
