# 機能設計書 29-MaskedTextBox

## 概要

本ドキュメントは、AvaloniaフレームワークにおけるMaskedTextBoxコントロールの機能設計を記載する。MaskedTextBoxは、入力マスク（フォーマット）を指定してテキスト入力を制御するテキストボックスコントロールである。

### 本機能の処理概要

MaskedTextBoxは、電話番号、郵便番号、日付、クレジットカード番号など、特定のフォーマットで入力を制限・誘導するテキストボックスコントロールである。.NETのMaskedTextProviderを使用してマスク処理を行い、入力文字の検証とフォーマットを自動的に行う。

**業務上の目的・背景**：
業務アプリケーションにおいて、電話番号や郵便番号など決まったフォーマットでの入力が必要な場面は多い。MaskedTextBoxは、入力フォーマットを強制することで、データの一貫性を保ち、入力ミスを防止する。

**機能の利用シーン**：
- 電話番号の入力（000-0000-0000）
- 郵便番号の入力（000-0000）
- 日付の入力（0000/00/00）
- クレジットカード番号の入力（0000-0000-0000-0000）
- 社会保障番号・マイナンバーの入力
- IPアドレスの入力

**主要な処理内容**：
1. マスクパターンに基づく入力制御
2. リテラル文字の自動挿入
3. 入力位置の自動移動
4. パスワードマスク（PasswordChar）
5. プロンプト文字（PromptChar）の表示
6. カルチャに応じた数値・日付フォーマット

**関連システム・外部連携**：
- System.ComponentModel.MaskedTextProvider

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

## 関連画面

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

## 機能種別

UI操作 / 入力コントロール / マスク付きテキスト入力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Mask | string | No | マスクパターン | MaskedTextProvider形式 |
| Text | string | No | マスクされたテキスト | - |
| PromptChar | char | No | 未入力位置に表示する文字 | デフォルト: '_' |
| PasswordChar | char | No | パスワード表示文字 | デフォルト: '\0' |
| AsciiOnly | bool | No | ASCII文字のみ許可 | デフォルト: false |
| HidePromptOnLeave | bool | No | フォーカスロスト時にプロンプトを非表示 | デフォルト: false |
| ResetOnPrompt | bool | No | プロンプト文字入力で位置をリセット | デフォルト: true |
| ResetOnSpace | bool | No | スペース入力で位置をリセット | デフォルト: true |
| Culture | CultureInfo | No | カルチャ情報 | デフォルト: CurrentCulture |

### マスク文字の種類

| 文字 | 説明 |
|------|------|
| 0 | 必須の数字（0-9） |
| 9 | オプションの数字（0-9）またはスペース |
| # | オプションの数字、スペース、+/- |
| L | 必須の文字（a-Z） |
| ? | オプションの文字（a-Z） |
| & | 必須の任意文字 |
| C | オプションの任意文字 |
| A | 必須の英数字 |
| a | オプションの英数字 |
| . | 小数点（カルチャ依存） |
| , | 桁区切り（カルチャ依存） |
| : | 時刻区切り（カルチャ依存） |
| / | 日付区切り（カルチャ依存） |
| $ | 通貨記号（カルチャ依存） |
| < | 以降を小文字に変換 |
| > | 以降を大文字に変換 |
| \\ | エスケープ（次の文字をリテラルとして扱う） |

### 入力データソース

- ユーザーによるテキスト入力
- クリップボードからの貼り付け
- プログラムによるText設定
- データバインディングによる制御

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Text | string | マスクされたテキスト（リテラル含む） |

### 出力先

- UI表示（マスクされたテキスト表示）
- TextChangedイベントの発行

## 処理フロー

### 処理シーケンス

```
1. マスク設定
   └─ MaskedTextProvider初期化
2. テキスト入力検出
   └─ OnTextInput/OnKeyDown
3. 入力文字検証
   └─ MaskedTextProvider.VerifyChar
4. 文字挿入
   └─ MaskedTextProvider.InsertAt
5. テキスト更新
   └─ Text = MaskedTextProvider.ToString()
6. キャレット位置更新
   └─ 次の入力可能位置へ移動
7. イベント発行
   └─ TextChanged
```

### フローチャート

```mermaid
flowchart TD
    A[テキスト入力] --> B{マスク設定あり?}
    B -->|No| C[通常のTextBox動作]
    B -->|Yes| D[入力位置取得]
    D --> E{入力可能位置?}
    E -->|No| F[次の入力可能位置を検索]
    E -->|Yes| G[MaskedTextProvider.VerifyChar]
    F --> G
    G --> H{検証成功?}
    H -->|No| I[入力拒否]
    H -->|Yes| J[MaskedTextProvider.InsertAt]
    J --> K[Text更新]
    K --> L[キャレット位置更新]
    L --> M[TextChangedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | マスク検証 | マスクパターンに合致しない入力は拒否 | 常時適用 |
| BR-002 | リテラル自動挿入 | 入力位置がリテラル文字の場合、自動的にスキップ | 常時適用 |
| BR-003 | カルチャ適用 | 小数点、桁区切り等はCultureに従う | 常時適用 |
| BR-004 | 大小文字変換 | </>マスク文字以降の入力を大/小文字に変換 | マスク設定時 |
| BR-005 | フォーカスロスト | HidePromptOnLeave=trueの場合、プロンプト文字を非表示 | 設定時 |

### 計算ロジック

入力可能位置の検索：
```
nextPosition = MaskedTextProvider.FindEditPositionFrom(currentPosition, direction)
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 無効な入力 | マスクパターンに合致しない入力 | 入力を拒否（ビープ音なし） |
| - | 無効なマスク | 不正なマスクパターン | 例外をスロー |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- 入力に即座に反応する必要がある
- マスク処理はMaskedTextProviderに委譲

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

- PasswordCharを設定することで、パスワード入力として使用可能
- 入力値の検証はマスクパターンに依存し、追加のセキュリティ検証は別途必要

## 備考

- .NETのMaskedTextProviderをラップしているため、Windows Forms/WPFと同様のマスク機能を提供
- カルチャに依存するマスク文字（.,:/$）は実行環境のカルチャに応じて変化

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: MaskedTextBoxはTextBoxを継承し、内部でMaskedTextProviderを使用してマスク処理を行う。

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

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

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

**主要処理フロー**:
1. **プロパティ定義**: Mask、PromptChar、PasswordChar、AsciiOnly、Culture等
2. **MaskedTextProvider**: マスク処理を担当する.NETクラス

#### Step 3: マスク処理を理解する

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

**主要処理フロー**:
- MaskedTextProvider.VerifyCharで入力文字を検証
- MaskedTextProvider.InsertAtで文字を挿入
- MaskedTextProvider.ToStringでフォーマット済みテキストを取得

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

```
MaskedTextBox
    │
    ├─ OnPropertyChanged (Maskプロパティ)
    │      └─ MaskedTextProvider初期化
    │
    ├─ OnTextInput
    │      ├─ MaskedTextProvider.VerifyChar
    │      ├─ MaskedTextProvider.InsertAt
    │      └─ Text更新
    │
    ├─ OnKeyDown
    │      ├─ Delete/Backspace処理
    │      └─ MaskedTextProvider.RemoveAt
    │
    └─ OnGotFocus/OnLostFocus
           └─ プロンプト文字の表示/非表示制御
```

### データフロー図

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

Mask設定 ───────────▶ MaskedTextProvider初期化
                              │
                              ▼
テキスト入力 ──────────▶ OnTextInput
                              │
                              ▼
                       VerifyChar（検証）
                              │
                              ├─▶ 検証失敗: 入力拒否
                              │
                              ▼
                       InsertAt（挿入）
                              │
                              ▼
                       ToString（フォーマット）
                              │
                              ▼
                       Text更新 ──▶ TextChangedイベント
                              │
                              ▼
                       キャレット位置更新 ──▶ UI表示更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MaskedTextBox.cs | `src/Avalonia.Controls/MaskedTextBox.cs` | ソース | メインコントロールクラス |
| TextBox.cs | `src/Avalonia.Controls/TextBox.cs` | ソース | 基底クラス |
| MaskedTextBox.xaml | `src/Avalonia.Themes.Fluent/Controls/MaskedTextBox.xaml` | テンプレート | Fluentテーマのテンプレート（存在する場合） |
