syncfusion-winforms-masked-textbox

Syncfusion WinForms での MaskedEditBox の実装

MaskedEditBox コントロールは、あらかじめ定義されたパターンに従って書式付きデータを収集するための専用入力コントロールです。マスク定義によって視覚的なガイドと入力制約を提供するため、電話番号、IP アドレス、SSN など、標準化されたデータ入力に最適です。

MaskedEditBox を使用する場面

次のような場合に、このコントロールを使用してください。

• ユーザー入力を特定のパターンに制限する場合（電話番号：(###) ###-####）
• 予想されるデータ形式を視覚的なプレースホルダーで示す場合
• 別途検証ロジックを用意せずに、ユーザーの入力中に入力内容を検証する場合
• 電話番号、IP アドレス、日付、通貨などの一般的なパターンを扱う場合
• コントロールレベルで無効なデータ入力を防ぐ場合
• アプリケーション全体で一貫した書式を表示する場合

ユーザーが完全に自由な形式でテキストを入力する必要がある場合や、データ形式が予測できない場合は、使用しないでください。

コンポーネントの概要

主な概念

マスク： 次の要素を使用して入力形式を定義する文字列です。

• マスク文字（数字を表す #、文字を表す & などのプレースホルダー）
• リテラル文字（(###) ###-#### の括弧やハイフンなど、固定された記号）

例：

• 米国の電話番号：(###) ###-####
• IP アドレス：###.###.###.###
• 社会保障番号：###-##-####
• 日付（MM/DD/YYYY）：##/##/####

主な機能

• 複数のモード： ClipMode（区切り文字を除去）、InputMode（区切り文字を含める）、UsageMode（プログラムから使用）
• 外観の制御： 境界線、フォント、色、表示オプション
• データ処理： マスクを含む Text と、マスク文字のみの Value を分けて処理
• 区切り文字： 地域形式に対応する日付、小数点、桁区切り、時刻の区切り文字
• イベント： 入力の検証、完了、操作に関するイベント

ドキュメントの案内

実装のニーズに応じて、以下のリファレンスを参照してください。

はじめに

📄 参照先： references/getting-started.md

• インストールとアセンブリのセットアップ
• デザイナーを使用した MaskedEditBox の追加
• コードを使用した MaskedEditBox の追加
• 基本的な初期化

マスクの設定

📄 参照先： references/mask-settings.md

• マスク文字の種類と構文
• 電話番号マスクの作成
• IP アドレスのマスク
• カスタムマスクパターン

動作モード

📄 参照先： references/behavior-modes.md

• ClipMode：出力形式の制御
• InputMode：ユーザー入力の動作
• UsageMode：プログラムからの使用
• ユースケースに適したモードの選択

テキストと値の処理

📄 参照先： references/text-and-value-handling.md

• Text プロパティ（マスクリテラルを含む）
• Value プロパティ（マスク文字のみ）
• DataGroups の設定
• 区切り文字の設定（日付、小数点、桁区切り、時刻）
• 入力検証パターン

外観の設定

📄 参照先： references/appearance-settings.md

• 境界線のスタイルと色
• フォントのプロパティとサイズ
• 表示オプションと可視性
• 読み取り専用モード
• 有効／無効の状態

イベントと検証

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

• 使用可能な MaskedEditBox のイベント
• 入力検証イベント
• 完了イベントとフォーカスイベント
• イベント処理の例

クイックスタートの例

using Syncfusion.Windows.Forms.Tools;

// Create MaskedEditBox for phone number
MaskedEditBox phoneInput = new MaskedEditBox();
phoneInput.Mask = "(###) ###-####";  // US phone format
phoneInput.Location = new Point(10, 10);
phoneInput.Size = new Size(200, 25);
phoneInput.Placeholder = "(123) 456-7890";

// Add to form
this.Controls.Add(phoneInput);

// Access entered value
string phoneValue = phoneInput.Value;  // Without mask characters: "1234567890"
string phoneText = phoneInput.Text;    // With mask: "(123) 456-7890"

一般的なパターン

電話番号（米国形式）

maskedEditBox.Mask = "(###) ###-####";

IP アドレス

maskedEditBox.Mask = "###.###.###.###";

社会保障番号

maskedEditBox.Mask = "###-##-####";

日付（MM/DD/YYYY）

maskedEditBox.Mask = "##/##/####";

郵便番号（米国）

maskedEditBox.Mask = "#####";
// Optional: Extended format
maskedEditBox.Mask = "#####-####";

主なプロパティ

プロパティ	目的	例
Mask	入力形式のパターンを定義します	"(###) ###-####"
Text	マスク文字を含むテキストを取得または設定します	"(123) 456-7890"
Value	マスク文字を含まないテキストを取得または設定します	"1234567890"
ClipMode	マスクを削除したときの出力形式を制御します	ClipModes.IncludeLiterals
InputMode	ユーザー入力の動作を制御します	InputModes.IgnoreSeparators
Border3DStyle	境界線の外観	Border3DStyle.Raised
Font	フォントのプロパティ（名前、サイズ、スタイル）	new Font("Arial", 10)
ForeColor	テキストの色	Color.Black
BackColor	背景色	Color.White
ReadOnly	ユーザー入力を禁止します	true/false
Enabled	コントロールの有効／無効を切り替えます	true/false

一般的な使用例

1. 検証機能付きの電話番号入力

コントロールのレベルで無効な入力を防ぎながら、標準形式で電話番号を収集します。

2. 国際形式への対応

区切り文字のプロパティを使用して、地域ごとの区切り文字や日付／時刻形式を設定します。

3. 財務データの入力

通貨、口座番号、または精度を制御した書式付き数値データの入力に使用します。

4. 医療／行政機関のフォーム

医療 ID、社会保障番号、登録コードに特定の形式を適用します。

5. ネットワーク設定

固定形式が必要な IP アドレス、MAC アドレス、その他のネットワーク識別子に使用します。

---

次のステップ：

1. getting-started.mdから始めて、コントロールをセットアップします
2. mask-settings.mdからマスク形式を選択します
3. behavior-modes.mdで動作を設定します
4. text-and-value-handling.mdでデータを処理します
5. appearance-settings.mdで外観をカスタマイズします
6. events-and-validation.mdからイベントを追加します