# 機能設計書 38-Border

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるBorder（ボーダー装飾コンテナ）の機能設計を定義するものである。Borderは単一の子要素に対してボーダー（境界線）と背景を付与する装飾コンテナを提供する。

### 本機能の処理概要

Borderは、Decoratorを継承し、単一の子要素に対してボーダー線、背景色、角丸、ボックスシャドウなどの視覚的な装飾を追加するコンテナを提供する。CSS的なボックスモデルに類似した装飾機能を実現する。

**業務上の目的・背景**：UIデザインにおいて、要素に対する視覚的な境界線の追加、背景色の設定、角丸の適用は非常に一般的な要件である。Borderは、これらの装飾を宣言的かつ再利用可能な形で提供し、一貫性のあるUI設計を支援する。

**機能の利用シーン**：
- カード形式のコンテンツ表示
- パネルやセクションの区切り
- ボタンやフォーム要素の装飾
- シャドウ効果付きのコンテナ

**主要な処理内容**：
1. BorderThicknessによる境界線の太さ設定
2. BorderBrushによる境界線の色/ブラシ設定
3. Backgroundによる背景色/ブラシ設定
4. CornerRadiusによる角丸設定
5. BoxShadowによるシャドウ効果
6. BackgroundSizingによる背景描画領域の調整

**関連システム・外部連携**：Decoratorを継承し、IVisualWithRoundRectClipを実装。

**権限による制御**：特になし。UIコンポーネントとしてアプリケーション側で必要に応じて実装。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | Borderは多くの画面で装飾コンテナとして使用される |

## 機能種別

装飾 / UIコンテナ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Background | IBrush? | No | 背景を塗りつぶすブラシ | - |
| BackgroundSizing | BackgroundSizing | No | 背景描画領域（デフォルト: CenterBorder） | InnerBorderEdge/OuterBorderEdge/CenterBorder |
| BorderBrush | IBrush? | No | 境界線を塗りつぶすブラシ | - |
| BorderThickness | Thickness | No | 境界線の太さ（デフォルト: 0） | 0以上 |
| CornerRadius | CornerRadius | No | 角丸の半径（デフォルト: 0） | 0以上 |
| BoxShadow | BoxShadows | No | ボックスシャドウ効果 | - |
| Child | Control? | No | 装飾対象の子要素（Decoratorから継承） | - |
| Padding | Thickness | No | 子要素との内側余白（Decoratorから継承） | 0以上 |

### BackgroundSizing列挙型

| 値 | 説明 |
|-----|------|
| InnerBorderEdge | 背景を境界線の内側に描画 |
| OuterBorderEdge | 背景を境界線の外側に描画 |
| CenterBorder | 背景を境界線の中央に描画 |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DesiredSize | Size | 計測フェーズで計算された希望サイズ（子+Padding+BorderThickness） |
| 描画出力 | 視覚効果 | 背景、ボーダー、シャドウの描画 |

## 処理フロー

### 処理シーケンス

```
1. MeasureOverrideフェーズ
   └─ LayoutHelper.MeasureChild（子+Padding+BorderThickness考慮）
2. ArrangeOverrideフェーズ
   └─ LayoutHelper.ArrangeChild（Padding+BorderThickness分内側に配置）
3. Renderフェーズ
   ├─ BorderRenderHelper.Render
   │   ├─ BoxShadow描画
   │   ├─ Background描画（BackgroundSizing考慮）
   │   └─ Border描画（CornerRadius適用）
   └─ 子要素描画
```

### フローチャート

```mermaid
flowchart TD
    A[Render開始] --> B[BorderRenderHelper.Render]
    B --> C{BoxShadow?}
    C -->|Yes| D[シャドウ描画]
    C -->|No| E[Background描画]
    D --> E
    E --> F{CornerRadius > 0?}
    F -->|Yes| G[RoundedRect描画]
    F -->|No| H[Rect描画]
    G --> I[Border描画]
    H --> I
    I --> J[Render完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-38-01 | サイズ計算 | DesiredSize = 子サイズ + Padding + BorderThickness | 常時 |
| BR-38-02 | UseLayoutRounding | trueの場合、BorderThicknessをピクセル境界に丸める | UseLayoutRounding=true時 |
| BR-38-03 | 角丸クリッピング | CornerRadius指定時、ClipToBoundsRadiusとして使用 | CornerRadius > 0時 |
| BR-38-04 | 背景描画領域 | BackgroundSizingに応じて背景の描画範囲を調整 | Background指定時 |

### 計算ロジック

**DesiredSize計算**:
```
DesiredSize.Width = Child.DesiredSize.Width + Padding.Left + Padding.Right + BorderThickness.Left + BorderThickness.Right
DesiredSize.Height = Child.DesiredSize.Height + Padding.Top + Padding.Bottom + BorderThickness.Top + BorderThickness.Bottom
```

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

該当なし（UIコンポーネントのためDB操作は行わない）

## エラー処理

特になし

## パフォーマンス要件

- UseLayoutRounding対応でスケール変更時のキャッシュ無効化
- Compositionビジュアル（CompositionBorderVisual）による効率的なレンダリング

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

特になし

## 備考

- partialクラス構成（Border.cs + Border.partial.cs等）
- IVisualWithRoundRectClipインターフェースで角丸クリッピング対応

---

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

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

### 推奨読解順序

#### Step 1: 基底クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Decorator.cs | `src/Avalonia.Controls/Decorator.cs` | Childプロパティ、Padding処理 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Border.cs | `src/Avalonia.Controls/Border.cs` | メインクラス |

**主要処理フロー**:
- **14行目**: `Border`クラス定義。`Decorator`, `IVisualWithRoundRectClip`を実装
- **20-53行目**: プロパティ定義（Background/BackgroundSizing/BorderBrush/BorderThickness/CornerRadius/BoxShadow）
- **55行目**: `_borderRenderHelper` - 描画ヘルパー
- **63-73行目**: 静的コンストラクタ - AffectsRender/AffectsMeasure登録

#### Step 3: レイアウト処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Border.cs | `src/Avalonia.Controls/Border.cs` | MeasureOverride/ArrangeOverrideメソッド（197-210行目） |

**主要処理フロー**:
- **199行目**: `LayoutHelper.MeasureChild` - 子要素計測（Padding+BorderThickness考慮）
- **209行目**: `LayoutHelper.ArrangeChild` - 子要素配置

**読解のコツ**: LayoutHelperクラスでPaddingとBorderThicknessを考慮したサイズ計算・配置を共通化。

#### Step 4: 描画処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Border.cs | `src/Avalonia.Controls/Border.cs` | Renderメソッド（179-190行目） |
| 4-2 | BorderRenderHelper.cs | `src/Avalonia.Controls/Utils/BorderRenderHelper.cs` | 描画ロジック詳細 |

**主要処理フロー**:
- **181-189行目**: `_borderRenderHelper.Render` - サイズ、ボーダー、角丸、背景、シャドウを渡して描画

#### Step 5: LayoutThickness - UseLayoutRounding対応

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Border.cs | `src/Avalonia.Controls/Border.cs` | LayoutThicknessプロパティ（145-163行目） |

**主要処理フロー**:
- **149行目**: `VerifyScale` - スケール変更検出
- **155-156行目**: `UseLayoutRounding`時の丸め処理

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

```
Border (装飾コンテナ)
    │
    ├─ MeasureOverride()
    │      └─ LayoutHelper.MeasureChild()
    │             └─ Child.Measure(availableSize - Padding - BorderThickness)
    │
    ├─ ArrangeOverride()
    │      └─ LayoutHelper.ArrangeChild()
    │             └─ Child.Arrange(rect with Padding + BorderThickness offset)
    │
    └─ Render()
           └─ _borderRenderHelper.Render()
                  ├─ BoxShadow描画
                  ├─ Background描画（BackgroundSizing考慮）
                  └─ Border描画（CornerRadius適用）
```

### データフロー図

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

BorderThickness ─────────▶ LayoutThickness
UseLayoutRounding ───────▶ (丸め処理)
                              │
                              ▼
Child ───────────────────▶ MeasureOverride()
Padding ──────────────────▶ LayoutHelper.MeasureChild()
                              │
                              ▼
                     DesiredSize
                              │
                              ▼
                     ArrangeOverride()
                              │
                              ▼
Background ──────────────▶ Render()
BorderBrush ──────────────▶ BorderRenderHelper.Render()
CornerRadius ─────────────▶ │
BoxShadow ────────────────▶ │
                              │
                              ▼
                     視覚的出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Border.cs | `src/Avalonia.Controls/Border.cs` | ソース | メインクラス |
| Decorator.cs | `src/Avalonia.Controls/Decorator.cs` | ソース | 基底クラス |
| BorderRenderHelper.cs | `src/Avalonia.Controls/Utils/BorderRenderHelper.cs` | ソース | 描画ヘルパー |
| LayoutHelper.cs | `src/Avalonia.Layout/LayoutHelper.cs` | ソース | レイアウト計算ヘルパー |
| BackgroundSizing.cs | `src/Avalonia.Controls/BackgroundSizing.cs` | ソース | 背景サイズ列挙型 |
| BoxShadows.cs | `src/Avalonia/Media/BoxShadows.cs` | ソース | ボックスシャドウ構造体 |
