# 機能設計書 11-TreeView

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるTreeViewコントロールの機能設計を記述する。TreeViewは階層データを視覚的に表示・操作するためのUIコントロールである。

### 本機能の処理概要

TreeViewは、階層構造を持つデータをツリー形式で表示し、ユーザーがノードの展開・折りたたみ、選択操作を行えるようにするコントロールである。

**業務上の目的・背景**：ファイルエクスプローラー、組織図、カテゴリ一覧など、階層構造を持つデータを直感的に表示・操作するニーズは多くのアプリケーションに存在する。TreeViewはこれらのユースケースに対応し、ユーザーが大量の階層データを効率的にナビゲートできるようにする。

**機能の利用シーン**：
- ファイルシステムの階層表示
- 組織構造やカテゴリの表示
- 設定画面でのオプションツリー
- XMLやJSONなど階層データの可視化

**主要な処理内容**：
1. 階層データのバインディングと表示
2. ノードの展開・折りたたみ状態の管理
3. 単一選択・複数選択モードのサポート
4. キーボードナビゲーション（上下左右キー、Enter、+/-キー）
5. 選択アイテムの自動スクロール
6. 仮想化による大量データの効率的表示

**関連システム・外部連携**：ItemsControlを継承し、データバインディングシステムと連携。ICustomKeyboardNavigationインターフェースを実装してカスタムキーボードナビゲーションを提供。

**権限による制御**：特になし。UIコントロールとして汎用的に使用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 61 | TreeView | 主画面 | TreeViewコントロールのデモ。階層データ表示、ノード展開・折りたたみ |

## 機能種別

データ表示 / 階層ナビゲーション / 選択管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ItemsSource | IEnumerable | No | 表示するデータソース | - |
| SelectedItem | object | No | 選択されているアイテム | - |
| SelectedItems | IList | No | 複数選択時の選択アイテムリスト | 固定サイズ・読み取り専用コレクションは不可 |
| SelectionMode | SelectionMode | No | 選択モード（Single/Multiple/Toggle等） | - |
| AutoScrollToSelectedItem | bool | No | 選択アイテムへの自動スクロール | デフォルト: false |

### 入力データソース

- ItemsSourceプロパティへのデータバインディング
- XAMLでの直接アイテム定義
- コードビハインドでのItems追加

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SelectedItem | object | 現在選択されているアイテム |
| SelectedItems | IList | 選択されているアイテムのコレクション |

### 出力先

- SelectionChangedイベントによる選択変更通知
- プロパティバインディングによるViewModel更新

## 処理フロー

### 処理シーケンス

```
1. データソースバインド
   └─ ItemsSourceにコレクションを設定
2. コンテナ生成
   └─ 各アイテムに対してTreeViewItemを生成
3. 階層構造の構築
   └─ TreeViewItemが子アイテムのコンテナを管理
4. ユーザー操作
   └─ 展開/折りたたみ、選択操作を処理
5. 選択状態の更新
   └─ SelectedItem/SelectedItemsを更新し、イベント発火
```

### フローチャート

```mermaid
flowchart TD
    A[TreeViewにアイテム設定] --> B[TreeViewItem生成]
    B --> C{ユーザー操作}
    C -->|クリック| D[選択処理]
    C -->|ダブルクリック| E[展開/折りたたみ]
    C -->|キー入力| F[キーボードナビゲーション]
    D --> G[SelectedItems更新]
    E --> H[IsExpanded変更]
    F --> I{キー種別}
    I -->|上下| J[フォーカス移動]
    I -->|左右| K[展開/折りたたみ]
    I -->|Enter| L[展開トグル]
    G --> M[SelectionChangedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 単一選択モード | SelectionMode=Singleの場合、1つのアイテムのみ選択可能 | 単一選択モード時 |
| BR-02 | 複数選択モード | SelectionMode=Multipleの場合、Ctrl/Shiftキーで複数選択 | 複数選択モード時 |
| BR-03 | 範囲選択 | Shiftキーで範囲選択時、表示されているアイテムのみ選択 | 複数選択+Shift |
| BR-04 | 自動スクロール | AutoScrollToSelectedItemがtrueの場合、実現済みアイテムのみスクロール | 選択変更時 |

### 計算ロジック

特になし

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

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

該当なし（UIコントロール）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | NotSupportedException | SelectedItemsに固定サイズ/読み取り専用コレクションを設定 | 可変リストを使用 |
| - | InvalidOperationException | TreeViewItem操作時にTreeViewが見つからない | TreeViewの子として配置 |

### リトライ仕様

該当なし

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

該当なし（UIコントロール）

## パフォーマンス要件

- 仮想化対応：VirtualizingStackPanelと組み合わせて大量データの効率的表示が可能
- 遅延展開：展開されていないノードの子アイテムは生成されない

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

特になし（UIコントロールとして汎用的に使用可能）

## 備考

- WPFのTreeViewとの互換性を意識した設計
- 仮想化使用時は、選択済みだが未実現のアイテムへのスクロールは制限される

---

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

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

### 推奨読解順序

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

TreeViewの選択管理とアイテム管理の基盤となるインターフェースとクラスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SelectionMode.cs | `src/Avalonia.Controls/Selection/SelectionMode.cs` | 選択モードの列挙型定義（Single, Multiple, Toggle等） |
| 1-2 | ICustomKeyboardNavigation.cs | `src/Avalonia.Base/Input/ICustomKeyboardNavigation.cs` | カスタムキーボードナビゲーションのインターフェース |

**読解のコツ**: SelectionModeはフラグ列挙型であり、複数の選択動作を組み合わせて使用できる。

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

TreeViewクラス自体がエントリーポイントとなる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | TreeView.cs | `src/Avalonia.Controls/TreeView.cs` | TreeViewの主要実装。選択管理、キーボードナビゲーション |

**主要処理フロー**:
1. **27-55行目**: プロパティ定義（SelectedItem, SelectedItems, SelectionMode等）
2. **64-68行目**: 静的コンストラクタで選択変更イベントハンドラを登録
3. **166-183行目**: ExpandSubTree - サブツリー全体を展開
4. **212-230行目**: SelectAll - 表示されているすべてのアイテムを選択
5. **496-514行目**: GetNext - キーボードナビゲーションの次要素取得
6. **564-599行目**: OnKeyDown - キー入力処理

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

TreeViewの各ノードを表すコントロール。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TreeViewItem.cs | `src/Avalonia.Controls/TreeViewItem.cs` | 個々のツリーノードの実装 |

**主要処理フロー**:
- **30-33行目**: IsExpandedプロパティ定義（TwoWayバインディング）
- **94-98行目**: IsExpandedプロパティのゲッター/セッター
- **209-309行目**: OnKeyDown - キー入力による展開/折りたたみ

#### Step 4: 選択管理を理解する

複数選択、範囲選択の実装詳細。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TreeView.cs | `src/Avalonia.Controls/TreeView.cs` | UpdateSelectionFromContainer, GetItemsInRange |

**主要処理フロー**:
- **701-768行目**: UpdateSelectionFromContainer - コンテナからの選択更新
- **822-877行目**: GetItemsInRange - 範囲選択時のアイテム取得

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

```
TreeView
    │
    ├─ ItemsControl (基底クラス)
    │      └─ アイテムコンテナ管理
    │
    ├─ TreeViewItem (子コンテナ)
    │      ├─ IsExpanded管理
    │      ├─ IsSelected管理
    │      └─ OnKeyDown (展開/折りたたみ)
    │
    ├─ ICustomKeyboardNavigation
    │      └─ GetNext (ナビゲーション)
    │
    └─ SelectionChanged イベント
           └─ 選択変更通知
```

### データフロー図

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

ItemsSource ───▶ TreeView.Items ───▶ TreeViewItem群
                      │
ユーザー操作 ───▶ UpdateSelectionFromContainer ───▶ SelectedItem/SelectedItems
                      │
キー入力 ───▶ OnKeyDown ───▶ フォーカス移動/展開状態変更
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TreeView.cs | `src/Avalonia.Controls/TreeView.cs` | ソース | TreeViewコントロール本体 |
| TreeViewItem.cs | `src/Avalonia.Controls/TreeViewItem.cs` | ソース | ツリーノードコントロール |
| TreeViewAutomationPeer.cs | `src/Avalonia.Controls/Automation/Peers/TreeViewAutomationPeer.cs` | ソース | UIオートメーション対応 |
| TreeViewItemAutomationPeer.cs | `src/Avalonia.Controls/Automation/Peers/TreeViewItemAutomationPeer.cs` | ソース | TreeViewItemのオートメーション |
| ItemsControl.cs | `src/Avalonia.Controls/ItemsControl.cs` | ソース | 基底クラス（アイテム管理） |
| SelectingItemsControl.cs | `src/Avalonia.Controls/Primitives/SelectingItemsControl.cs` | ソース | 選択機能の基底 |
