syncfusion-wpf-maskedtextbox

实现 Syncfusion WPF MaskedTextBox（SfMaskedEdit）

WPF MaskedTextBox（SfMaskedEdit）是一种高级输入控件，可使用掩码模式将用户输入限制为特定类型。它非常适合用于创建电话号码、IP 地址、产品 ID、日期以及其他格式化数据输入的模板。

何时使用此技能

在以下情况下使用此技能：

• 将输入限制为特定格式，无需自定义验证
• 实现格式化输入字段，用于电话号码、电子邮件、日期和货币
• 使用 Simple 或 RegEx 掩码类型创建掩码模式
• 在按键时或失去焦点时验证用户输入
• 设置值格式，包含或不包含文字和提示字符
• 显示错误指示器，提示无效输入
• 添加水印，引导用户输入
• 自定义外观，包括颜色、边框和主题
• 支持 RTL 布局，用于国际化应用
• 处理值更改，并通过事件接收通知

组件概述

SfMaskedEdit 提供：

• 多种掩码类型： Simple 和 RegEx 模式
• 灵活的验证： KeyPress 或 LostFocus 验证模式
• 值格式设置： 包含或排除提示符和文字
• 视觉反馈： 错误边框、提示字符、水印
• 全面自定义： 颜色、主题、模板
• MVVM 支持： 数据绑定和属性更改通知

程序集： Syncfusion.SfInput.WPF、Syncfusion.SfShared.WPF
命名空间： Syncfusion.Windows.Controls.Input

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 程序集部署和 NuGet 安装
• 通过设计器、XAML 和 C# 添加 SfMaskedEdit
• 基本配置和设置
• 第一个掩码文本框示例
• 处理 ValueChanged 事件

掩码模式和输入限制

📄 阅读： references/mask-patterns-input-restriction.md、references/mask-patterns-advanced.md

• 掩码元素参考（[], \d, \w, {n}, +, *, ? 等）
• 创建自定义掩码模式
• 使用 (?=) 和 (?!) 允许或限制特定值
• 丰富的掩码示例（电话、电子邮件、货币、日期等）
• 输入验证模式（KeyPress 与 LostFocus）
• 验证结果和 HasError 属性
• PromptChar 和 ShowPromptOnFocus 配置

值管理

📄 阅读： references/value-management.md、references/value-management-advanced.md

• 设置和获取 Value 属性
• ValueMaskFormat 选项：
  • ExcludePromptAndLiterals
  • IncludeLiterals
  • IncludePrompt
  • IncludePromptAndLiterals
• 值更改通知
• 使用格式化值进行剪贴板操作

外观和自定义

📄 阅读： references/appearance-customization.md、references/appearance-customization-themes.md

• Background、Foreground 和 SelectionBrush
• 自定义 CaretBrush 和 BorderBrush
• 用于验证反馈的 ErrorBorderBrush
• 用于 RTL 支持的 FlowDirection
• Watermark 和 WatermarkTemplate
• 主题集成和样式设置

快速入门示例

电话号码掩码

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Grid>
        <syncfusion:SfMaskedEdit 
            x:Name="phoneNumber"
            Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}" 
            MaskType="RegEx"
            Value="4553456789"
            PromptChar="_"
            Width="200" 
            Height="30"
            ValueChanged="PhoneNumber_ValueChanged"/>
    </Grid>
</Window>

using Syncfusion.Windows.Controls.Input;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
    }

    private void PhoneNumber_ValueChanged(object sender, EventArgs e)
    {
        var maskedEdit = sender as SfMaskedEdit;
        if (!maskedEdit.HasError)
        {
            // Use formatted value: (455) 345-6789
            string formattedPhone = maskedEdit.Value;
        }
    }
}

常见模式

常见模式包括电子邮件、货币、日期、产品密钥和值格式设置。请参阅掩码模式和输入限制，查看 25 个以上的详细模式示例，其中包含完整的 XAML 和代码示例。

主要属性

主要属性包括 Mask（模式）、MaskType（Simple/RegEx）、Value（格式化后的输出）、ValueMaskFormat（格式控制）、ValidationMode（KeyPress/LostFocus）、HasError（验证状态）、PromptChar（缺失输入指示符）、ErrorBorderBrush（错误反馈）和 Watermark（占位文本）。有关属性的详细信息和 25 个以上的掩码模式示例，请参阅 入门指南 和 掩码模式。

常见用例

• 数据录入表单： 联系方式、财务数据、带自动格式化的身份证号码
• 电话/财务： 在应用中保持格式一致，强制使用货币/百分比格式
• 产品注册： 验证产品密钥和序列号
• 日期/时间： 使用 RegEx 验证实现 DatePicker 之外的自定义格式
• 国际化： 通过 FlowDirection 支持 RTL，支持区域日期/电话格式
• 实时验证： 使用 KeyPress 即时反馈，或使用 LostFocus 减少干扰

事件

事件	描述
ValueChanged	Value 属性更改时触发（取决于 ValidationMode）
LostFocus	标准 WPF 事件，可用于 LostFocus 验证模式

最佳实践

1. 选择合适的 MaskType： 复杂模式使用 RegEx，基本场景使用 Simple
2. 尽早设置 ValueMaskFormat： 在访问 Value 属性前确定格式
3. 提供视觉反馈： 使用 ErrorBorderBrush 和 Watermark 改善 UX
4. 根据 UX 选择验证模式： KeyPress 可即时反馈，LostFocus 可减少验证干扰
5. 记录自定义模式： 为复杂的 RegEx 掩码添加注释，以便维护
6. 测试边界情况： 验证空输入、部分输入和边界值下的行为
7. 使用 ShowPromptOnFocus： 启用此项可更清晰地显示预期输入格式

---

后续步骤： 根据需求选择上方的参考文件，或从 getting-started.md 开始进行初始设置。