# 機能設計書 61-TemplateBinding

## 概要

本ドキュメントは、Avaloniaフレームワークにおける**TemplateBinding**機能の設計仕様を記述する。TemplateBindingは、コントロールテンプレート内でテンプレート化された親コントロールのプロパティにバインドするための特殊なバインディング機能を提供する。

### 本機能の処理概要

TemplateBindingは、コントロールテンプレート内の要素からテンプレート化された親コントロール（TemplatedParent）のプロパティへの軽量で高速なバインディングを実現する機能である。通常のBindingと比較して、よりシンプルな構文と高速な実行を提供する。

**業務上の目的・背景**：UIフレームワークにおいて、カスタムコントロールを作成する際、テンプレート内の要素が親コントロールのプロパティ値を反映する必要がある。例えば、ButtonコントロールのTemplateでContentPresenterがButtonのContentプロパティを表示する場合などが典型的なユースケースである。TemplateBindingは、このようなテンプレート内バインディングを簡潔かつ効率的に実現する。

**機能の利用シーン**：
- ControlTemplateの定義においてテンプレート化された親のプロパティを参照する場合
- カスタムコントロールのテンプレート作成時にプロパティ値を子要素に伝播させる場合
- スタイルやテーマの定義でコントロールの外観をプロパティに基づいて動的に変更する場合

**主要な処理内容**：
1. テンプレート化された親コントロール（TemplatedParent）の取得とプロパティ値の監視
2. プロパティ値の変換（IValueConverterを使用した変換処理）
3. 双方向バインディングのサポート（OneWay, TwoWay, OneWayToSourceモード）
4. 値変更時のターゲットプロパティへの自動更新

**関連システム・外部連携**：TemplateBindingはAvalonia.Base.Dataモジュール内で実装され、スタイリングシステム（Styling）およびコントロールテンプレートシステム（Controls）と密接に連携する。

**権限による制御**：特にアクセス権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全コントロール | 主機能 | コントロールテンプレート内でのプロパティバインディング |

## 機能種別

データバインディング / テンプレートプロパティ連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Property | AvaloniaProperty | No | バインドするソースプロパティ | nullの場合はTemplatedParent自体を返す |
| Converter | IValueConverter | No | 値変換用のコンバーター | - |
| ConverterCulture | CultureInfo | No | コンバーターで使用するカルチャー | デフォルトはCurrentCulture |
| ConverterParameter | object | No | コンバーターに渡すパラメータ | - |
| Mode | BindingMode | No | バインディングモード | OneTime, OneWayToSourceは非サポート |

### 入力データソース

- テンプレート化された親コントロール（TemplatedParent）のプロパティ値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Value | object | バインドされたプロパティの値（変換後） |

### 出力先

- ターゲット要素のAvaloniaProperty（バインド先プロパティ）

## 処理フロー

### 処理シーケンス

```
1. TemplateBindingの生成
   └─ Property, Converter, Mode等のパラメータを設定
2. バインディングの適用（CreateInstance呼び出し）
   └─ TemplateBindingExpressionのインスタンス生成
3. バインディング開始（StartCore）
   └─ TemplatedParentの取得と監視開始
4. 値の取得と配信（PublishValue）
   └─ ソースプロパティ値の取得 → コンバーター適用 → 型変換 → ターゲットへ配信
5. プロパティ変更時の更新
   └─ ソースまたはターゲットのプロパティ変更を検知して値を同期
6. バインディング終了（StopCore）
   └─ イベントハンドラの解除とリソース解放
```

### フローチャート

```mermaid
flowchart TD
    A[TemplateBinding開始] --> B{TemplatedParent取得}
    B -->|成功| C[プロパティ監視開始]
    B -->|失敗| D[UnsetValue配信]
    C --> E[プロパティ値取得]
    E --> F{Converter設定あり?}
    F -->|Yes| G[Converter適用]
    F -->|No| H[型変換処理]
    G --> H
    H --> I[ターゲットへ値配信]
    I --> J{OneTimeモード?}
    J -->|Yes| K[バインディング停止]
    J -->|No| L[変更監視継続]
    L --> M{プロパティ変更検知}
    M -->|ソース変更| E
    M -->|ターゲット変更| N{TwoWay/OneWayToSource?}
    N -->|Yes| O[ソースへ値書き込み]
    N -->|No| L
    O --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-61-01 | サポートモード制限 | OneTimeとOneWayToSourceモードはサポートされない | TemplateBinding使用時 |
| BR-61-02 | プロパティnull時動作 | Propertyがnullの場合、TemplatedParent自体が値として返される | Property未設定時 |
| BR-61-03 | バインディング優先度 | TemplateBindingはBindingPriority.Templateの優先度で適用される | 常時 |

### 計算ロジック

- 値変換ロジック: Converter?.Convert(value, targetType, converterParameter, culture)
- 逆変換ロジック: Converter?.ConvertBack(value, targetType, converterParameter, culture)

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | NotSupportedException | OneTimeまたはOneWayToSourceモードを指定した場合 | サポートされるモードを使用する |
| - | 型変換エラー | ソース値をターゲット型に変換できない場合 | 警告ログ出力後、UnsetValueを返す |

### リトライ仕様

リトライ処理は行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

- 通常のBindingより軽量な実装を目指す
- プロパティ変更通知は即座に処理される

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

特段のセキュリティ要件はない。

## 備考

- TemplateBindingは{TemplateBinding Property}の形式でXAMLで使用される
- C#コードからはTemplateBindingクラスを直接インスタンス化して使用可能

---

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

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

### 推奨読解順序

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

TemplateBindingの基本構造とプロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TemplateBinding.cs | `src/Avalonia.Base/Data/TemplateBinding.cs` | バインディング定義クラス。Property, Converter, Modeの各プロパティを確認 |

**読解のコツ**: TemplateBindingはBindingBaseを継承し、ProvideValueメソッドでself参照を返すマークアップ拡張として機能する。

**主要処理フロー**:
1. **14-21行目**: コンストラクタ - Propertyパラメータの設定
2. **26-46行目**: プロパティ定義 - Converter, ConverterCulture, ConverterParameter, Mode, Property
3. **57-68行目**: CreateInstance - バインディング式の生成（OneTime/OneWayToSourceの検証と例外スロー）

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

バインディング式の実行ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TemplateBindingExpression.cs | `src/Avalonia.Base/Data/TemplateBindingExpression.cs` | バインディング式の実行クラス |

**主要処理フロー**:
1. **20-33行目**: コンストラクタ - バインディングパラメータの保持
2. **37-43行目**: StartCore - TemplatedParent監視開始
3. **100-126行目**: PublishValue - 値の取得・変換・配信処理
4. **62-76行目**: WriteValueToSource - TwoWay時のソース書き込み

#### Step 3: 基底クラスを理解する

バインディング式の共通基盤を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BindingBase.cs | `src/Avalonia.Base/Data/BindingBase.cs` | バインディングの基底クラス |
| 3-2 | UntypedBindingExpressionBase.cs | `src/Avalonia.Base/Data/Core/UntypedBindingExpressionBase.cs` | バインディング式の基底クラス |

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

```
TemplateBinding (XAML markup extension)
    │
    └─ CreateInstance()
           │
           └─ TemplateBindingExpression
                  │
                  ├─ StartCore() ─────────┬─ OnTemplatedParentChanged()
                  │                       │         │
                  │                       │         └─ PublishValue()
                  │                       │
                  │                       └─ target.PropertyChanged += handler
                  │
                  ├─ OnTemplatedParentPropertyChanged()
                  │         │
                  │         └─ PublishValue()
                  │
                  ├─ WriteValueToSource() ─── templatedParent.SetCurrentValue()
                  │
                  └─ StopCore() ─── イベントハンドラ解除
```

### データフロー図

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

TemplatedParent ───────────▶ TemplateBindingExpression ───────▶ ターゲットプロパティ
    │                              │
    │ GetValue(Property)           │ Converter?.Convert()
    │                              │ ConvertToTargetType()
    └──────────────────────────────┘
                                   │
                                   ▼ (TwoWay時)
                            WriteValueToSource()
                                   │
                                   ▼
                            TemplatedParent.SetCurrentValue()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TemplateBinding.cs | `src/Avalonia.Base/Data/TemplateBinding.cs` | ソース | マークアップ拡張クラス |
| TemplateBindingExpression.cs | `src/Avalonia.Base/Data/TemplateBindingExpression.cs` | ソース | バインディング式実行クラス |
| BindingBase.cs | `src/Avalonia.Base/Data/BindingBase.cs` | ソース | バインディング基底クラス |
| BindingMode.cs | `src/Avalonia.Base/Data/BindingMode.cs` | ソース | バインディングモード列挙型 |
| IValueConverter.cs | `src/Avalonia.Base/Data/Converters/IValueConverter.cs` | ソース | 値変換インターフェース |
| StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | ソース | TemplatedParentプロパティ定義 |
