このドキュメントはアーカイブされており、メンテナンスされていません。

MaskedTextBox クラス

更新 : 2007 年 11 月

適切なユーザー入力と不適切なユーザー入力を区別するには、マスクを使用します。

名前空間 :  System.Windows.Forms
アセンブリ :  System.Windows.Forms (System.Windows.Forms.dll 内)

[ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch)]
[ComVisibleAttribute(true)]
[DefaultBindingPropertyAttribute("Text")]
public class MaskedTextBox : TextBoxBase
/** @attribute ClassInterfaceAttribute(ClassInterfaceType.AutoDispatch) */
/** @attribute ComVisibleAttribute(true) */
/** @attribute DefaultBindingPropertyAttribute("Text") */
public class MaskedTextBox extends TextBoxBase
public class MaskedTextBox extends TextBoxBase

MaskedTextBox クラスは、ユーザー入力を受け入れまたは拒否するための宣言構文をサポートする、拡張された TextBox コントロールです。Mask プロパティを使用すると、アプリケーションでカスタム検証ロジックを作成しなくても、次の入力を指定できます。

  • 必須の入力文字。

  • オプションの入力文字。

  • マスク内の特定の位置で想定される入力の種類。たとえば、数字、英字、英数字など。

  • マスク リテラル。つまり MaskedTextBox に直接表示される文字。たとえば、電話番号のハイフン (-)、価格の通貨記号など。

  • 入力文字の特殊処理。たとえば、英字を大文字に変換するなど。

実行時に MaskedTextBox コントロールが表示される場合、マスクは一連のプロンプト文字およびオプションのリテラル文字として表されます。編集可能な各マスク位置は、必須またはオプションの入力を表し、単一のプロンプト文字を使用して表示されます。たとえば、シャープ記号 (#) は、数字入力のプレースホルダとしてよく使用されます。PromptChar プロパティを使用すると、カスタム プロンプト文字を指定できます。HidePromptOnLeave プロパティは、コントロールが入力フォーカスを失ったときにプロンプト文字が表示されるかどうかを決定します。

ユーザーがマスクされたテキスト ボックスに入力すると、有効な入力文字はそれぞれのプロンプト文字に順に置換されます。ユーザーが無効な文字を入力すると、置換は行われません。BeepOnError プロパティが true に設定されている場合、ビープ音が出され、MaskInputRejected イベントが発生します。このイベントを処理すると、独自のカスタム エラー ロジックを指定できます。

現在の挿入位置がリテラル文字の場合、複数のオプションを使用できます。

  • プロンプト文字以外の文字を入力すると、リテラルは自動的にスキップされ、入力文字は、次のプロンプト文字で表される次の編集可能な位置に自動的に適用されます。

  • AllowPromptAsInput プロパティが true の場合、プロンプト文字を入力すると、入力はプロンプト文字を上書きし、挿入位置はマスク内の次の位置に移動します。

  • 方向キーを使用すると、前の位置または後続の位置に移動できます。

MaskFull プロパティを使用すると、ユーザーが必須の入力をすべて入力したかどうかを検証できます。Text プロパティは、マスクおよび TextMaskFormat プロパティに従って書式設定されたユーザーの入力を常に取得します。

実際には、MaskedTextBox コントロールは、MaskedTextProvider プロパティで指定された System.ComponentModel.MaskedTextProvider クラスに対するすべてのマスク処理を遅延します。この標準のプロバイダは、サロゲートおよび垂直方向の組み合わせ文字を除くすべての Unicode 文字をサポートします。ただし、AsciiOnly プロパティを使用すると、入力を文字セット a ~ z、A ~ Z、および 0 ~ 9 に制限できます。

マスクは、ユーザーの入力が特定の型に対する有効な値を表すことを必ずしも保証していません。たとえば、年齢に対して -9 が入力されることがあります。その値の型のインスタンスを ValidatingType プロパティに割り当てると、ユーザーの入力が有効な値を表すかどうかを検証できます。TypeValidationCompleted イベントを監視すると、無効な値が含まれる場合にユーザーが MaskedTextBox からフォーカスを解除するかどうかを検出できます。型の検証が正常に行われると、TypeValidationEventArgs パラメータの ReturnValue プロパティを通じて値を表すオブジェクトを使用できます。

TextBox コントロールと同様、MaskedTextBox では、いくつかの一般的なショートカット キーが使用できません。たとえば、Ctrl + R (右揃え)、Ctrl + L (左揃え)、Ctrl + L (中央揃え) の各キーは使用できません。

Visual Basic 6.0 との互換性

MaskedTextBox は、Visual Basic 6.0 のマスク エディット コントロール のほとんどの機能を保持するようにデザインされています。マスク エディット コントロールの一般的なプロパティと、MaskedTextBox での等価のプロパティの一覧を次の表に示します。

マスク エディット コントロール (Visual Basic 6.0) プロパティ

等価の MaskedTextBox (.NET Framework) プロパティ

AllowPrompt プロパティ

AllowPromptAsInput

AutoTab プロパティ

なし

ClipMode プロパティ

CutCopyMaskFormat

ClipText プロパティ

Text (TextMaskFormatExcludePromptAndLiterals に設定されている場合)

Format プロパティ

なし

FormattedText プロパティ

Text (TextMaskFormatIncludePromptAndLiterals に設定されている場合)

Mask プロパティ

Mask

PromptChar プロパティ

PromptChar

PromptInclude プロパティ

ResetOnPrompt

ValidationError イベント

MaskInputRejected

注意 :

MaskedTextBox コントロールは、複数行の構成や元に戻す機能をサポートしていません。ただし、これらの機能に関連付けられたメンバが、TextBoxBase 基本クラスとの互換性のために保持されていますが、これらのメンバの実装がアクションを実行することはありません。

日付を受け入れるために MaskedTextBox を初期化し、MaskInputRejected イベントと TypeValidationCompleted イベントの両方を使用して、ユーザーに無効な入力であることを通知するコード例を次に示します。

private void Form1_Load(object sender, EventArgs e)
{
    maskedTextBox1.Mask = "00/00/0000";

    maskedTextBox1.MaskInputRejected += new MaskInputRejectedEventHandler(maskedTextBox1_MaskInputRejected);
    maskedTextBox1.KeyDown += new KeyEventHandler(maskedTextBox1_KeyDown);
}

void maskedTextBox1_MaskInputRejected(object sender, MaskInputRejectedEventArgs e)
{
    if (maskedTextBox1.MaskFull)
    {
        toolTip1.ToolTipTitle = "Input Rejected - Too Much Data";
        toolTip1.Show("You cannot enter any more data into the date field. Delete some characters in order to insert more data.", maskedTextBox1, 0, -20, 5000);
    }
    else if (e.Position == maskedTextBox1.Mask.Length)
    {
        toolTip1.ToolTipTitle = "Input Rejected - End of Field";
        toolTip1.Show("You cannot add extra characters to the end of this date field.", maskedTextBox1, 0, -20, 5000);
    }
    else
    {
        toolTip1.ToolTipTitle = "Input Rejected";
        toolTip1.Show("You can only add numeric characters (0-9) into this date field.", maskedTextBox1, 0, -20, 5000);
    }
}

void maskedTextBox1_KeyDown(object sender, KeyEventArgs e)
{
    // The balloon tip is visible for five seconds; if the user types any data before it disappears, collapse it ourselves.
    toolTip1.Hide(maskedTextBox1);
}


System.Object
  System.MarshalByRefObject
    System.ComponentModel.Component
      System.Windows.Forms.Control
        System.Windows.Forms.TextBoxBase
          System.Windows.Forms.MaskedTextBox

この型のすべてのパブリック static (Visual Basic では Shared) メンバは、スレッド セーフです。インスタンス メンバの場合は、スレッド セーフであるとは限りません。

Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

.NET Framework および .NET Compact Framework では、各プラットフォームのすべてのバージョンはサポートしていません。サポートされているバージョンについては、「.NET Framework システム要件」を参照してください。

.NET Framework

サポート対象 : 3.5、3.0、2.0
表示: