MaskedTextBox 类
定义
重要
一些信息与预发行产品相关，相应产品在发行之前可能会进行重大修改。 对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。
使用掩码区分正确的和不正确的用户输入。
public ref class MaskedTextBox : System::Windows::Forms::TextBoxBase[System.ComponentModel.DefaultBindingProperty("Text")]
[System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.AutoDispatch)]
[System.Runtime.InteropServices.ComVisible(true)]
public class MaskedTextBox : System.Windows.Forms.TextBoxBase[System.ComponentModel.DefaultBindingProperty("Text")]
public class MaskedTextBox : System.Windows.Forms.TextBoxBase[<System.ComponentModel.DefaultBindingProperty("Text")>]
[<System.Runtime.InteropServices.ClassInterface(System.Runtime.InteropServices.ClassInterfaceType.AutoDispatch)>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type MaskedTextBox = class
inherit TextBoxBase[<System.ComponentModel.DefaultBindingProperty("Text")>]
type MaskedTextBox = class
inherit TextBoxBasePublic Class MaskedTextBox
Inherits 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);
}
Private Sub MaskedTextBox1_MaskInputRejected(ByVal sender As System.Object, ByVal e As System.Windows.Forms.MaskInputRejectedEventArgs) Handles MaskedTextBox1.MaskInputRejected
If (Me.MaskedTextBox1.MaskFull) Then
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.", Me.MaskedTextBox1, Me.MaskedTextBox1.Location.X, Me.MaskedTextBox1.Location.Y, 5000)
ElseIf (e.Position = Me.MaskedTextBox1.Mask.Length) Then
ToolTip1.ToolTipTitle = "Input Rejected - End of Field"
ToolTip1.Show("You cannot add extra characters to the end of this date field.", Me.MaskedTextBox1, 0, -20, 5000)
Else
ToolTip1.ToolTipTitle = "Input Rejected"
ToolTip1.Show("You can only add numeric characters (0-9) into this date field.", Me.MaskedTextBox1, 0, -20, 5000)
End If
End Sub
Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load
Me.ToolTip1.IsBalloon = True
Me.MaskedTextBox1.Mask = "00/00/0000"
End Sub
Private Sub MaskedTextBox1_KeyDown(ByVal sender As Object, ByVal e As KeyEventArgs) Handles MaskedTextBox1.KeyDown
' The balloon tip is visible for five seconds; if the user types any data before it disappears, collapse it ourselves.
Me.ToolTip1.Hide(Me.MaskedTextBox1)
End Sub
注解
类 MaskedTextBox 是一个增强的 TextBox 控件，它支持用于接受或拒绝用户输入的声明性语法。 Mask使用 属性，可以指定以下输入，而无需在应用程序中编写任何自定义验证逻辑：
必需的输入字符。
可选输入字符。
在掩码中给定位置预期的输入类型;例如，数字、字母或字母数字字符。
掩码文本或应直接显示在 中的 MaskedTextBox字符;例如，在电话号码中 ( ) 连字符，或价格中的货币符号。
输入字符的特殊处理;例如，将字母字符转换为大写。
当控件 MaskedTextBox 在运行时显示时，它将掩码表示为一系列提示字符和可选文本字符。 每个可编辑的掩码位置（表示必需或可选输入）都以单个提示字符显示。 例如，数字符号 (#) 通常用作数字字符输入的占位符。 可以使用 PromptChar 属性指定自定义提示字符。 属性 HidePromptOnLeave 确定控件失去输入焦点时用户是否看到提示字符。
当用户在屏蔽的文本框中键入输入时，有效的输入字符将按顺序替换其各自的提示字符。 如果用户键入无效的输入字符，则不会进行替换，但如果 属性设置为 true，则会发出BeepOnError蜂鸣声，并MaskInputRejected引发事件。 可以通过处理此事件来提供自己的自定义错误逻辑。
当当前插入点位于文本字符时，用户有许多选项：
如果键入了提示字符以外的字符，则文本将自动跳过，输入字符将应用于下一个可编辑的位置，由下一个提示字符表示。
如果提示字符已键入并且 AllowPromptAsInput 属性为 true，则输入将覆盖提示字符，并且插入点将移动到掩码中的下一个位置。
与往常一样，箭头键可用于导航到上一个或后续位置。
可以使用 MaskFull 属性来验证用户是否已输入所有必需的输入。 属性 Text 将始终检索根据掩码和 TextMaskFormat 属性设置格式的用户输入。
控件 MaskedTextBox 实际上将所有掩码处理延迟到 System.ComponentModel.MaskedTextProvider 由 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当 设置为 ExcludePromptAndLiterals) 时 TextMaskFormat ( |
Format 属性 |
无 |
FormattedText 属性 |
Text当 设置为 IncludePromptAndLiterals) 时 TextMaskFormat ( |
Mask 属性 |
Mask |
PromptChar 属性 |
PromptChar |
PromptInclude 属性 |
ResetOnPrompt |
ValidationError 事件 |
MaskInputRejected |
注意
控件 MaskedTextBox 不支持多行配置或撤消功能。 但是，尽管为了与 TextBoxBase 基类兼容而保留与这些功能关联的成员，但其实现不执行任何操作。
构造函数
| MaskedTextBox() |
使用默认值初始化 MaskedTextBox 类的一个新实例。 |
| MaskedTextBox(MaskedTextProvider) |
使用指定的自定义掩码语言提供程序初始化 MaskedTextBox 类的一个新实例。 |
| MaskedTextBox(String) |
使用指定的输入掩码初始化 MaskedTextBox 类的一个新实例。 |
属性
| AcceptsTab |
获取或设置一个值，该值确定将如何针对多行配置处理 Tab 键。 MaskedTextBox 不支持此属性。 |
| AccessibilityObject |
获取分配给该控件的 AccessibleObject。 (继承自 Control) |
| AccessibleDefaultActionDescription |
获取或设置控件的默认操作说明以供具有辅助功能的客户端应用程序使用。 (继承自 Control) |
| AccessibleDescription |
获取或设置辅助功能客户端应用程序使用的控件说明。 (继承自 Control) |
| AccessibleName |
获取或设置辅助功能客户端应用程序所使用的控件名称。 (继承自 Control) |
| AccessibleRole |
获取或设置控件的辅助性角色。 (继承自 Control) |
| AllowDrop |
获取或设置一个值，该值指示控件是否可以接受用户拖放到它上面的数据。 (继承自 Control) |
| AllowPromptAsInput |
获取或设置一个值，该值指示 PromptChar 是否可以作为有效数据由用户输入。 |
| Anchor |
获取或设置控件绑定到的容器的边缘并确定控件如何随其父级一起调整大小。 (继承自 Control) |
| AsciiOnly |
获取或设置一个值，该值指示 MaskedTextBox 控件是否接受 ASCII 字符集以外的字符。 |
| AutoScrollOffset |
获取或设置一个值，该值指示在 ScrollControlIntoView(Control) 中将控件滚动到何处。 (继承自 Control) |
| AutoSize |
获取或设置一个值，该值指示当更改分配给控件的字体时，是否自动调整控件的高度。 (继承自 TextBoxBase) |
| BackColor |
获取或设置控件的背景色。 (继承自 TextBoxBase) |
| BackgroundImage |
此属性与此类无关。 (继承自 TextBoxBase) |
| BackgroundImageLayout |
此属性与此类无关。 (继承自 TextBoxBase) |
| BeepOnError |
获取或设置一个值，该值指示掩码文本框控件是否每当用户键入了它拒绝的字符时都发出系统提示音。 |
| BindingContext |
获取或设置控件的 BindingContext。 (继承自 Control) |
| BorderStyle |
获取或设置文本框控件的边框类型。 (继承自 TextBoxBase) |
| Bottom |
获取控件下边缘与其容器的工作区上边缘之间的距离（以像素为单位）。 (继承自 Control) |
| Bounds |
获取或设置控件（包括其非工作区元素）相对于其父控件的大小和位置（以像素为单位）。 (继承自 Control) |
| CanEnableIme |
获取一个用以指示是否可以将 ImeMode 属性设置为活动值的值，以启用 IME 支持。 (继承自 TextBoxBase) |
| CanFocus |
获取一个值，该值指示控件是否可以接收焦点。 (继承自 Control) |
| CanRaiseEvents |
确定是否可以在控件上引发事件。 (继承自 Control) |
| CanSelect |
获取一个值，该值指示是否可以选中控件。 (继承自 Control) |
| CanUndo |
获取一个值，该值指示用户能否撤消上一个操作。 MaskedTextBox 不支持此属性。 |
| Capture |
获取或设置一个值，该值指示控件是否已捕获鼠标。 (继承自 Control) |
| CausesValidation |
获取或设置一个值，该值指示控件是否会引起在任何需要在接收焦点时执行验证的控件上执行验证。 (继承自 Control) |
| ClientRectangle |
获取表示控件的工作区的矩形。 (继承自 Control) |
| ClientSize |
获取或设置控件的工作区的高度和宽度。 (继承自 Control) |
| CompanyName |
获取包含控件的应用程序的公司名称或创建者。 (继承自 Control) |
| Container |
获取包含 IContainer 的 Component。 (继承自 Component) |
| ContainsFocus |
获取一个值，该值指示控件或它的一个子控件当前是否有输入焦点。 (继承自 Control) |
| ContextMenu |
获取或设置与控件关联的快捷菜单。 (继承自 Control) |
| ContextMenuStrip |
获取或设置与此控件关联的 ContextMenuStrip。 (继承自 Control) |
| Controls |
获取包含在控件内的控件的集合。 (继承自 Control) |
| Created |
获取一个值，该值指示控件是否已经创建。 (继承自 Control) |
| CreateParams |
获取创建控件句柄时所需要的创建参数。 |
| Culture |
获取或设置与掩码文本框关联的区域性信息。 |
| Cursor |
获取或设置当鼠标指针位于控件上时显示的光标。 (继承自 Control) |
| CutCopyMaskFormat |
获取或设置一个值，该值决定是否将原义字符和提示字符复制到剪贴板中。 |
| DataBindings |
为该控件获取数据绑定。 (继承自 Control) |
| DataContext |
获取或设置用于数据绑定的数据上下文。 这是一个环境属性。 (继承自 Control) |
| DefaultCursor |
获取或设置控件的默认光标。 (继承自 TextBoxBase) |
| DefaultImeMode |
获取控件支持的默认输入法编辑器 (IME) 模式。 (继承自 Control) |
| DefaultMargin |
获取控件之间默认指定的间距（以像素为单位）。 (继承自 Control) |
| DefaultMaximumSize |
获取以像素为单位的长度和高度，此长度和高度被指定为控件的默认最大大小。 (继承自 Control) |
| DefaultMinimumSize |
获取以像素为单位的长度和高度，此长度和高度被指定为控件的默认最小大小。 (继承自 Control) |
| DefaultPadding |
获取控件内容的默认内部间距（以像素为单位）。 (继承自 Control) |
| DefaultSize |
获取控件的默认大小。 (继承自 TextBoxBase) |
| DesignMode |
获取一个值，用以指示 Component 当前是否处于设计模式。 (继承自 Component) |
| DeviceDpi |
获取显示当前控件的显示设备的 DPI 值。 (继承自 Control) |
| DisplayRectangle |
获取表示控件的显示区域的矩形。 (继承自 Control) |
| Disposing |
获取一个值，该值指示 Control 基类是否在释放进程中。 (继承自 Control) |
| Dock |
获取或设置哪些控件边框停靠到其父控件并确定控件如何随其父级一起调整大小。 (继承自 Control) |
| DoubleBuffered |
获取或设置一个值，该值指示是否在显示控件前在缓冲区中完成控件绘制。 此属性与此类无关。 (继承自 TextBoxBase) |
| Enabled |
获取或设置一个值，该值指示控件是否可以对用户交互作出响应。 (继承自 Control) |
| Events |
获取附加到此 Component 的事件处理程序的列表。 (继承自 Component) |
| Focused |
获取一个值，该值指示控件是否有输入焦点。 (继承自 Control) |
| Font |
获取或设置控件显示的文字的字体。 (继承自 Control) |
| FontHeight |
获取或设置控件的字体的高度。 (继承自 Control) |
| ForeColor |
获取或设置控件的前景色。 (继承自 TextBoxBase) |
| FormatProvider |
获取或设置在执行类型验证时使用的 IFormatProvider。 |
| Handle |
获取控件绑定到的窗口句柄。 (继承自 Control) |
| HasChildren |
获取一个值，该值指示控件是否包含一个或多个子控件。 (继承自 Control) |
| Height |
获取或设置控件的高度。 (继承自 Control) |
| HidePromptOnLeave |
获取或设置一个值，该值指示当掩码文本框失去焦点时，输入掩码中的提示字符是否隐藏。 |
| HideSelection |
获取或设置一个值，该值指示当文本框控件没有焦点时，该控件中选定的文本是否保持突出显示。 (继承自 TextBoxBase) |
| ImeMode |
获取或设置控件的输入法编辑器 (IME) 模式。 (继承自 Control) |
| ImeModeBase |
获取或设置控件的输入法编辑器 (IME) 模式。 (继承自 TextBoxBase) |
| InsertKeyMode |
获取或设置掩码文本框控件的文本插入模式。 |
| InvokeRequired |
获取一个值，该值指示调用方在对控件进行方法调用时是否必须调用 Invoke 方法，因为调用方位于创建控件所在的线程以外的线程中。 (继承自 Control) |
| IsAccessible |
获取或设置一个值，该值指示控件对辅助功能应用程序是否可见。 (继承自 Control) |
| IsAncestorSiteInDesignMode |
指示此控件的上级之一是否位于 DesignMode 中以及该站点。 此属性为只读。 (继承自 Control) |
| IsDisposed |
获取一个值，该值指示控件是否已经被释放。 (继承自 Control) |
| IsHandleCreated |
获取一个值，该值指示控件是否有与它关联的句柄。 (继承自 Control) |
| IsMirrored |
获取一个值，该值指示此控件是否为镜像控件。 (继承自 Control) |
| IsOverwriteMode |
获取一个值，该值指定新的用户输入是否覆盖现有输入。 |
| LayoutEngine |
获取控件的布局引擎的缓存实例。 (继承自 Control) |
| Left |
获取或设置控件左边缘与其容器的工作区左边缘之间的距离（以像素为单位）。 (继承自 Control) |
| Lines |
获取或设置多行配置中的文本行。 MaskedTextBox 不支持此属性。 |
| Location |
获取或设置该控件的左上角相对于其容器的左上角的坐标。 (继承自 Control) |
| Margin |
获取或设置控件之间的空间。 (继承自 Control) |
| Mask |
获取或设置运行时使用的输入掩码。 |
| MaskCompleted |
获取一个值，该值指示所有必需的输入是否都已输入到输入掩码中。 |
| MaskedTextProvider |
获取与掩码文本框控件的此实例关联的掩码提供程序的复本。 |
| MaskFull |
获取一个值，该值指示所有必需和可选的输入是否都已输入到输入掩码中。 |
| MaximumSize |
获取或设置大小，该大小是 GetPreferredSize(Size) 可以指定的上限。 (继承自 Control) |
| MaxLength |
获取或设置用户可在文本框控件中键入或粘贴的最大字符数。 MaskedTextBox 不支持此属性。 |
| MinimumSize |
获取或设置大小，该大小是 GetPreferredSize(Size) 可以指定的下限。 (继承自 Control) |
| Modified |
获取或设置一个值，该值指示自创建文本框控件或上次设置该控件的内容后，用户修改了该控件。 (继承自 TextBoxBase) |
| Multiline |
获取或设置一个值，该值指示它是否为多行文本框控件。 MaskedTextBox 不完全支持此属性。 |
| Name |
获取或设置控件的名称。 (继承自 Control) |
| Padding |
此属性与此类无关。 (继承自 TextBoxBase) |
| Parent |
获取或设置控件的父容器。 (继承自 Control) |
| PasswordChar |
获取或设置要取代用户输入而显示的字符。 |
| PreferredHeight |
获取文本框的首选高度。 (继承自 TextBoxBase) |
| PreferredSize |
获取可以容纳控件的矩形区域的大小。 (继承自 Control) |
| ProductName |
获取包含控件的程序集的产品名称。 (继承自 Control) |
| ProductVersion |
获取包含控件的程序集的版本。 (继承自 Control) |
| PromptChar |
获取或设置用于表示 MaskedTextBox 中缺少用户输入的字符。 |
| ReadOnly |
获取或设置一个值，该值指示文本框中的文本是否为只读。 |
| RecreatingHandle |
获取一个值，该值指示控件当前是否在重新创建其句柄。 (继承自 Control) |
| Region |
获取或设置与控件关联的窗口区域。 (继承自 Control) |
| RejectInputOnFirstFailure |
获取或设置一个值，该值指示当遇到第一个无效字符时，是否应停止对用户输入的分析。 |
| RenderRightToLeft |
已过时.
已过时.
此属性现已过时。 (继承自 Control) |
| ResetOnPrompt |
获取或设置一个值，该值确定应如何处理与提示字符匹配的输入字符。 |
| ResetOnSpace |
获取或设置一个值，该值确定应如何处理空白输入字符。 |
| ResizeRedraw |
获取或设置一个值，该值指示控件在调整大小时是否重绘自己。 (继承自 Control) |
| Right |
获取控件右边缘与其容器的工作区左边缘之间的距离（以像素为单位）。 (继承自 Control) |
| RightToLeft |
获取或设置一个值，该值指示是否将控件的元素对齐以支持使用从右向左的字体的区域设置。 (继承自 Control) |
| ScaleChildren |
获取一个值，该值确定子控件的缩放。 (继承自 Control) |
| SelectedText |
获取或设置 MaskedTextBox 控件中当前选择的内容。 |
| SelectionLength |
获取或设置文本框中选定的字符数。 (继承自 TextBoxBase) |
| SelectionStart |
获取或设置文本框中选定的文本起始点。 (继承自 TextBoxBase) |
| ShortcutsEnabled |
获取或设置一个值，该值指示是否启用已定义的快捷方式。 (继承自 TextBoxBase) |
| ShowFocusCues |
获取一个值，该值指示控件是否应显示聚焦框。 (继承自 Control) |
| ShowKeyboardCues |
获取一个值，该值指示用户界面是否处于适当的状态以显示或隐藏键盘快捷键。 (继承自 Control) |
| Site |
获取或设置控件的站点。 (继承自 Control) |
| Size |
获取或设置控件的高度和宽度。 (继承自 Control) |
| SkipLiterals |
获取或设置一个值，该值指示是否允许用户重新输入原义字符值。 |
| TabIndex |
获取或设置控件在其容器内的 Tab 键顺序。 (继承自 Control) |
| TabStop |
获取或设置一个值，该值指示用户能否使用 Tab 键将焦点放到该控件上。 (继承自 Control) |
| Tag |
获取或设置包含有关控件的数据的对象。 (继承自 Control) |
| Text |
获取或设置当前显示给用户的文本。 |
| TextAlign |
获取或设置掩码文本框控件中文本的对齐方式。 |
| TextLength |
获取显示的文本的长度。 |
| TextMaskFormat |
获取或设置一个值，该值决定原义字符和提示字符是否包括在格式化字符串中。 |
| Top |
获取或设置控件上边缘与其容器的工作区上边缘之间的距离（以像素为单位）。 (继承自 Control) |
| TopLevelControl |
获取没有另一个 Windows 窗体控件作为其父级的父控件。 通常，这是控件所在的最外面的 Form。 (继承自 Control) |
| UseSystemPasswordChar |
获取或设置一个值，该值指示是否应使用操作系统提供的密码字符。 |
| UseWaitCursor |
获取或设置一个值，该值指示是否将等待光标用于当前控件以及所有子控件。 (继承自 Control) |
| ValidatingType |
获取或设置用于验证用户输入的数据的数据类型。 |
| Visible |
获取或设置一个值，该值指示是否显示该控件及其所有子控件。 (继承自 Control) |
| Width |
获取或设置控件的宽度。 (继承自 Control) |
| WindowTarget |
此属性与此类无关。 (继承自 Control) |
| WordWrap |
获取或设置一个值，它指示必要时多行文本框控件是否自动换行到下一行的起始处。 MaskedTextBox 不支持此属性。 |
方法
事件
显式接口实现
| IDropTarget.OnDragDrop(DragEventArgs) |
引发 DragDrop 事件。 (继承自 Control) |
| IDropTarget.OnDragEnter(DragEventArgs) |
引发 DragEnter 事件。 (继承自 Control) |
| IDropTarget.OnDragLeave(EventArgs) |
引发 DragLeave 事件。 (继承自 Control) |
| IDropTarget.OnDragOver(DragEventArgs) |
引发 DragOver 事件。 (继承自 Control) |
