# 画面設計書 48-RefreshContainer

## 概要

本ドキュメントは、Avalonia UIフレームワークのControlCatalogサンプルアプリケーションにおける「RefreshContainer」デモページの画面設計書です。

### 本画面の処理概要

RefreshContainerページは、プルダウンによるリフレッシュ機能（Pull-to-Refresh）をデモンストレーションする画面です。タッチ操作やマウスドラッグでコンテンツを引き下げることでデータ更新をトリガーできます。

**業務上の目的・背景**：モバイルアプリケーションで一般的なPull-to-Refresh UIパターンは、ユーザーが直感的にデータを更新できるインターフェースを提供します。本画面は、RefreshContainerコントロールを使用して、スクロール可能なリストの上部から引き下げる操作でデータリフレッシュを実行する方法を示しています。SNSフィード、ニュースリスト、メールボックスなど、動的なコンテンツを表示するアプリケーションで活用できます。

**画面へのアクセス方法**：MainWindowからMainViewのHamburgerMenuを開き、「RefreshContainer」メニュー項目を選択することでアクセスできます。

**主要な操作・処理内容**：
1. リストを上方向にスクロールして最上部を超えて引き下げる
2. RefreshContainerがリフレッシュインジケーターを表示
3. リフレッシュがトリガーされると、RefreshRequestedイベントが発生
4. 非同期でデータを追加（3秒のディレイ後）
5. リストの先頭に新しいアイテムを挿入

**画面遷移**：本画面は単独のデモページであり、MainViewのHamburgerMenuから遷移します。他画面への直接遷移機能は持ちません。

**権限による表示制御**：本デモ画面では権限による表示制御は実装されていません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | ScrollViewer | 主機能 | プルダウンリフレッシュのスクロール制御 |

## 画面種別

デモ / リスト更新

## URL/ルーティング

ControlCatalog内のHamburgerMenuナビゲーションによるページ切り替え（URL/ルーティング定義なし）

## 入出力項目

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| Items | 出力 | ObservableCollection<string> | - | リスト表示データ（初期200件） |

## 表示項目

| 項目名 | 表示位置 | 説明 |
|--------|----------|------|
| ラベル | 上部 | "A control that supports pull to refresh" |
| RefreshContainer | 中央〜下部 | プルダウンリフレッシュ対応コンテナ（高さ600） |
| ListBox | RefreshContainer内 | アイテムリスト表示 |
| RefreshVisualizer | プルダウン時 | リフレッシュインジケーター（自動表示） |

## イベント仕様

### 1-RefreshRequested イベント

ユーザーがコンテンツを引き下げてリフレッシュをトリガーすると発生する。イベントハンドラ内でDeferralを取得し、非同期処理完了後にComplete()を呼び出す。

### 2-AddToTop 処理

RefreshRequestedイベントハンドラ内で呼び出される。3秒のディレイ後、ObservableCollectionの先頭に新しいアイテムを挿入する。

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

本画面はUIコントロールのデモ画面であり、データベースへのアクセス・更新は行いません。

## メッセージ仕様

本画面では特定のメッセージ表示は実装されていません。

## 例外処理

本画面では特別な例外処理は実装されていません。

## 備考

- PullDirection="TopToBottom" で上から下へのプル方向を指定
- RefreshRequestedEventArgs.GetDeferral()で非同期処理の完了を制御
- ObservableCollection.Insert(0, item)でリスト先頭に追加
- 初期データは "Item 1" 〜 "Item 200" の200件

---

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

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

### 推奨読解順序

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

ViewModelのデータコレクションを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | RefreshContainerViewModel.cs | `samples/ControlCatalog/ViewModels/RefreshContainerViewModel.cs` | Itemsプロパティ（12行）でObservableCollection確認 |
| 1-2 | RefreshContainerViewModel.cs | `samples/ControlCatalog/ViewModels/RefreshContainerViewModel.cs` | コンストラクタ（14-17行）で初期データ生成 |

**読解のコツ**: ObservableCollectionとINotifyPropertyChangedの関係を理解しておくと良い。

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

UserControlの初期化処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | RefreshContainerPage.axaml.cs | `samples/ControlCatalog/Pages/RefreshContainerPage.axaml.cs` | コンストラクタ（10-16行）でViewModel設定 |

**主要処理フロー**:
1. **12行**: InitializeComponentでXAMLをロード
2. **14行**: RefreshContainerViewModelをインスタンス化
3. **16行**: DataContextにViewModelを設定

#### Step 3: RefreshRequestedイベント処理を理解する

プルダウンリフレッシュの処理フローを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | RefreshContainerPage.axaml.cs | `samples/ControlCatalog/Pages/RefreshContainerPage.axaml.cs` | RefreshContainerPage_RefreshRequested（19-26行） |
| 3-2 | RefreshContainerViewModel.cs | `samples/ControlCatalog/ViewModels/RefreshContainerViewModel.cs` | AddToTop（19-23行）で非同期データ追加 |

**主要処理フロー**:
- **21行**: e.GetDeferral()で遅延オブジェクト取得
- **23行**: _viewModel.AddToTop()を非同期実行
- **25行**: deferral.Complete()でリフレッシュ完了を通知

#### Step 4: XAMLレイアウトを理解する

RefreshContainerの配置とバインディングを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | RefreshContainerPage.axaml | `samples/ControlCatalog/Pages/RefreshContainerPage.axaml` | DockPanel構造（11-26行） |
| 4-2 | RefreshContainerPage.axaml | `samples/ControlCatalog/Pages/RefreshContainerPage.axaml` | RefreshContainer定義（15-25行） |

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

```
RefreshContainerPage (UserControl)
    │
    ├─ InitializeComponent()
    │      └─ XAMLパーサー → RefreshContainerPage.axaml読み込み
    │
    ├─ RefreshContainerViewModel
    │      ├─ Items (ObservableCollection<string>)
    │      │      └─ 初期データ: "Item 1" 〜 "Item 200"
    │      │
    │      └─ AddToTop()
    │             ├─ Task.Delay(3000)
    │             └─ Items.Insert(0, newItem)
    │
    └─ RefreshContainerPage_RefreshRequested
           ├─ e.GetDeferral()
           ├─ await _viewModel.AddToTop()
           └─ deferral.Complete()
```

### データフロー図

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

プルダウン操作 ──────────▶ RefreshContainer ──────────▶ RefreshRequested
(タッチ/マウス)           ├─ PullDirection判定          イベント発生
                          └─ RefreshVisualizer表示         │
                                                           ▼
                                                    GetDeferral()
                                                           │
                                                           ▼
                                                    AddToTop()
                                                    ├─ Task.Delay(3000)
                                                    └─ Items.Insert(0, ...)
                                                           │
                                                           ▼
                                                    deferral.Complete()
                                                           │
                                                           ▼
                                                    ListBox更新
                                                    (ObservableCollection通知)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| RefreshContainerPage.axaml | `samples/ControlCatalog/Pages/RefreshContainerPage.axaml` | XAML | 画面レイアウト・RefreshContainer定義 |
| RefreshContainerPage.axaml.cs | `samples/ControlCatalog/Pages/RefreshContainerPage.axaml.cs` | ソース | コードビハインド・イベントハンドラ |
| RefreshContainerViewModel.cs | `samples/ControlCatalog/ViewModels/RefreshContainerViewModel.cs` | ソース | ViewModel・データ管理 |
