# 画面設計書 38-ListBox

## 概要

本ドキュメントは、ControlCatalogサンプルアプリケーションのListBoxページに関する画面設計書です。ListBoxコントロールの各種機能と使用方法をデモンストレーションするページです。

### 本画面の処理概要

ListBoxページは、AvaloniaフレームワークにおけるListBoxコントロールの機能を確認するためのデモ画面です。大量のアイテム（10,000件）の表示、仮想化によるパフォーマンス最適化、各種選択モード、スタイルセレクター（nth-child、nth-last-child）の動作を学習・検証できます。

**業務上の目的・背景**：リスト形式のデータ表示は、多くのアプリケーションで必要とされる基本機能です。ListBoxは、アイテムの選択、スクロール、仮想化による大量データの効率的な表示など、重要な機能を提供します。本画面は開発者がListBoxの各種オプション（選択モード、自動スクロール、ラップ選択）と、CSSライクなセレクター機能を理解するために提供されています。

**画面へのアクセス方法**：ControlCatalogアプリケーションのMainViewから、HamburgerMenuナビゲーションを使用して「ListBox」を選択することでアクセスできます。

**主要な操作・処理内容**：
1. リスト内のアイテム選択（クリック、キーボード）
2. 選択モードの切り替え（Multiple、Toggle、AlwaysSelected）
3. AutoScrollToSelectedItemの有効/無効切り替え
4. WrapSelectionの有効/無効切り替え
5. Addボタン：新しいアイテムを追加
6. Removeボタン：選択中のアイテムを削除
7. Select Random Itemボタン：ランダムなアイテムを選択

**画面遷移**：
- 遷移元：MainView（HamburgerMenuによるナビゲーション）
- 遷移先：なし（デモページのため他画面への遷移機能はなし）

**権限による表示制御**：特になし。すべてのユーザーが全機能を利用可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 9 | ListBox | 主機能 | ListBoxコントロールのデモ。リスト形式の選択 |
| 41 | VirtualizingStackPanel | 補助機能 | 大量データの効率的表示 |

## 画面種別

デモ/サンプル画面

## URL/ルーティング

HamburgerMenuナビゲーション経由でアクセス（Avalonia UIフレームワークのページベースナビゲーション）

## 入出力項目

| 項目名 | 入力/出力 | 型 | 説明 |
|--------|----------|------|------|
| Multiple | 入力 | bool | 複数選択モードの有効/無効 |
| Toggle | 入力 | bool | トグル選択モードの有効/無効 |
| AlwaysSelected | 入力 | bool | 常時選択モードの有効/無効 |
| AutoScrollToSelectedItem | 入力 | bool | 選択アイテムへの自動スクロールの有効/無効 |
| WrapSelection | 入力 | bool | 選択のラップアラウンドの有効/無効 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|------|------|
| ヘッダーテキスト | TextBlock | "Hosts a collection of ListBoxItem." |
| 説明テキスト | TextBlock | nth-childルールの説明 |
| Multiple | CheckBox | 複数選択の切り替え |
| Toggle | CheckBox | トグル選択の切り替え |
| AlwaysSelected | CheckBox | 常時選択の切り替え |
| AutoScrollToSelectedItem | CheckBox | 自動スクロールの切り替え |
| WrapSelection | CheckBox | ラップ選択の切り替え |
| Add | Button | アイテム追加ボタン |
| Remove | Button | アイテム削除ボタン |
| Select Random Item | Button | ランダム選択ボタン |
| ListBox | ListBox | メインのリストボックス（10,000アイテム） |

## イベント仕様

### 1-選択モード変更

Multiple、Toggle、AlwaysSelectedチェックボックスの変更により、SelectionModeプロパティが更新されます。WhenAnyValueを使用してリアクティブに計算されます。

### 2-Addボタン

AddItemCommandが実行され、新しいItemModelがItemsコレクションに追加され、追加されたアイテムが選択されます。

### 3-Removeボタン

RemoveItemCommandが実行され、選択中のアイテムがItemsコレクションから削除されます。

### 4-Select Random Itemボタン

SelectRandomItemCommandが実行され、ランダムなインデックスのアイテムが選択されます。

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

本画面はデモ画面のため、データベース操作は行いません。ItemModelはメモリ上でのみ管理されます。

## メッセージ仕様

本画面には固有のメッセージ表示はありません。

## 例外処理

本画面はデモ画面のため、特別な例外処理は実装されていません。

## 備考

- 初期アイテム数は10,000件で、仮想化により効率的に表示
- VirtualizingStackPanelのCacheLengthは0.5に設定
- nth-child(5n+3)ルール：5番目ごと+3のアイテムを赤色・太字で表示
- nth-last-child(5n+4)ルール：後ろから5番目ごと+4のアイテムを青背景・太字で表示
- 偶数番目のアイテムにはContextFlyout（MenuFlyout）が設定
- SelectionModel<ItemModel>を使用した高度な選択管理
- DisplayMemberBindingでアイテムの表示形式をカスタマイズ

---

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

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

### 推奨読解順序

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

ViewModelとItemModelの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ListBoxPageViewModel.cs | `samples/ControlCatalog/ViewModels/ListBoxPageViewModel.cs` | Items、Selection、SelectionModeの管理を理解 |

**読解のコツ**: WhenAnyValueを使用したリアクティブなSelectionModeの計算、SelectionModel<T>の使用方法、MiniCommandによるコマンド実装を確認してください。

#### Step 2: UI定義を理解する

XAMLでListBoxの各種設定とスタイルを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ListBoxPage.xaml | `samples/ControlCatalog/Pages/ListBoxPage.xaml` | スタイルセレクター、バインディング設定を理解 |

**主要処理フロー**:
- **行7-26**: DockPanel.Stylesセクションでnth-child、nth-last-childルールを定義
- **行43-48**: ListBoxのItemsSource、Selection、SelectionModeバインディング

#### Step 3: コードビハインドを理解する

最小限のコードビハインドでViewModelの初期化を行います。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ListBoxPage.xaml.cs | `samples/ControlCatalog/Pages/ListBoxPage.xaml.cs` | DataContext設定 |

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

```
ListBoxPage (UserControl)
    |
    +-- ListBoxPage.xaml.cs (Code-behind)
    |       |
    |       +-- InitializeComponent()
    |       +-- DataContext = new ListBoxPageViewModel()
    |
    +-- ListBoxPageViewModel (ViewModel)
    |       |
    |       +-- Items: ObservableCollection<ItemModel>
    |       |       +-- 初期10,000アイテム
    |       |
    |       +-- Selection: SelectionModel<ItemModel>
    |       |
    |       +-- SelectionMode: IObservable<SelectionMode>
    |       |       +-- WhenAnyValue(Multiple, Toggle, AlwaysSelected)
    |       |
    |       +-- AddItemCommand
    |       |       +-- Items.Add(newItem)
    |       |       +-- Selection.Select(lastIndex)
    |       |
    |       +-- RemoveItemCommand
    |       |       +-- Items.Remove(selectedItems)
    |       |
    |       +-- SelectRandomItemCommand
    |               +-- Selection.Select(randomIndex)
    |
    +-- ItemModel
            +-- ID: int
            +-- ToString(): "Item {ID}"
```

### データフロー図

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

CheckBox変更 ─────────> WhenAnyValue() ───────────────> SelectionMode更新
(Multiple/Toggle/            |                          ListBox動作変更
 AlwaysSelected)             v
                        SelectionMode計算
                        (Multiple | Toggle | AlwaysSelected)

Addボタン ────────────> AddItemCommand ───────────────> Items.Add()
                              |                         Selection.Select()
                              v
                        GenerateItem()
                        新規ItemModel生成

Removeボタン ─────────> RemoveItemCommand ────────────> Items.Remove()
                              |
                              v
                        Selection.SelectedItems
                        からループ削除

Select Random ────────> SelectRandomItemCommand ──────> Selection.Select()
                              |
                              v
                        Random.Next(Items.Count)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ListBoxPage.xaml | `samples/ControlCatalog/Pages/ListBoxPage.xaml` | XAML | UI定義、スタイルセレクター |
| ListBoxPage.xaml.cs | `samples/ControlCatalog/Pages/ListBoxPage.xaml.cs` | ソース | コードビハインド |
| ListBoxPageViewModel.cs | `samples/ControlCatalog/ViewModels/ListBoxPageViewModel.cs` | ソース | ViewModel、コマンド実装 |
