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 控件提供：

• 掩码类型 - 简单（固定长度）和正则表达式（可变长度）模式
• 简单掩码 - 内置元素：0（数字）、L（字母）、A（字母数字）等
• 正则表达式掩码 - 完整支持正则表达式模式，可用于复杂验证
• 提示字符 - 可自定义的占位字符（默认值为 '_'）
• 值格式化 - 控制值的显示方式，包括文字和提示字符
• 错误指示 - 内置错误类型（警告、成功、严重等）
• 自定义错误 - 用于验证的自定义图标和边框颜色
• 标题和说明 - 标签和帮助文本，改善用户体验
• 事件 - 用于实时验证的 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 和代码隐藏中添加控件
• 导入命名空间
• 简单掩码示例（日期模式）
• 正则表达式掩码示例（电子邮件模式）
• 设置提示字符
• 设置 value 属性

掩码类型

📄 阅读： references/mask-types.md

• 用于固定长度输入的简单掩码类型
• 简单掩码元素（0、9、#、L、?、C、A、<、>）
• 元素说明和用法
• 用于可变长度输入的正则表达式掩码类型
• 正则表达式模式元素和语法
• 电话号码掩码示例
• 电子邮件模式示例
• 产品密钥模式
• 创建自定义掩码

值格式化

📄 阅读： 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

• ValueChanging 事件（更改前）
• 事件参数和属性
• 使用 Cancel 阻止无效输入
• 实时字符筛选
• 条件输入规则

📄 阅读： references/events-valuechanged.md

• ValueChanged 事件（更改后）
• 组合使用 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	验证反馈类型（None、Warning、Success 等）
CustomErrorIcon	ImageSource	Custom 错误类型的自定义错误图标
CustomErrorBorderBrush	Brush	错误状态的自定义边框画笔
ErrorContent	object	悬停在错误图标上时显示的工具提示内容
Header	object	显示在控件上方的标签
HeaderTemplate	DataTemplate	标题的自定义模板
Description	object	显示在控件下方的帮助文本

常见用例

用例 1：包含多个已验证输入项的表单

创建一个注册表单，包含电话号码、电子邮件和 SSN 字段，每个字段都使用适当的掩码和验证图标。

用例 2：国际电话号码

使用正则表达式掩码支持带国家代码的各种国际电话号码格式。

用例 3：信用卡号输入

实现信用卡号输入，显示格式化的内容（每组 4 位数字），并提供用于处理的原始值。

用例 4：IP 地址输入

使用简单掩码“000.000.000.000”，并通过验证确保每个八位组的值都在 0-255 之间。

用例 5：时间输入

创建使用“00:00 >LL”掩码的时间输入字段，支持 24 小时制和 AM/PM 指示符。

用例 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，请确保语法正确