# 機能設計書 65-ThemeVariant

## 概要

本ドキュメントは、Avaloniaフレームワークにおける**ThemeVariant**機能の設計仕様を記述する。ThemeVariantは、ライト・ダーク等のテーマバリアント（テーマの変種）を指定し、UIの配色やスタイルを切り替えるための機能を提供する。

### 本機能の処理概要

ThemeVariantは、ControlおよびApplicationに対して適用すべきUIテーマバリアントを指定するレコード型である。Light、Dark、Defaultの3つの定義済みバリアントに加え、カスタムバリアントの作成もサポートする。バリアント間の継承関係も定義可能で、リソースが見つからない場合のフォールバック動作を制御できる。

**業務上の目的・背景**：現代のUIアプリケーションでは、ユーザーの好みやシステム設定に応じてライトモードとダークモードを切り替える機能が標準的に求められる。ThemeVariantは、この要件を満たすための基盤機能を提供し、テーマ切り替えを宣言的かつ効率的に実現する。また、カスタムバリアントにより、ハイコントラストモード等の追加テーマバリアントの定義も可能にする。

**機能の利用シーン**：
- アプリケーション全体のテーマ切り替え（ライト/ダーク）
- 個別コントロールのテーマオーバーライド
- システムテーマの継承
- カスタムテーマバリアントの作成
- リソースディクショナリのテーマ別管理

**主要な処理内容**：
1. テーマバリアントの指定（RequestedThemeVariant）
2. 実際に適用されるテーマバリアントの取得（ActualThemeVariant）
3. テーマバリアント間の継承関係の定義
4. プラットフォームテーマとの変換

**関連システム・外部連携**：ThemeVariantはAvalonia.Base.Stylingモジュール内で実装され、ResourceDictionary、StyledElement、Application、およびプラットフォーム固有のテーマ検出システムと連携する。

**権限による制御**：特にアクセス権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | メインビュー | 補助機能 | ライト・ダークテーマの切り替え設定UI |
| 57 | Theme Variants | 主機能 | テーマバリアントのデモ。ライト・ダーク等のテーマ切り替え |

## 機能種別

テーマ管理 / リソース管理 / 状態管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Key | object | Yes | テーマバリアントのキー | nullは不可 |
| InheritVariant | ThemeVariant | No | 継承するテーマバリアント | Defaultは不可 |

### 入力データソース

- ユーザー設定（RequestedThemeVariant）
- システムテーマ（PlatformThemeVariant）
- 親要素からの継承

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ThemeVariant | record | テーマバリアントのインスタンス |
| ActualThemeVariant | ThemeVariant | 実際に適用されるテーマバリアント |

### 出力先

- ResourceDictionary.ThemeVariantプロパティ
- StyledElement.RequestedThemeVariantプロパティ
- Application.ActualThemeVariantプロパティ

## 処理フロー

### 処理シーケンス

```
1. テーマバリアントの要求
   └─ RequestedThemeVariantプロパティの設定
2. 実際のテーマバリアントの決定
   └─ Default時はシステムテーマを使用
3. リソース検索時のテーマ判定
   └─ ResourceDictionaryのThemeVariantキーと照合
4. フォールバック処理
   └─ InheritVariantを使用したフォールバック
```

### フローチャート

```mermaid
flowchart TD
    A[RequestedThemeVariant設定] --> B{Default?}
    B -->|Yes| C[システムテーマ取得]
    B -->|No| D[指定バリアント使用]
    C --> E[ActualThemeVariant決定]
    D --> E
    E --> F[リソース検索]
    F --> G{リソース存在?}
    G -->|Yes| H[リソース返却]
    G -->|No| I{InheritVariant?}
    I -->|Yes| J[継承バリアントで再検索]
    I -->|No| K{Defaultあり?}
    J --> G
    K -->|Yes| L[Defaultリソース返却]
    K -->|No| M[null返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-65-01 | Default継承禁止 | InheritVariantにDefaultを指定することは不可 | コンストラクタ |
| BR-65-02 | キーによる比較 | ThemeVariantの等価性はKeyプロパティで判定 | Equals呼び出し時 |
| BR-65-03 | システムテーマ継承 | Defaultバリアント時はシステムテーマを継承 | Application |
| BR-65-04 | 親からの継承 | ActualThemeVariantは親要素から継承される | inherits: true |

### 計算ロジック

- 等価性判定: `Equals(Key, other.Key)`
- ハッシュコード: `Key.GetHashCode()`

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ArgumentNullException | Keyがnullの場合 | 有効なキーを指定する |
| - | ArgumentException | InheritVariantにDefaultを指定した場合 | Light/Darkまたはカスタムバリアントを指定 |
| - | ArgumentOutOfRangeException | 無効なPlatformThemeVariantを変換した場合 | 有効な値を使用 |

### リトライ仕様

リトライ処理は行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

- テーマ切り替えは即座に反映される
- リソース検索は効率的に実行される

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

特段のセキュリティ要件はない。

## 備考

- 定義済みバリアント: Default, Light, Dark
- PlatformThemeVariantとの相互変換をサポート
- TypeConverterによるXAMLでの文字列指定をサポート

---

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

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

### 推奨読解順序

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

ThemeVariantレコードの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ThemeVariant.cs | `src/Avalonia.Base/Styling/ThemeVariant.cs` | Key, InheritVariant、定義済みバリアント、演算子オーバーロードを確認 |

**読解のコツ**: ThemeVariantはrecord型で定義されており、不変性と値の等価性を持つ。

**主要処理フロー (ThemeVariant.cs)**:
1. **21-24行目**: ActualThemeVariantProperty - 実際のテーマを保持するStyledProperty（継承あり）
2. **29-31行目**: RequestedThemeVariantProperty - 要求されたテーマを保持するStyledProperty
3. **40-49行目**: コンストラクタ - Key, InheritVariantの設定とバリデーション
4. **59行目**: Key プロパティ - バリアントを識別するキー
5. **64行目**: InheritVariant プロパティ - フォールバック先バリアント
6. **70行目**: Default 静的プロパティ - デフォルトバリアント
7. **75行目**: Light 静的プロパティ - ライトバリアント
8. **80行目**: Dark 静的プロパティ - ダークバリアント
9. **87-95行目**: Equals メソッド - キーベースの等価性判定
10. **97-123行目**: 明示的変換演算子 - PlatformThemeVariantとの相互変換

#### Step 2: TypeConverterを理解する

XAMLでの文字列からの変換処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ThemeVariantTypeConverter.cs | `src/Avalonia.Base/Styling/ThemeVariantTypeConverter.cs` | 文字列からThemeVariantへの変換 |

#### Step 3: プロパティの定義と継承を理解する

ActualThemeVariantPropertyの継承動作を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | RequestedThemeVariant/ActualThemeVariantプロパティの使用 |
| 3-2 | Application.cs | `src/Avalonia.Controls/Application.cs` | アプリケーションレベルのテーマ管理 |

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

```
Application/StyledElement
    │
    ├─ RequestedThemeVariant設定
    │      │
    │      └─ ActualThemeVariant更新
    │
    └─ リソース検索
           │
           └─ ResourceDictionary.TryGetResource(key, themeVariant)
                  │
                  ├─ ThemeVariantキーの照合
                  │
                  └─ InheritVariantによるフォールバック
```

### データフロー図

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

RequestedThemeVariant ──────▶ テーマ決定処理 ─────────────────▶ ActualThemeVariant
    │                              │                                  │
    │ Light/Dark/Default          │ Default時:                       │ Light/Dark
    │                              │   システムテーマ取得              │
    └──────────────────────────────┘                                  │
                                                                      ▼
                                                              リソース検索
                                                                      │
                                                                      ▼
                                                              テーマ固有リソース取得
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ThemeVariant.cs | `src/Avalonia.Base/Styling/ThemeVariant.cs` | ソース | テーマバリアントレコード |
| ThemeVariantTypeConverter.cs | `src/Avalonia.Base/Styling/ThemeVariantTypeConverter.cs` | ソース | TypeConverter |
| StyledElement.cs | `src/Avalonia.Base/StyledElement.cs` | ソース | テーマプロパティ使用 |
| Application.cs | `src/Avalonia.Controls/Application.cs` | ソース | アプリレベルテーマ管理 |
| ResourceDictionary.cs | `src/Avalonia.Controls/ResourceDictionary.cs` | ソース | テーマ別リソース管理 |
| PlatformThemeVariant.cs | `src/Avalonia.Base/Platform/PlatformThemeVariant.cs` | ソース | プラットフォームテーマ列挙型 |
