# 機能設計書 60-MultiBinding

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるマルチバインディング（MultiBinding）機能の設計仕様を定義する。MultiBindingは、複数のソースバインディングから値を収集し、IMultiValueConverterを通じて単一の値に結合する機能を提供する。

### 本機能の処理概要

MultiBindingは、複数の子バインディングを持ち、それぞれの値を収集して集約する機能を提供する。IMultiValueConverterにより複数の値を単一の値に変換し、ターゲットプロパティに設定する。これにより、複数のデータソースに基づく複雑な表示ロジックを実現できる。

**業務上の目的・背景**：単一のプロパティで複数のデータソースを組み合わせた表示が必要な場合がある。例えば、姓と名を結合したフルネーム表示、複数の条件に基づく可視性制御、複数の数値の合計表示などである。MultiBindingにより、これらの要件を宣言的に実現できる。

**機能の利用シーン**：
- 姓と名を結合したフルネーム表示
- 複数のブール値のAND/OR演算による可視性制御
- 複数の数値の演算結果表示
- 複数のプロパティに基づくスタイル決定
- 国際化対応の複合文字列フォーマット

**主要な処理内容**：
1. 複数の子バインディング（Bindings）の管理
2. IMultiValueConverterによる値の結合
3. StringFormatによる文字列フォーマット
4. FallbackValue/TargetNullValueの適用
5. MultiBindingExpressionの生成と値の同期

**関連システム・外部連携**：BindingBase、IMultiValueConverter、MultiBindingExpression、StringFormatMultiValueConverterと連携。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | MultiBindingは特定の画面に限定されず、アプリケーション全体で使用可能 |

## 機能種別

データバインディング / 複数値結合 / 値変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Bindings | IList<BindingBase> | Yes | 子バインディングのコレクション | 空でも可 |
| Converter | IMultiValueConverter? | No | 複数値→単一値コンバーター | null許容 |
| ConverterParameter | object? | No | コンバーターパラメーター | null許容 |
| ConverterCulture | CultureInfo? | No | コンバーターカルチャ | null許容 |
| FallbackValue | object | No | エラー時のフォールバック値 | UnsetValueデフォルト |
| TargetNullValue | object | No | 結果がnull時の値 | UnsetValueデフォルト |
| Mode | BindingMode | No | バインディングモード（デフォルト: OneWay） | 有効な列挙値 |
| Priority | BindingPriority | No | バインディング優先度 | 有効な列挙値 |
| RelativeSource | RelativeSource? | No | 相対ソース（子バインディングへ伝播） | null許容 |
| StringFormat | string? | No | 文字列フォーマット | null許容 |

### 入力データソース

- XAML {MultiBinding}マークアップ拡張
- 各子バインディングのソースプロパティ

## 出力仕様

### 出力データ

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

### 出力先

- ターゲットプロパティ（コンバーター結果値）

## 処理フロー

### 処理シーケンス

```
1. MultiBinding定義解析
   └─ Bindingsコレクション構築
2. CreateInstance呼び出し
   └─ ターゲットへのバインド時
3. コンバーター準備
   └─ StringFormat指定時はStringFormatMultiValueConverter使用
4. MultiBindingExpression生成
   └─ 子バインディングをラップ
5. 各子バインディングの値監視
   └─ いずれかの値が変更されたら再評価
6. Converter.Convert呼び出し
   └─ 複数値を単一値に変換
7. ターゲットプロパティ更新
   └─ 変換結果を設定
```

### フローチャート

```mermaid
flowchart TD
    A[MultiBinding定義] --> B[Bindings追加]
    B --> C[CreateInstance]
    C --> D{StringFormat指定?}
    D -->|Yes| E[StringFormatMultiValueConverter作成]
    D -->|No| F[Converter使用]
    E --> G[MultiBindingExpression生成]
    F --> G
    G --> H[子バインディング購読開始]
    H --> I{いずれかの値変更?}
    I -->|Yes| J[全子バインディング値収集]
    J --> K[Converter.Convert呼び出し]
    K --> L{変換成功?}
    L -->|Yes| M{結果null?}
    M -->|Yes| N[TargetNullValue適用]
    M -->|No| O[結果値を設定]
    L -->|No| P[FallbackValue適用]
    N --> O
    P --> O
    I -->|No| I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-60-01 | OneWayデフォルト | MultiBindingはデフォルトでOneWayモード | Mode未指定時 |
| BR-60-02 | StringFormat優先 | StringFormat指定時はConverterをラップ | StringFormat != null |
| BR-60-03 | コンバーター必須 | 複数値の結合にはConverterが必要 | Bindings.Count > 1 |
| BR-60-04 | 値更新トリガー | いずれかの子バインディング値が変わったら再評価 | 値変更時 |

### 計算ロジック

**StringFormatMultiValueConverter**：
- Converterがある場合は先に適用
- String.Formatで整形
- ターゲット型がstring/objectの場合のみ適用

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 変換エラー | IMultiValueConverter.Convert失敗 | FallbackValue使用 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 子バインディングの値変更ごとに再評価が発生するため、大量のバインディングには注意

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

特になし

## 備考

- TwoWayモードはサポートが限定的（IMultiValueConverter.ConvertBackが必要）
- Bindingsは[Content]属性でXAML子要素として定義可能

---

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

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

### 推奨読解順序

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

MultiBindingで使用される型定義を先に把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IMultiValueConverter.cs | `src/Avalonia.Base/Data/Converters/IMultiValueConverter.cs` | Convert/ConvertBackメソッド |
| 1-2 | MultiBinding.cs | `src/Avalonia.Base/Data/MultiBinding.cs` | クラス定義、プロパティ |

**読解のコツ**: IMultiValueConverterはIReadOnlyList<object?>を受け取り単一値を返す。ConvertBackは複数値を返す（TwoWay用）。

#### Step 2: MultiBindingクラスを理解する

メインクラスの構造とプロパティを把握する。

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

**主要処理フロー**:
1. **18-20行目**: Bindingsプロパティ（[Content]属性付き）
2. **25行目**: Converterプロパティ
3. **45-50行目**: FallbackValue/TargetNullValueプロパティ
4. **55行目**: Modeプロパティ（デフォルトOneWay）
5. **78-110行目**: CreateInstance/InstanceCore

#### Step 3: CreateInstanceを理解する

MultiBindingExpression生成ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | MultiBinding.cs | `src/Avalonia.Base/Data/MultiBinding.cs` | InstanceCoreメソッド |

**主要処理フロー**:
- **86-110行目**: InstanceCore実装
  - **90-91行目**: ターゲット型取得
  - **96-99行目**: StringFormat指定時のコンバーターラップ
  - **102-109行目**: MultiBindingExpression生成

#### Step 4: StringFormatコンバーターを理解する

StringFormat適用ロジックを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | StringFormatMultiValueConverter.cs | `src/Avalonia.Base/Data/Converters/StringFormatMultiValueConverter.cs` | ラップコンバーター |

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

```
<MultiBinding Converter="{...}">
    <Binding Path="FirstName"/>
    <Binding Path="LastName"/>
</MultiBinding>
    │
    └─ MultiBinding インスタンス生成
           │
           └─ CreateInstance (ターゲットにバインド時)
                  │
                  ├─ ターゲット型判定
                  │
                  ├─ StringFormat処理
                  │      └─ StringFormatMultiValueConverter作成
                  │
                  └─ new MultiBindingExpression(...)
                         │
                         ├─ 子バインディング生成・購読
                         ├─ 値収集
                         ├─ IMultiValueConverter.Convert
                         └─ ターゲットプロパティ更新
```

### データフロー図

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

Binding1の値 ───────┐
                    ├───▶ IMultiValueConverter ───▶ 単一値
Binding2の値 ───────┤           │
                    │           ├─ Convert
BindingNの値 ───────┘           └─ StringFormat適用
                                        │
                                        └─▶ ターゲットプロパティ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MultiBinding.cs | `src/Avalonia.Base/Data/MultiBinding.cs` | ソース | メインクラス |
| BindingBase.cs | `src/Avalonia.Base/Data/BindingBase.cs` | ソース | バインディング基底 |
| IMultiValueConverter.cs | `src/Avalonia.Base/Data/Converters/IMultiValueConverter.cs` | ソース | マルチ値コンバーター |
| MultiBindingExpression.cs | `src/Avalonia.Base/Data/Core/MultiBindingExpression.cs` | ソース | マルチバインディング式 |
| StringFormatMultiValueConverter.cs | `src/Avalonia.Base/Data/Converters/StringFormatMultiValueConverter.cs` | ソース | StringFormatラッパー |
| FuncMultiValueConverter.cs | `src/Avalonia.Base/Data/Converters/FuncMultiValueConverter.cs` | ソース | 関数ベースコンバーター |
| BindingMode.cs | `src/Avalonia.Base/Data/BindingMode.cs` | ソース | バインディングモード |
| RelativeSource.cs | `src/Avalonia.Base/Data/RelativeSource.cs` | ソース | 相対ソース |
