syncfusion-maui-masked-entry

.NET MAUI Masked Entry の実装

Syncfusion .NET MAUI Masked Entry（SfMaskedEntry）は、カスタマイズ可能なマスクパターンを使用して、ユーザー入力を制限および書式設定する高度な入力コントロールです。電話番号、日付、メールアドレス、製品キーなどの構造化データを入力する際に、自動検証、書式設定、視覚的なフィードバックを提供します。

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

次のようなニーズがある場合に、このスキルを使用してください。

• 書式設定された入力フィールド：電話番号、日付、時刻、SSN、クレジットカード番号、ZIP コード、製品キー
• 入力文字の制限：特定の文字（数字、英字、英数字）のみを受け付ける
• パターン検証：固定長または可変長のパターンに対して入力を検証する
• 自動書式設定：入力中に区切り文字、デリミター、書式を適用する
• カルチャ固有の入力：通貨記号、日付／時刻の区切り文字、小数点の書式を扱う
• マスキング付きパスワードフィールド：カスタマイズ可能な遅延時間で文字の表示／非表示を切り替える
• メールアドレスと URL の検証：複雑な検証に正規表現パターンを使用する
• データ入力フォーム：入力ガイドと即時フィードバックで UX を向上させる
• アクセシビリティ要件：プロンプトと検証で、明確な入力内容を示す

コンポーネントの概要

主な機能：

• 2 種類のマスクタイプ：Simple（固定パターン）と RegEx（柔軟なパターン）
• 入力位置の候補を示す、カスタマイズ可能なプロンプト文字
• 柔軟な値の書式設定（プロンプトとリテラルの包含／除外）
• 複数の検証モードによるリアルタイム検証
• 入力の監視と制御に対応した豊富なイベントシステム
• 幅広いカスタマイズ（色、フォント、境界線、クリアボタン）
• 国際的な書式に対応するカルチャサポート
• 表示制御付きのパスワードマスキング
• 最新の Liquid Glass エフェクトとの統合
• アクセシビリティとオートメーションへの完全対応

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

はじめに

📄 参照： references/getting-started.md

• インストールと NuGet パッケージのセットアップ
• MauiProgram.cs でのハンドラー登録
• MaskedEntry の基本的な実装
• マスクパターンとタイプの設定
• プロンプト文字の設定
• 値の設定と取得
• 最初に動作するサンプル

マスクタイプとパターン

📄 参照： references/mask-types.md

• Simple マスクタイプと要素（0、9、#、L、?、C、A、<、>）
• RegEx マスクタイプとパターン
• 要素の完全なリファレンステーブル
• サンプル：電話番号、日付、メールアドレス、製品キー
• 大文字・小文字の変換と特殊文字
• Simple と RegEx の使い分け
• パフォーマンスに関する考慮事項

値の書式設定と表示

📄 参照： references/value-formatting.md

• ValueMaskFormat のオプション
• ExcludePromptAndLiterals（入力された文字のみ）
• IncludePrompt（プロンプト文字を含む）
• IncludeLiterals（区切り文字を含む）
• IncludePromptAndLiterals（すべての文字）
• データ保存と表示での使い分け
• 視覚的な比較とサンプル

検証とイベント

📄 参照： references/validation-and-events.md

• ValidationMode（KeyPress、LostFocus）
• 検証ステータスを示す HasError プロパティ
• Focused／Unfocused イベント
• Focus() メソッドと Unfocus() メソッド
• ValueChanging イベント（キャンセル可能。IsValid、NewValue、OldValue、Cancel を含む）
• ValueChanged イベント（IsMaskCompleted を含む）
• Completed イベント（リターンキー）
• ClearButtonClicked イベント
• イベントのライフサイクルとベストプラクティス

カスタマイズとスタイル設定

📄 参照： references/customization.md

• クリアボタンの設定（表示、色、カスタムパス）
• フォントプロパティ（サイズ、属性、ファミリー）
• テキストとプレースホルダーのスタイル設定
• 境界線のカスタマイズ（ストローク、表示）
• 背景と透明度
• カーソル位置の制御
• キーボードの設定
• SelectAllOnFocus の動作
• IsReadOnly モード
• リターンキーの処理（ReturnType、ReturnCommand）
• UI テスト用の AutomationId サポート
• プラットフォーム固有の考慮事項

高度な機能

📄 参照： references/advanced-features.md

• カルチャーのサポート（通貨、日付／時刻の区切り文字、小数点／桁区切り記号）
• HidePromptOnLeave による、よりすっきりとした UI
• パスワードのマスキング（PasswordChar、PasswordDelayDuration）
• Liquid Glass Effect の統合
• RTL のサポート
• アクセシビリティ機能
• パフォーマンスの最適化
• エッジケースとトラブルシューティング