# 画面設計書 8-AutoCompleteBox

## 概要

本ドキュメントは、ControlCatalogアプリケーションのAutoCompleteBoxページ（AutoCompleteBoxPage）の画面設計を定義します。

### 本画面の処理概要

このAutoCompleteBoxページは、Avalonia UIのAutoCompleteBoxコントロールをデモンストレーションするページです。様々な設定（MinimumPrefixLength、MinimumPopulateDelay、MaxDropDownHeight等）やカスタム動作（非同期ポピュレート、マルチバインディング、カスタムオートコンプリート）を示しています。

**業務上の目的・背景**：本画面は、Avalonia UIフレームワークのAutoCompleteBoxコントロールの実装方法を示すデモです。AutoCompleteBoxは、ユーザーが入力を開始すると候補リストを表示し、選択できるコントロールです。検索機能、住所入力、タグ入力など、様々な場面で活用できます。開発者が各種オートコンプリートパターンを実装する際の参考となります。

**画面へのアクセス方法**：MainViewのHamburgerMenuから「AutoCompleteBox」タブを選択してアクセスします。MainView.xamlの31-33行目で定義されています。

**主要な操作・処理内容**：
1. 各種設定のAutoCompleteBoxにテキストを入力して候補を表示
2. MinimumPrefixLengthで候補表示に必要な最小入力文字数を確認
3. MinimumPopulateDelayで候補表示の遅延を確認
4. MaxDropDownHeightでドロップダウンの最大高さを確認
5. AsyncPopulateで非同期候補取得（1.5秒遅延）を確認
6. CustomAutocompleteで文章単語補完を確認

**画面遷移**：
- 遷移元：MainView（HamburgerMenu）
- 遷移先：なし（コンテンツページ）

**権限による表示制御**：本アプリケーションはデモ用のため、特別な権限制御は実装されていません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 28 | AutoCompleteBox | 主機能 | オートコンプリート入力ボックスのデモ。入力候補の表示と選択 |

## 画面種別

デモページ / サンプル

## URL/ルーティング

デスクトップアプリケーションのため、URLルーティングは該当なし。HamburgerMenuのTabItemとしてアクセス。

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 | バインディング |
|--------|----------|----------|------|---------------|
| MinimumPrefixLength=0 | 入力 | string | 0文字から候補表示 | ItemsSource=States |
| MinimumPrefixLength=1 | 入力 | string | 1文字から候補表示 | ItemsSource=States |
| MinimumPrefixLength=3 | 入力 | string | 3文字から候補表示 | ItemsSource=States |
| MinimumPopulateDelay | 入力 | string | 1秒遅延で候補表示 | ItemsSource=States |
| MaxDropDownHeight | 入力 | string | ドロップダウン高さ60 | ItemsSource=States |
| PlaceholderText | 入力 | string | プレースホルダー表示 | ItemsSource=States |
| ValueMemberBinding | 入力 | string | Capital（州都）で検索 | ValueMemberBinding |
| Multi-Binding | 入力 | string | Name (Abbreviation)形式 | MultiBinding |
| Async Populate | 入力 | string | 非同期候補取得 | AsyncPopulator |
| Custom Autocomplete | 入力 | string | 文章単語補完 | TextFilter, TextSelector |

## 表示項目

| 項目名 | 表示位置 | データ型 | 説明 |
|--------|----------|----------|------|
| h2テキスト | 上部 | TextBlock | 説明文 |
| UniformGrid | メイン | UniformGrid | 2列×複数行 |
| AutoCompleteBox群 | グリッド内 | AutoCompleteBox | 各種設定のデモ |
| ValidationErrors | 下部 | AutoCompleteBox | バリデーションエラー表示 |

## イベント仕様

### 1-PopulateAsync（非同期候補取得）

**トリガー**: Async PopulateのAutoCompleteBoxに入力

**処理内容**:
1. 1.5秒の遅延（Task.Delay）
2. StatesからName/Capitalで部分一致検索
3. 結果リストを返却

**コード参照**: AutoCompleteBoxPage.xaml.cs 129-136行目

### 2-LastWordContains（カスタムフィルター）

**トリガー**: Custom AutocompleteのAutoCompleteBoxに入力

**処理内容**:
1. 入力テキストをスペースで分割
2. 定義済み文章リスト（Sentences）の各単語と照合
3. 最後の単語が候補の先頭と一致するかチェック

**コード参照**: AutoCompleteBoxPage.xaml.cs 138-163行目

### 3-AppendWord（カスタムテキストセレクター）

**トリガー**: Custom Autocompleteで候補を選択

**処理内容**:
1. 入力テキストをスペースで分割
2. 最後の単語を選択した候補で置換
3. 結合して返却

**コード参照**: AutoCompleteBoxPage.xaml.cs 164-176行目

## データベース更新仕様

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

本画面はデータベースを使用しません。

## メッセージ仕様

| メッセージID | 種別 | 内容 | 表示条件 |
|-------------|------|------|----------|
| N/A | - | - | - |

本画面では特別なメッセージ表示は行われません。

## 例外処理

| 例外種別 | 発生条件 | 対処 |
|----------|----------|------|
| CancellationToken | 非同期処理キャンセル | 処理中止 |

## 備考

- 50州のStateData（Name、Abbreviation、Capital）を候補として使用
- 4つの定義済み文章（Hello world、No this is Patrick等）をカスタムオートコンプリートで使用
- PlaceholderForeground="Green"でプレースホルダーの色をカスタマイズ可能
- DataValidationErrors.Errorでバリデーションエラーを表示
- FilterMode="Contains"で部分一致、"None"でカスタムフィルターを使用

---

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

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

### 推奨読解順序

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

まず、候補データの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | StateData.cs | `samples/ControlCatalog/Models/StateData.cs` | Name、Abbreviation、Capitalプロパティ |
| 1-2 | AutoCompleteBoxPage.xaml.cs | `samples/ControlCatalog/Pages/AutoCompleteBoxPage.xaml.cs` | BuildAllStates()、BuildAllSentences() |

**読解のコツ**: StateDataは米国50州の情報を持つシンプルなデータクラスです。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AutoCompleteBoxPage.xaml | `samples/ControlCatalog/Pages/AutoCompleteBoxPage.xaml` | UniformGridの各AutoCompleteBox設定 |
| 2-2 | AutoCompleteBoxPage.xaml.cs | `samples/ControlCatalog/Pages/AutoCompleteBoxPage.xaml.cs` | コンストラクタでのItemsSource設定 |

**主要処理フロー**:
1. **16-71行目（C#）**: BuildAllStates()で50州データ生成
2. **74-85行目（C#）**: BuildAllSentences()で文章データ生成
3. **88-115行目（C#）**: コンストラクタでItemsSource設定、バインディング設定

#### Step 3: カスタムオートコンプリートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AutoCompleteBoxPage.xaml.cs | `samples/ControlCatalog/Pages/AutoCompleteBoxPage.xaml.cs` | PopulateAsync、LastWordContains、AppendWord |

**主要処理フロー**:
- **110行目**: AsyncBox.AsyncPopulator = PopulateAsync
- **112-114行目**: CustomAutocompleteBox設定
- **129-136行目**: PopulateAsync実装（1.5秒遅延）
- **138-163行目**: LastWordContainsフィルター
- **164-176行目**: AppendWordセレクター

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

```
AutoCompleteBoxPage（UserControl）
    │
    ├─ コンストラクタ
    │      ├─ BuildAllStates() → States[] (50州)
    │      ├─ BuildAllSentences() → Sentences[] (4文章)
    │      │
    │      ├─ GetAllAutoCompleteBox()
    │      │      └─ 各AutoCompleteBox.ItemsSource = States
    │      │
    │      ├─ MultiBinding設定
    │      │      └─ FuncMultiValueConverter
    │      │             └─ "{0} ({1})" フォーマット
    │      │
    │      ├─ AsyncBox設定
    │      │      └─ AsyncPopulator = PopulateAsync
    │      │
    │      └─ CustomAutocompleteBox設定
    │             ├─ ItemsSource = Sentences単語一覧
    │             ├─ TextFilter = LastWordContains
    │             └─ TextSelector = AppendWord
    │
    ├─ PopulateAsync(searchText, cancellationToken)
    │      ├─ Task.Delay(1.5秒)
    │      └─ States.Where(Name/Capital Contains searchText)
    │
    ├─ LastWordContains(searchText, item)
    │      └─ 最後の単語が候補に一致するか
    │
    └─ AppendWord(text, item)
           └─ 最後の単語を置換
```

### データフロー図

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

ユーザー入力 ───────▶ AutoCompleteBox ────────▶ 候補表示
  │                        │
  ├─ 通常入力 ──────▶ ItemsSource検索 ────▶ ドロップダウン
  │                        │
  ├─ 非同期入力 ────▶ PopulateAsync ──────▶ 遅延後候補表示
  │                        │      └─ 1.5秒待機
  │                        │
  └─ カスタム入力 ──▶ LastWordContains ───▶ 単語候補表示
                           │
                           └─ AppendWord ───▶ 単語置換
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AutoCompleteBoxPage.xaml | `samples/ControlCatalog/Pages/AutoCompleteBoxPage.xaml` | XAML | AutoCompleteBoxデモのUI定義 |
| AutoCompleteBoxPage.xaml.cs | `samples/ControlCatalog/Pages/AutoCompleteBoxPage.xaml.cs` | ソース | 候補データ生成、カスタムロジック |
| StateData.cs | `samples/ControlCatalog/Models/StateData.cs` | ソース | 州データモデル |
