# 機能設計書 58-Binding

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるデータバインディング（Binding）機能の設計仕様を定義する。BindingはReflectionBindingを中心とした、プロパティ間の双方向データ連携を実現する中核機能である。

### 本機能の処理概要

Avaloniaのデータバインディングシステムは、ソースオブジェクトのプロパティとターゲット要素のプロパティを連携させる機能を提供する。ReflectionBindingはリフレクションを使用してプロパティにアクセスし、パス式による柔軟なバインディングをサポートする。

**業務上の目的・背景**：MVVMパターンにおいて、ViewとViewModelの分離を実現するためにデータバインディングは不可欠である。バインディングにより、UIの状態とビジネスロジックの状態を同期させ、宣言的なUI定義とテスト可能なビジネスロジックの分離を実現する。

**機能の利用シーン**：
- TextBoxのTextプロパティとViewModelのプロパティの双方向バインディング
- リストコントロールのItemsSourceへのコレクションバインディング
- コンバーターを使用した値変換（数値↔文字列、bool↔Visibility等）
- 複数バインディングの結合（MultiBinding）
- 相対ソースによる祖先要素へのバインディング

**主要な処理内容**：
1. パス式の解析とExpressionNodeツリー構築
2. ソースオブジェクトの決定（DataContext、ElementName、RelativeSource）
3. バインディングモード（OneWay、TwoWay、OneWayToSource、OneTime）の適用
4. 値コンバーターによる変換処理
5. バリデーションエラーの伝播
6. 更新トリガー（PropertyChanged、LostFocus）の制御

**関連システム・外部連携**：AvaloniaProperty、INotifyPropertyChanged、IValueConverter、BindingExpressionと連携してバインディングを実現。

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインウィンドウ | 主機能 | ウィンドウプロパティのデータバインディング |
| 26 | Data Validation | 主機能 | データバリデーションのデモ。入力検証機能 |
| 109 | メインウィンドウ | 主機能 | データバインディングのデモ |

## 機能種別

データバインディング / プロパティ同期 / 値変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string | No | バインディングパス（例: "Property.SubProperty"） | 空文字列許容 |
| Mode | BindingMode | No | バインディングモード（Default/OneWay/TwoWay等） | 有効な列挙値 |
| Converter | IValueConverter? | No | 値コンバーター | null許容 |
| ConverterParameter | object? | No | コンバーターパラメーター | null許容 |
| Source | object? | No | バインディングソース | null許容 |
| ElementName | string? | No | ソース要素名 | null許容 |
| RelativeSource | RelativeSource? | No | 相対ソース定義 | null許容 |
| FallbackValue | object? | No | エラー時のフォールバック値 | null許容 |
| TargetNullValue | object? | No | ソースがnull時の値 | null許容 |
| StringFormat | string? | No | 文字列フォーマット | null許容 |
| UpdateSourceTrigger | UpdateSourceTrigger | No | 更新トリガー | 有効な列挙値 |
| Priority | BindingPriority | No | バインディング優先度 | 有効な列挙値 |
| Delay | int | No | 更新遅延（ミリ秒） | 非負整数 |

### 入力データソース

- XAML {Binding}マークアップ拡張
- コードビハインドでのバインディング設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| BindingExpression | BindingExpression | アクティブなバインディング式 |

### 出力先

- ターゲットプロパティ（バインディング結果値）
- ソースプロパティ（TwoWay/OneWayToSource時）

## 処理フロー

### 処理シーケンス

```
1. バインディング定義解析
   └─ ReflectionBinding/CompiledBindingインスタンス作成
2. パス式解析
   └─ BindingExpressionGrammarでASTを構築
3. ExpressionNode生成
   └─ ExpressionNodeFactory.CreateFromAstでノードツリー作成
4. ソース決定
   └─ DataContext/ElementName/RelativeSource/Source評価
5. BindingExpression生成
   └─ CreateInstanceでアクティブな式を作成
6. 値の購読開始
   └─ ソースプロパティの変更を監視
7. 値変換・適用
   └─ コンバーター適用後、ターゲットに設定
```

### フローチャート

```mermaid
flowchart TD
    A[バインディング定義] --> B[パス式解析]
    B --> C{パス空?}
    C -->|Yes| D[DataContextソースのみ]
    C -->|No| E[ExpressionNode構築]
    E --> F{Source指定?}
    F -->|Yes| G[指定Sourceを使用]
    F -->|No| H{ElementName?}
    H -->|Yes| I[NamedElementNode追加]
    H -->|No| J{RelativeSource?}
    J -->|Yes| K[RelativeSourceNode追加]
    J -->|No| L[DataContextNode追加]
    D --> M[BindingExpression作成]
    G --> M
    I --> M
    K --> M
    L --> M
    M --> N[ソース購読開始]
    N --> O{Mode?}
    O -->|OneWay| P[ソース→ターゲット監視]
    O -->|TwoWay| Q[双方向監視]
    O -->|OneWayToSource| R[ターゲット→ソース監視]
    O -->|OneTime| S[初回のみ転送]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-58-01 | デフォルトモード | Mode=Defaultの場合、ターゲットプロパティのDefaultBindingModeを使用 | Mode未指定時 |
| BR-58-02 | DataContext継承 | Source未指定でパスがルートでない場合、DataContextを使用 | ソース未指定時 |
| BR-58-03 | 変換エラー時フォールバック | コンバーターエラー時はFallbackValueを使用 | 変換失敗時 |
| BR-58-04 | null時TargetNullValue | ソース値がnullの場合TargetNullValueを使用 | ソースnull時 |
| BR-58-05 | UpdateSourceTrigger | PropertyChanged=即時、LostFocus=フォーカス喪失時に更新 | TwoWay/OneWayToSource時 |

### 計算ロジック

特になし

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

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

該当なし（UIフレームワークのためデータベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | BindingChainException | パス解決失敗 | FallbackValue使用、エラー通知 |
| - | DataValidationException | バリデーションエラー | エラー状態をターゲットに伝播 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- バインディング評価は即座に行われる必要がある
- リフレクションによるオーバーヘッドを考慮（CompiledBinding推奨）

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

- リフレクションによるプライベートメンバーへのアクセスは制限される
- 信頼されていないパス式の評価には注意が必要

## 備考

- ReflectionBindingはトリミング/AOTとの互換性に注意が必要
- パフォーマンスが重要な場合はCompiledBindingを使用

---

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

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

### 推奨読解順序

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

バインディングシステムで使用される型定義を先に把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | BindingBase.cs | `src/Avalonia.Base/Data/BindingBase.cs` | バインディング基底クラス、CreateInstance抽象メソッド |
| 1-2 | BindingMode.cs | `src/Avalonia.Base/Data/BindingMode.cs` | Default/OneWay/TwoWay/OneWayToSource/OneTime列挙型 |
| 1-3 | BindingPriority.cs | `src/Avalonia.Base/Data/BindingPriority.cs` | バインディング優先度列挙型 |
| 1-4 | UpdateSourceTrigger.cs | `src/Avalonia.Base/Data/UpdateSourceTrigger.cs` | Default/PropertyChanged/LostFocus列挙型 |

**読解のコツ**: BindingBaseはすべてのバインディングタイプの基底。CreateInstanceがBindingExpressionを生成する。

#### Step 2: ReflectionBindingを理解する

リフレクションベースバインディングの実装を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ReflectionBinding.cs | `src/Avalonia.Base/Data/ReflectionBinding.cs` | プロパティ定義、CreateInstance実装 |

**主要処理フロー**:
1. **26-37行目**: コンストラクタ、Pathプロパティ初期化
2. **130-185行目**: CreateInstance - ExpressionNode構築、BindingExpression生成
3. **140-149行目**: パス解析、BindingExpressionGrammar.ParseToPooledList
4. **155-159行目**: ソースノード追加ロジック
5. **169-184行目**: BindingExpression生成

#### Step 3: パス解析を理解する

バインディングパスの解析ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BindingExpressionGrammar.cs | `src/Avalonia.Base/Data/Core/Parsers/BindingExpressionGrammar.cs` | パス式文法定義 |
| 3-2 | ExpressionNodeFactory.cs | `src/Avalonia.Base/Data/Core/ExpressionNodes/ExpressionNodeFactory.cs` | ASTからノード生成 |

#### Step 4: BindingExpressionを理解する

アクティブなバインディング式の動作を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BindingExpression.cs | `src/Avalonia.Base/Data/Core/BindingExpression.cs` | 値の購読・更新ロジック |
| 4-2 | BindingExpressionBase.cs | `src/Avalonia.Base/Data/BindingExpressionBase.cs` | バインディング式基底 |

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

```
{Binding Path=...} (XAML)
    │
    └─ ReflectionBinding インスタンス生成
           │
           └─ CreateInstance (ターゲットにバインド時)
                  │
                  ├─ BindingExpressionGrammar.ParseToPooledList
                  │      └─ パス式をASTに解析
                  │
                  ├─ ExpressionNodeFactory.CreateFromAst
                  │      └─ ExpressionNodeツリー構築
                  │
                  ├─ CreateSourceNode
                  │      ├─ NamedElementNode (ElementName指定時)
                  │      ├─ RelativeSourceNode (RelativeSource指定時)
                  │      └─ DataContextNode (デフォルト)
                  │
                  └─ new BindingExpression(...)
                         │
                         ├─ ソースプロパティ購読
                         ├─ 値変換 (Converter)
                         └─ ターゲットプロパティ更新
```

### データフロー図

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

ソースプロパティ ───▶ BindingExpression ───▶ ターゲットプロパティ
(INotifyPropertyChanged)   │                   (AvaloniaProperty)
                           ├─ ExpressionNodeチェーン評価
                           ├─ IValueConverter適用
                           └─ StringFormat適用

ターゲットプロパティ ───▶ BindingExpression ───▶ ソースプロパティ
(TwoWay/OneWayToSource)    │                   (セッター呼び出し)
                           └─ IValueConverter.ConvertBack
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BindingBase.cs | `src/Avalonia.Base/Data/BindingBase.cs` | ソース | バインディング基底クラス |
| ReflectionBinding.cs | `src/Avalonia.Base/Data/ReflectionBinding.cs` | ソース | リフレクションバインディング |
| BindingExpression.cs | `src/Avalonia.Base/Data/Core/BindingExpression.cs` | ソース | バインディング式 |
| BindingExpressionBase.cs | `src/Avalonia.Base/Data/BindingExpressionBase.cs` | ソース | バインディング式基底 |
| BindingMode.cs | `src/Avalonia.Base/Data/BindingMode.cs` | ソース | バインディングモード |
| RelativeSource.cs | `src/Avalonia.Base/Data/RelativeSource.cs` | ソース | 相対ソース定義 |
| IValueConverter.cs | `src/Avalonia.Base/Data/Converters/IValueConverter.cs` | ソース | 値コンバーター |
| BindingExpressionGrammar.cs | `src/Avalonia.Base/Data/Core/Parsers/BindingExpressionGrammar.cs` | ソース | パス式文法 |
| ExpressionNodeFactory.cs | `src/Avalonia.Base/Data/Core/ExpressionNodes/ExpressionNodeFactory.cs` | ソース | ノード生成 |
