# 機能設計書 30-Carousel

## 概要

本ドキュメントは、AvaloniaフレームワークにおけるCarouselコントロールの機能設計を記載する。Carouselは、複数のコンテンツをスライドショー形式で表示するコンテナコントロールである。

### 本機能の処理概要

Carouselは、複数のアイテムを1つずつ表示し、スワイプ操作やボタン操作で前後のアイテムに切り替えることができるコントロールである。画像ギャラリー、オンボーディング画面、プロダクトショーケースなどで使用される。トランジションアニメーションをサポートし、滑らかな切り替え効果を提供する。

**業務上の目的・背景**：
限られた画面スペースで複数のコンテンツを効果的に表示する必要がある場面で使用される。視覚的に魅力的なコンテンツ表示により、ユーザーエンゲージメントを向上させる。

**機能の利用シーン**：
- 画像ギャラリー・スライドショー
- オンボーディング/チュートリアル画面
- プロダクト・サービスのショーケース
- バナー広告の表示
- ウィザード形式のステップ表示
- ダッシュボードのウィジェット切り替え

**主要な処理内容**：
1. 複数アイテムの管理と1アイテム表示
2. Next/Previousによるアイテム切り替え
3. トランジションアニメーションの実行
4. スワイプ/タッチ操作によるナビゲーション
5. キーボード操作（左右矢印）によるナビゲーション
6. SelectedIndexによる現在位置の管理

**関連システム・外部連携**：
- IPageTransitionインターフェースによるカスタムトランジション

**権限による制御**：
本コントロールには権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | Carousel | 主画面 | Carouselコントロールのデモ |

## 機能種別

UI操作 / コンテナコントロール / スライドショー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ItemsSource | IEnumerable | No | 表示するアイテムのコレクション | - |
| Items | IList | No | 直接追加されたアイテム | - |
| SelectedIndex | int | No | 現在選択中のインデックス | 0〜Items.Count-1 |
| SelectedItem | object | No | 現在選択中のアイテム | - |
| PageTransition | IPageTransition | No | ページ切り替えトランジション | - |
| ItemTemplate | IDataTemplate | No | アイテム表示テンプレート | - |
| IsVirtualized | bool | No | 仮想化の有効/無効 | デフォルト: true |

### 入力データソース

- ユーザーによるスワイプ/タッチ操作
- キーボード操作（左右矢印、Home、End）
- プログラムによるNext/Previous呼び出し
- プログラムによるSelectedIndex/SelectedItem設定
- データバインディングによる制御

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SelectedIndex | int | 現在選択中のインデックス |
| SelectedItem | object | 現在選択中のアイテム |
| ItemCount | int | アイテムの総数 |

### 出力先

- UI表示（現在のアイテム、トランジションアニメーション）
- SelectionChangedイベントの発行

## 処理フロー

### 処理シーケンス

```
1. アイテムコレクション設定
   └─ ItemsSource/Items設定
2. 初期表示
   └─ SelectedIndex=0のアイテム表示
3. ナビゲーション操作検出
   ├─ スワイプ操作: ポインターイベント
   ├─ キーボード: OnKeyDown
   └─ プログラム: Next/Previous
4. インデックス変更
   └─ SelectedIndex更新
5. トランジション実行
   └─ PageTransition.Start
6. コンテンツ切り替え
   └─ 新しいアイテムを表示
7. イベント発行
   └─ SelectionChanged
```

### フローチャート

```mermaid
flowchart TD
    A[ナビゲーション操作] --> B{操作タイプ}
    B -->|Next| C[SelectedIndex + 1]
    B -->|Previous| D[SelectedIndex - 1]
    B -->|Swipe左| C
    B -->|Swipe右| D
    B -->|直接指定| E[指定インデックス]
    C --> F{範囲内?}
    D --> F
    E --> F
    F -->|No| G[WrapSelectionに応じてラップ]
    F -->|Yes| H[SelectedIndex更新]
    G --> H
    H --> I{PageTransitionあり?}
    I -->|Yes| J[トランジション実行]
    I -->|No| K[即座に切り替え]
    J --> L[コンテンツ表示]
    K --> L
    L --> M[SelectionChangedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | インデックス範囲 | SelectedIndexは0〜Items.Count-1の範囲 | 常時適用 |
| BR-002 | ラップナビゲーション | WrapSelection=trueの場合、末尾から先頭へ/先頭から末尾へ循環 | 設定時 |
| BR-003 | 仮想化 | IsVirtualized=trueの場合、表示されていないアイテムは生成しない | 設定時 |
| BR-004 | トランジション方向 | Next=forward、Previous=backward | 常時適用 |

### 計算ロジック

インデックスラップ処理：
```
if (WrapSelection) {
    newIndex = ((newIndex % count) + count) % count;
} else {
    newIndex = Math.Clamp(newIndex, 0, count - 1);
}
```

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

本コントロールはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 範囲外インデックス | SelectedIndexが範囲外 | 範囲内にクランプまたはラップ |
| - | 空コレクション | Items.Count=0でナビゲーション | 操作を無視 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- トランジションアニメーションは60fpsで滑らかに実行
- 仮想化により、大量アイテムでもメモリ効率を維持

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

本コントロールにはセキュリティ上の特別な考慮事項はない。

## 備考

- SelectingItemsControlを継承しているため、選択機能の基本動作はそこから継承
- 大量アイテムの場合はIsVirtualized=trueを推奨

---

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

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

### 推奨読解順序

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

Carousel関連の型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Carousel.cs | `src/Avalonia.Controls/Carousel.cs` | プロパティ定義 |
| 1-2 | SelectingItemsControl.cs | `src/Avalonia.Controls/Primitives/SelectingItemsControl.cs` | 基底クラス |

**読解のコツ**: CarouselはSelectingItemsControlを継承しており、選択機能の基本動作（SelectedIndex、SelectedItem）は基底クラスで定義されている。

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

Carouselクラスの主要プロパティを理解する。

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

**主要処理フロー**:
1. **18行目**: PseudoClasses属性で:empty擬似クラスを定義
2. **22-27行目**: TemplatePart属性でPART_TransitioningContentPresenterを定義
3. **30-36行目**: IsVirtualized、PageTransitionプロパティ定義

#### Step 3: ナビゲーション処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Carousel.cs | `src/Avalonia.Controls/Carousel.cs` | Next、Previous、OnKeyDown |

**主要処理フロー**:
- **Nextメソッド**: SelectedIndexを+1
- **Previousメソッド**: SelectedIndexを-1
- **OnKeyDown**: 左右矢印、Home、Endキーの処理

#### Step 4: トランジション処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Carousel.cs | `src/Avalonia.Controls/Carousel.cs` | OnSelectionChanged |
| 4-2 | TransitioningContentControl.cs | `src/Avalonia.Controls/TransitioningContentControl.cs` | トランジション実行 |

**主要処理フロー**:
- OnSelectionChangedで選択変更を検出
- TransitioningContentPresenterでトランジション実行

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

```
Carousel
    │
    ├─ Next
    │      └─ SelectedIndex++
    │
    ├─ Previous
    │      └─ SelectedIndex--
    │
    ├─ OnKeyDown
    │      ├─ Key.Left → Previous
    │      ├─ Key.Right → Next
    │      ├─ Key.Home → SelectedIndex = 0
    │      └─ Key.End → SelectedIndex = Count - 1
    │
    └─ OnSelectionChanged
           └─ TransitioningContentPresenter
                  └─ PageTransition.Start
```

### データフロー図

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

スワイプ/キー入力 ─────▶ Next/Previous
                              │
                              ▼
                       SelectedIndex更新
                              │
                              ▼
プログラム設定 ────────▶ OnSelectionChanged
                              │
                              ▼
                       TransitioningContentPresenter
                              │
                              ├─▶ PageTransition.Start（アニメーション）
                              │
                              ▼
                       コンテンツ切り替え
                              │
                              └─▶ SelectionChangedイベント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Carousel.cs | `src/Avalonia.Controls/Carousel.cs` | ソース | メインコントロールクラス |
| SelectingItemsControl.cs | `src/Avalonia.Controls/Primitives/SelectingItemsControl.cs` | ソース | 基底クラス |
| TransitioningContentControl.cs | `src/Avalonia.Controls/TransitioningContentControl.cs` | ソース | トランジション付きコンテンツコントロール |
| IPageTransition.cs | `src/Avalonia.Base/Animation/IPageTransition.cs` | ソース | トランジションインターフェース |
| PageSlide.cs | `src/Avalonia.Base/Animation/PageSlide.cs` | ソース | スライドトランジション |
| CrossFade.cs | `src/Avalonia.Base/Animation/CrossFade.cs` | ソース | クロスフェードトランジション |
| Carousel.xaml | `src/Avalonia.Themes.Fluent/Controls/Carousel.xaml` | テンプレート | Fluentテーマのテンプレート |
