syncfusion-wpf-maskedtextbox

Syncfusion WPF MaskedTextBox（SfMaskedEdit）の実装

WPF MaskedTextBox（SfMaskedEdit）は、マスクパターンを使用してユーザー入力を特定の形式に制限する、高度な入力コントロールです。電話番号、IP アドレス、製品 ID、日付、その他の書式付きデータ入力用のテンプレート作成に最適です。

このスキルを使用する場面

次のような場合に、このスキルを使用してください。

• カスタム検証を行わずに、入力を特定の形式に制限する
• 電話番号、メールアドレス、日付、通貨用の書式付き入力フィールドを実装する
• Simple または RegEx のマスクタイプを使用してマスクパターンを作成する
• キー押下時またはフォーカス喪失時にユーザー入力を検証する
• リテラルやプロンプト文字の有無を指定して値を書式設定する
• 入力が無効な場合にエラーインジケーターを表示する
• ユーザー入力を案内するウォーターマークを追加する
• 色、境界線、テーマなどの外観をカスタマイズする
• 国際化アプリケーションで RTL レイアウトをサポートする
• イベント通知を使用して値の変更を処理する

コンポーネントの概要

SfMaskedEdit は、次の機能を提供します。

• 複数のマスクタイプ： Simple および RegEx のパターン
• 柔軟な検証： KeyPress または LostFocus の検証モード
• 値の書式設定： プロンプトとリテラルの包含または除外
• 視覚的なフィードバック： エラー境界線、プロンプト文字、ウォーターマーク
• 包括的なカスタマイズ： 色、テーマ、テンプレート
• MVVM のサポート： データバインディングとプロパティ変更通知

アセンブリ： Syncfusion.SfInput.WPF、Syncfusion.SfShared.WPF
名前空間： Syncfusion.Windows.Controls.Input

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• アセンブリの配置と NuGet のインストール
• デザイナー、XAML、C# からの SfMaskedEdit の追加
• 基本的な設定とセットアップ
• 最初のマスク付きテキストボックスの例
• ValueChanged イベントの処理

マスクパターンと入力制限

📄 参照： references/mask-patterns-input-restriction.md、references/mask-patterns-advanced.md

• マスク要素のリファレンス（[], \d, \w, {n}, +, *, ? など）
• カスタムマスクパターンの作成
• (?=) と (?! ) を使用した特定の値の許可または制限
• 豊富なマスクの例（電話番号、メールアドレス、通貨、日付など）
• 入力検証モード（KeyPress と LostFocus の比較）
• 検証結果と HasError プロパティ
• PromptChar と ShowPromptOnFocus の設定

値の管理

📄 参照： references/value-management.md、references/value-management-advanced.md

• Value プロパティの設定と取得
• ValueMaskFormat のオプション：
  • ExcludePromptAndLiterals
  • IncludeLiterals
  • IncludePrompt
  • IncludePromptAndLiterals
• 値変更の通知
• 書式付き値を使用したクリップボード操作

外観とカスタマイズ

📄 参照： references/appearance-customization.md、references/appearance-customization-themes.md

• Background、Foreground、SelectionBrush
• CaretBrush と BorderBrush のカスタマイズ
• 検証フィードバック用の ErrorBorderBrush
• RTL サポート用の FlowDirection
• Watermark と WatermarkTemplate
• テーマの統合とスタイル設定

クイックスタートの例

電話番号マスク

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Grid>
        <syncfusion:SfMaskedEdit 
            x:Name="phoneNumber"
            Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}" 
            MaskType="RegEx"
            Value="4553456789"
            PromptChar="_"
            Width="200" 
            Height="30"
            ValueChanged="PhoneNumber_ValueChanged"/>
    </Grid>
</Window>

using Syncfusion.Windows.Controls.Input;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
    }

    private void PhoneNumber_ValueChanged(object sender, EventArgs e)
    {
        var maskedEdit = sender as SfMaskedEdit;
        if (!maskedEdit.HasError)
        {
            // Use formatted value: (455) 345-6789
            string formattedPhone = maskedEdit.Value;
        }
    }
}

よく使われるパターン

主なパターンには、メールアドレス、通貨、日付、プロダクトキー、値の書式設定があります。XAML とコードの完全なサンプルを含む 25 件以上の詳しいパターン例については、マスクパターンと入力制限を参照してください。

主なプロパティ

主なプロパティには、Mask（パターン）、MaskType（Simple／RegEx）、Value（書式設定済みの出力）、ValueMaskFormat（書式の制御）、ValidationMode（KeyPress／LostFocus）、HasError（検証ステータス）、PromptChar（未入力箇所の表示文字）、ErrorBorderBrush（エラー表示）、Watermark（プレースホルダーテキスト）があります。プロパティの詳細と25種類以上のマスクパターンの例については、はじめにとマスクパターンをご覧ください。

よくある使用例

• データ入力フォーム： 連絡先情報、財務データ、ID番号を自動で書式設定します
• 電話番号／財務情報： アプリ全体で書式を統一し、通貨やパーセントの形式を強制します
• 製品登録： 製品キーやシリアル番号を検証します
• 日付／時刻： RegEx 検証を使い、DatePicker より柔軟なカスタム形式を設定します
• 国際化： FlowDirection による RTL 対応や、地域に応じた日付／電話番号の形式に対応します
• リアルタイム検証： 即座にフィードバックを返す場合は KeyPress、入力を妨げにくくする場合は LostFocus を使用します

イベント

イベント	説明
ValueChanged	Value プロパティが変更されたときに発生します（ValidationMode に基づきます）
LostFocus	標準の WPF イベントです。LostFocus 検証モードで役立ちます

ベストプラクティス

1. 適切な MaskType を選択する： 複雑なパターンには RegEx、基本的な用途には Simple を使用します
2. ValueMaskFormat を早めに設定する： Value プロパティにアクセスする前に書式を決定します
3. 視覚的なフィードバックを提供する： ErrorBorderBrush と Watermark を使って UX を向上させます
4. UX に合った検証モードを選ぶ： 即時にフィードバックを返す場合は KeyPress、入力を妨げにくくする場合は LostFocus を使用します
5. カスタムパターンを文書化する： 保守性を高めるため、複雑な RegEx マスクにはコメントを付けます
6. エッジケースをテストする： 入力が空の場合、一部だけ入力された場合、境界値の場合の動作を確認します
7. ShowPromptOnFocus を使用する： 想定される入力形式をより分かりやすくするため、有効にします

---

次のステップ： 用途に合わせて上記のリファレンスファイルを選ぶか、初期設定については getting-started.md から始めてください。