syncfusion-winui-masked-textbox

MaskedTextBox の実装

Syncfusion® WinUI MaskedTextBox（SfMaskedTextBox）の実装ガイド — カスタマイズ可能なマスクパターンを使用してユーザー入力を制限および書式設定する高度な入力コントロールです。エラー表示と検証に対応し、シンプルなマスクと正規表現ベースのマスクの両方をサポートします。

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

次のような場合にこのスキルを使用します。

• マスク付き入力フィールドを作成する：WinUI アプリケーションでパターン検証を行います
• 電話番号フィールドを実装する：(555) 123-4567 のような書式設定済みの入力にします
• メールアドレスを検証する：正規表現パターンを使用します
• 日付入力フィールドを作成する：視覚的なプレースホルダーを表示します
• プロダクトキー入力を作成する：XXXXX-XXXXX-XXXXX のような形式にします
• SSN、クレジットカード、IP アドレスを検証する：カスタムマスクを使用します
• エラー表示を行う：アイコンとツールチップを表示します
• プロンプト文字をカスタマイズする：空のフィールドに表示する文字を設定します
• 値を書式設定する：表示とクリップボード操作に使用する形式を設定します
• 入力フィールドにヘッダーと説明を追加する

このスキルでは、マスクの種類、検証、エラー処理、カスタマイズなど、MaskedTextBox の実装全体について説明します。

コンポーネントの概要

コントロール： SfMaskedTextBox
名前空間： Syncfusion.UI.Xaml.Editors
NuGet パッケージ： Syncfusion.Editors.WinUI
プラットフォーム： WinUI 3 Desktop（.NET 5+）

SfMaskedTextBox コントロールには、次の機能があります。

• マスクの種類 — シンプル（固定長）および RegEx（可変長）パターン
• シンプルなマスク — 組み込み要素：0（数字）、L（文字）、A（英数字）など
• RegEx マスク — 複雑な検証に対応する正規表現パターンの完全なサポート
• プロンプト文字 — カスタマイズ可能なプレースホルダー文字（既定値は「_」）
• 値の書式設定 — リテラル文字やプロンプト文字を含む値の表示方法を制御します
• エラー表示 — 組み込みのエラーの種類（Warning、Success、Critical など）
• カスタムエラー — 検証用のカスタムアイコンと境界線の色
• ヘッダーと説明 — UX を向上させるラベルとヘルプテキスト
• イベント — リアルタイム検証に使用する ValueChanging と ValueChanged

コントロールの構造

SfMaskedTextBox
├── Header (optional) - Label above the control
├── Input Area - Masked text entry with prompt characters
├── Error Icon (optional) - Validation feedback indicator
└── Description (optional) - Help text below the control

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

はじめに

📄 参照： references/getting-started.md

• インストールと NuGet パッケージのセットアップ
• XAML とコードビハインドでのコントロールの追加
• 名前空間のインポート
• シンプルなマスクの例（日付パターン）
• RegEx マスクの例（メールアドレスパターン）
• プロンプト文字の設定
• Value プロパティの設定

マスクの種類

📄 参照： references/mask-types.md

• 固定長入力向けのシンプルなマスクの種類
• シンプルなマスク要素（0、9、#、L、?、C、A、<、>）
• 要素の説明と使用方法
• 可変長入力向けの RegEx マスクの種類
• RegEx パターン要素と構文
• 電話番号マスクの例
• メールアドレスパターンの例
• プロダクトキーパターン
• カスタムマスクの作成

値の書式設定

📄 参照： references/value-formatting.md

• Value プロパティの使用方法
• ValueMaskFormat オプション
• IncludeLiterals 形式
• IncludePrompt 形式
• ExcludePromptAndLiterals 形式
• クリップボードへのコピー動作
• 貼り付け操作
• 書式設定済みの値と未加工の値の取得

エラー表示

📄 参照： references/error-indication.md

• ErrorType プロパティ
• 組み込みのエラーの種類（None、Default、Warning、Information、Critical、Success）
• 検証結果に応じたエラーの種類の設定
• カスタムエラーの種類
• CustomErrorIcon プロパティ
• CustomErrorBorderBrush プロパティ
• ツールチップメッセージ用の ErrorContent プロパティ

📄 参照： references/error-indication-validation.md

• ValueChanged イベントを使用した動的な検証
• 検証シナリオ（必須フィールド、リアルタイム、複数フィールド、日付範囲）
• エラー状態の解除
• フォーム検証の完全な例

カスタマイズ

📄 参照： references/customization.md

• ラベル用の Header プロパティ
• カスタムヘッダーデザイン用の HeaderTemplate
• ヘルプテキスト用の Description プロパティ
• コントロールのスタイル設定
• カスタムテンプレート
• 外観のカスタマイズ

イベント

📄 参照： references/events.md

• 値の変更イベント（変更前）
• イベント引数とプロパティ
• Cancel による無効な入力の防止
• リアルタイムの文字フィルタリング
• 条件付き入力ルール

📄 参照： references/events-valuechanged.md

• 値の変更イベント（変更後）
• ValueChanging と ValueChanged の組み合わせ
• 検証シナリオ（必須フィールド、フィールド間、非同期、日付範囲）
• 連絡先フォームの完全な例

クイックスタートの例

検証付き電話番号入力

<syncfusion:SfMaskedTextBox Width="200"
                            Header="Phone Number"
                            MaskType="Simple"
                            Mask="(000) 000-0000"
                            PromptChar="#"
                            ErrorType="Warning"
                            Description="Enter your 10-digit phone number"
                            ValueChanging="OnPhoneNumberChanging" />

private void OnPhoneNumberChanging(object sender, MaskedTextBoxValueChangingEventArgs e)
{
    // Show success icon for valid input, warning otherwise
    var maskedTextBox = sender as SfMaskedTextBox;
    maskedTextBox.ErrorType = e.IsValid ? ErrorType.Success : ErrorType.Warning;
}

一般的なパターン

パターン 1：シンプルなマスクを使用した日付入力

<syncfusion:SfMaskedTextBox Width="200"
                            Header="Date of Birth"
                            MaskType="Simple"
                            Mask="00/00/0000"
                            Value="12/31/1990" />

使用する場面： 固定形式の日付入力（MM/DD/YYYY）

パターン 2：正規表現によるメールアドレスの検証

<syncfusion:SfMaskedTextBox Width="300"
                            Header="Email Address"
                            MaskType="RegEx"
                            Mask="[A-Za-z0-9._%-]+@[A-Za-z0-9]+\.[A-Za-z]{2,3}"
                            ErrorType="Information"
                            ValueChanging="OnEmailValidation" />

使用する場面： パターン検証を伴う可変長の入力

パターン 3：大文字変換を伴うプロダクトキー

<syncfusion:SfMaskedTextBox Width="300"
                            Header="Product Key"
                            MaskType="Simple"
                            Mask=">AAAAA-AAAAA-AAAAA-AAAAA"
                            Description="Format: XXXXX-XXXXX-XXXXX-XXXXX" />

使用する場面： 書式設定されたシリアル番号またはライセンスキー（> によって大文字に変換）

パターン 4：アイコンと境界線を使用したカスタムエラー

<syncfusion:SfMaskedTextBox Width="250"
                            MaskType="Simple"
                            Mask="000-00-0000"
                            ErrorType="Custom"
                            CustomErrorIcon="ms-appx:///Assets/ErrorIcon.png"
                            CustomErrorBorderBrush="Red"
                            ErrorContent="Invalid SSN format" />

使用する場面： エラー状態に独自のブランディングが必要な場合

パターン 5：書式設定された表示を使用するクレジットカード

<syncfusion:SfMaskedTextBox Width="200"
                            Header="Credit Card"
                            MaskType="Simple"
                            Mask="0000 0000 0000 0000"
                            ValueMaskFormat="ExcludePromptAndLiterals" />

使用する場面： 書式設定された入力を表示しながら、未加工の値を返す場合

主要なプロパティ

プロパティ	型	説明
Mask	string	入力を制限するために使用するパターン（例："00/00/0000"）
MaskType	MaskedTextBoxMaskType	シンプルまたは正規表現のマスクタイプ
Value	string	現在の入力値
PromptChar	char	マスクの空の位置に表示する文字（既定値 '_'）
ValueMaskFormat	MaskedTextBoxValueMaskFormat	値の書式設定方法（リテラル、プロンプト）
ErrorType	ErrorType	検証フィードバックのタイプ（なし、警告、成功など）
CustomErrorIcon	ImageSource	カスタムエラータイプ用のカスタムエラーアイコン
CustomErrorBorderBrush	Brush	エラー用のカスタム境界線ブラシ
ErrorContent	object	エラーアイコンにカーソルを合わせたときに表示するツールチップの内容
Header	object	コントロールの上に表示するラベル
HeaderTemplate	DataTemplate	ヘッダー用のカスタムテンプレート
Description	object	コントロールの下に表示するヘルプテキスト

一般的な使用例

使用例 1：複数の検証付き入力を含むフォーム

電話番号、メールアドレス、SSN の各フィールドに適切なマスクと検証アイコンを設定した登録フォームを作成します。

使用例 2：国際電話番号

正規表現マスクを使用して、国番号を含むさまざまな国際電話番号形式に対応します。

使用例 3：クレジットカード入力

書式設定された表示（4 桁ごとのグループ）と、処理用の未加工の値を備えたクレジットカード入力を実装します。

使用例 4：IP アドレス入力

シンプルなマスク "000.000.000.000" と検証を使用して、各オクテットが 0～255 の範囲内であることを確認します。

使用例 5：時刻入力

24 時間形式と AM/PM 表示に対応する "00:00 >LL" マスクを使用して、時刻入力フィールドを作成します。

使用例 6：製品シリアル番号スキャナー

大文字変換とセグメント検証に対応する、バーコード互換の入力を実装します。

使用例 7：カスタム検証メッセージ

ErrorContent を使用して、特定の検証ルールに応じた状況に即したエラーメッセージを表示します。

使用例 8：多言語サポート

電話番号や郵便番号に関する各地域の要件に適応する正規表現パターンを使用します。

トラブルシューティング

問題：マスクが入力を受け付けない

• マスクパターンが想定される入力の種類（数字または文字）と一致していることを確認します
• MaskType が正しく設定されていることを確認します（Simple または RegEx）
• 選択した MaskType でマスク要素が有効であることを確認します

問題：Value プロパティが更新されない

• 変更を追跡するには ValueChanged イベントを使用します
• 取得した値が正しくないように見える場合は、ValueMaskFormat を確認します
• 双方向バインディングを設定します：Value="{x:Bind Property, Mode=TwoWay}"

問題：エラーアイコンが表示されない

• ErrorType に None 以外の値を設定します
• Custom タイプの場合は、CustomErrorIcon を指定します
• アイコンを表示するのに十分な幅がコントロールにあることを確認します

問題：RegEx マスクが正しく検証されない

• XAML 内の特殊文字をエスケープします（ドットをそのまま表示するには \\. を使用します）
• マスクで使用する前に、正規表現パターンを単独でテストします
• RegEx マスクは可変長の入力用であることに注意します

問題：プロンプト文字が値に表示される

• ValueMaskFormat プロパティを調整します
• 値をきれいな形式で取得するには ExcludePromptAndLiterals を使用します
• プロンプトが意図的に含まれているか確認します

問題：Header または Description が表示されない

• プロパティが XAML またはコードで設定されていることを確認します
• コントロールの高さがヘッダーや説明の表示に必要なスペースを確保していることを確認します
• カスタマイズしている場合は、HeaderTemplate の構文が正しいことを確認します