# 機能設計書 71-CrossFade

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるクロスフェードトランジション機能（CrossFade）の設計仕様を記述する。CrossFadeは、2つのVisual要素間でフェードイン・フェードアウトを同時に実行するページ遷移アニメーションを提供する。

### 本機能の処理概要

CrossFadeは、ページやコンテンツの切り替え時に滑らかな視覚的遷移を実現するアニメーション機能である。古いコンテンツが徐々に透明になりながら（フェードアウト）、新しいコンテンツが徐々に表示される（フェードイン）ことで、ユーザーに自然な画面遷移体験を提供する。

**業務上の目的・背景**：モダンなUIアプリケーションでは、画面遷移時のユーザー体験が重要視される。突然の画面切り替えはユーザーに違和感を与えるため、クロスフェードのような滑らかな遷移アニメーションを導入することで、アプリケーションの品質と使いやすさを向上させる。特にマルチページアプリケーションやウィザード形式のUIで効果的である。

**機能の利用シーン**：TransitioningContentControlでのコンテンツ切り替え、ページナビゲーション時の遷移効果、カルーセルコントロールでのスライド切り替え、タブコントロールでのタブ切り替えなど、2つのVisual要素を切り替える場面で使用される。

**主要な処理内容**：
1. フェードアウトアニメーションの生成（Opacity: 1.0 → 0.0）
2. フェードインアニメーションの生成（Opacity: 0.0 → 1.0）
3. 両アニメーションの並列実行
4. アニメーション完了後の可視性制御

**関連システム・外部連携**：Avaloniaのアニメーションシステム（Animation、KeyFrame、Cue）と連携し、IPageTransitionインターフェースを実装することでTransitioningContentControl等のコントロールから利用可能となる。

**権限による制御**：本機能は純粋なUI表示機能であり、特別な権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 60 | TransitioningContentControl | 主画面 | コンテンツ遷移アニメーションのデフォルトトランジションとして使用 |

## 機能種別

アニメーション処理 / UI遷移効果

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Duration | TimeSpan | No | アニメーションの持続時間 | TimeSpan.Zero以上 |
| FadeInEasing | Easing | No | フェードイン時のイージング関数 | null可（デフォルトはLinear） |
| FadeOutEasing | Easing | No | フェードアウト時のイージング関数 | null可（デフォルトはLinear） |
| from | Visual? | Yes | 遷移元のVisual要素 | null可（遷移元がない場合） |
| to | Visual? | Yes | 遷移先のVisual要素 | null可（遷移先がない場合） |
| cancellationToken | CancellationToken | Yes | キャンセルトークン | - |

### 入力データソース

- アプリケーションコードからの直接インスタンス化
- XAMLマークアップでのリソース定義
- TransitioningContentControlのTransitionプロパティ設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Task | Task | アニメーション完了を追跡するTask |

### 出力先

- Visual要素のOpacityプロパティ変更
- Visual要素のIsVisibleプロパティ変更

## 処理フロー

### 処理シーケンス

```
1. Start メソッド呼び出し
   └─ キャンセルチェック（IsCancellationRequested）
2. フェードアウトアニメーション開始（fromがnullでない場合）
   └─ _fadeOutAnimation.RunAsync(from, null, cancellationToken)
3. フェードインアニメーション開始（toがnullでない場合）
   └─ to.IsVisible = true
   └─ _fadeInAnimation.RunAsync(to, null, cancellationToken)
4. 両アニメーションの完了待機
   └─ Task.WhenAll(tasks)
5. 遷移元の非表示化（キャンセルされていない場合）
   └─ from.IsVisible = false
```

### フローチャート

```mermaid
flowchart TD
    A[Start] --> B{キャンセル済み?}
    B -->|Yes| Z[終了]
    B -->|No| C{from != null?}
    C -->|Yes| D[フェードアウトタスク追加]
    C -->|No| E{to != null?}
    D --> E
    E -->|Yes| F[to.IsVisible = true]
    F --> G[フェードインタスク追加]
    E -->|No| H[Task.WhenAll待機]
    G --> H
    H --> I{from != null かつ キャンセルなし?}
    I -->|Yes| J[from.IsVisible = false]
    I -->|No| Z
    J --> Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-71-01 | 並列アニメーション | フェードインとフェードアウトは同時に実行される | 常時 |
| BR-71-02 | 方向性無視 | forward引数は無視される（クロスフェードは方向に依存しない） | IPageTransition経由の呼び出し時 |
| BR-71-03 | 可視性制御 | 遷移先は事前に可視化、遷移元は完了後に非表示化 | アニメーション実行時 |

### 計算ロジック

フェードアウト: Opacity = 1.0 - progress（progressは0.0から1.0）
フェードイン: Opacity = progress（progressは0.0から1.0）

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | OperationCanceledException | CancellationTokenがキャンセルされた場合 | アニメーションを中断し、現在の状態を維持 |

### リトライ仕様

本機能にリトライ仕様は存在しない。キャンセル時は新しいトランジションを開始することで対応する。

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

本機能にトランザクション管理は存在しない。

## パフォーマンス要件

- アニメーションはGPUアクセラレーションを活用
- デフォルトのDurationはTimeSpan.Zero（即時遷移）
- 推奨Duration: 200ms〜500ms

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

本機能はUIアニメーションのみを処理するため、特別なセキュリティ考慮事項は存在しない。

## 備考

- CrossFadeはIPageTransitionインターフェースを実装するが、forward引数は無視される
- CancellationTokenを使用して外部からアニメーションを中断可能

---

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

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

### 推奨読解順序

#### Step 1: インターフェースを理解する

まず、CrossFadeが実装するインターフェースを理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IPageTransition.cs | `src/Avalonia.Base/Animation/IPageTransition.cs` | ページトランジションの契約を定義 |

**読解のコツ**: IPageTransitionインターフェースはStartメソッドを定義し、from/to/forward/cancellationTokenを受け取る。CrossFadeはforward引数を無視する点に注目。

#### Step 2: メインクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CrossFade.cs | `src/Avalonia.Base/Animation/CrossFade.cs` | クロスフェードトランジションの実装全体 |

**主要処理フロー**:
1. **32-97行目**: コンストラクタでフェードイン・アウトアニメーションを初期化
2. **34-64行目**: _fadeOutAnimationの定義（Opacity 1.0→0.0）
3. **65-95行目**: _fadeInAnimationの定義（Opacity 0.0→1.0）
4. **127-153行目**: Startメソッドでアニメーションを実行

#### Step 3: 依存コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Animation.cs | `src/Avalonia.Base/Animation/Animation.cs` | アニメーション実行の仕組み |
| 3-2 | KeyFrame.cs | `src/Avalonia.Base/Animation/KeyFrame.cs` | キーフレームの定義 |
| 3-3 | Cue.cs | `src/Avalonia.Base/Animation/Cue.cs` | アニメーション進行度の管理 |

**主要処理フロー**:
- **Animation.RunAsync**: アニメーションを非同期で実行
- **KeyFrame.Setters**: 各キーフレームでのプロパティ設定
- **Cue**: 0.0〜1.0の進行度を表現

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

```
CrossFade.Start(from, to, cancellationToken)
    │
    ├─ _fadeOutAnimation.RunAsync(from, null, cancellationToken)
    │      └─ Animation.RunAsync()
    │             └─ KeyFrame処理
    │                    └─ Setter適用（Opacity変更）
    │
    └─ _fadeInAnimation.RunAsync(to, null, cancellationToken)
           └─ Animation.RunAsync()
                  └─ KeyFrame処理
                         └─ Setter適用（Opacity変更）
```

### データフロー図

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

from (Visual?)  ───▶ CrossFade.Start() ───▶ from.Opacity: 1.0→0.0
                          │                  from.IsVisible = false
to (Visual?)    ───▶      │          ───▶ to.Opacity: 0.0→1.0
                          │                  to.IsVisible = true
Duration        ───▶      │
FadeInEasing    ───▶      │
FadeOutEasing   ───▶      │
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CrossFade.cs | `src/Avalonia.Base/Animation/CrossFade.cs` | ソース | クロスフェードトランジション本体 |
| IPageTransition.cs | `src/Avalonia.Base/Animation/IPageTransition.cs` | ソース | ページトランジションインターフェース |
| Animation.cs | `src/Avalonia.Base/Animation/Animation.cs` | ソース | アニメーション基底クラス |
| KeyFrame.cs | `src/Avalonia.Base/Animation/KeyFrame.cs` | ソース | キーフレーム定義 |
| Cue.cs | `src/Avalonia.Base/Animation/Cue.cs` | ソース | 進行度管理 |
| Setter.cs | `src/Avalonia.Base/Styling/Setter.cs` | ソース | プロパティ設定 |
| Visual.cs | `src/Avalonia.Base/Visual.cs` | ソース | OpacityPropertyの定義元 |
| Easing.cs | `src/Avalonia.Base/Animation/Easings/Easing.cs` | ソース | イージング基底クラス |
