mcpField
S
syncfusion-winforms-masked-textbox

syncfusion-winforms-masked-textbox

github.com/syncfusion开发280 次安装1 周前更新
代码仓库

关于 syncfusion-winforms-masked-textbox

面向使用 Syncfusion WinForms MaskedEditBox 的开发者，介绍如何采集固定格式的数据。内容涵盖掩码模式、输入行为、值处理、外观设置和验证事件。

主要功能

  1. 01按模式限制输入
  2. 02电话、IP 和日期掩码
  3. 03剪裁、输入与使用模式
  4. 04区分掩码文本和值
  5. 05验证与完成事件

适用场景

  1. 01采集格式化电话号码
  2. 02输入 IP 地址和网络标识符
  3. 03录入日期及地区格式数据
  4. 04验证账户或登记编号

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/syncfusion/winforms-ui-components-skills --skill syncfusion-winforms-masked-textbox

安装后在 Claude Code 中输入/syncfusion-winforms-masked-textbox确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
appearance-settings.md
behavior-modes.md
events-and-validation.md
getting-started.md
mask-settings.md
text-and-value-handling.md

详细介绍

在 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 添加事件

评论

支持 Markdown