syncfusion-winforms-masked-textbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing MaskedEditBox in Syncfusion WinForms

在Syncfusion WinForms中实现MaskedEditBox

The MaskedEditBox control is a specialized input control for collecting formatted data with predefined patterns. It provides visual cues and input constraints through mask definitions, making it ideal for standardized data entry like phone numbers, IP addresses, and SSNs.

MaskedEditBox控件是一款专用输入控件，用于收集符合预定义模式的格式化数据。它通过掩码定义提供视觉提示和输入约束，非常适合电话号码、IP地址和社保号码等标准化数据录入场景。

When to Use MaskedEditBox

何时使用MaskedEditBox

Use this control when you need to:

Restrict user input to specific patterns (phone:
```
(###) ###-####
```
)
Provide visual placeholders for expected data format
Validate input as users type without separate validation logic
Handle common patterns: phone numbers, IP addresses, dates, currency
Prevent invalid data entry at the control level
Display consistent formatting across your application

Do NOT use if users need completely free-form text input or when data format is unpredictable.

当你需要以下功能时，可使用此控件：

限制用户输入为特定模式（如电话号码：
```
(###) ###-####
```
）
为预期数据格式提供视觉占位符
在用户输入时实时验证，无需单独的验证逻辑
处理常见模式：电话号码、IP地址、日期、货币
在控件层面阻止无效数据输入
在应用中保持一致的格式显示

请勿使用的场景：用户需要完全自由格式的文本输入，或数据格式不可预测时。

Component Overview

组件概述

Key Concepts

核心概念

Mask: A string defining the input format using:

Mask characters (placeholders like
```
#
```
for digits,
```
&
```
for letters)
Literal characters (fixed symbols like parentheses, dashes in
```
(###) ###-####
```
)

Examples:

US Phone:
```
(###) ###-####
```
IP Address:
```
###.###.###.###
```
Social Security:
```
###-##-####
```
Date (MM/DD/YYYY):
```
##/##/####
```

掩码（Mask）：一个字符串，使用以下元素定义输入格式：

掩码字符（如
```
#
```
代表数字，
```
&
```
代表字母的占位符）
文字字符（固定符号，如电话号码掩码
```
(###) ###-####
```
中的括号、短横线）

示例：

美国电话号码：
```
(###) ###-####
```
IP地址：
```
###.###.###.###
```
社保号码：
```
###-##-####
```
日期（MM/DD/YYYY）：
```
##/##/####
```

Core Features

核心功能

Multiple Modes: ClipMode (strip separators), InputMode (include separators), UsageMode (programmatic)
Appearance Control: Borders, fonts, colors, display options
Data Handling: Separate Text (with masks) and Value (mask characters only)
Separators: Date, decimal, thousand, time separators for regional formats
Events: Input validation, completion, and interaction events

多种模式：ClipMode（去除分隔符）、InputMode（包含分隔符）、UsageMode（程序化使用）
外观控制：边框、字体、颜色、显示选项
数据处理：区分Text（包含掩码）和Value（仅掩码字符）
分隔符：针对区域格式的日期、小数、千分位、时间分隔符
事件：输入验证、完成和交互事件

Documentation Navigation

文档导航

Read the references below based on your implementation needs:

根据你的实现需求，阅读以下参考文档：

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and assembly setup
Adding MaskedEditBox via designer
Adding MaskedEditBox via code
Basic initialization

📄 阅读： references/getting-started.md

安装和程序集设置
通过设计器添加MaskedEditBox
通过代码添加MaskedEditBox
基础初始化

Mask Configuration

掩码配置

📄 Read: references/mask-settings.md

Mask character types and syntax
Creating phone number masks
IP address masks
Custom mask patterns

📄 阅读： references/mask-settings.md

掩码字符类型和语法
创建电话号码掩码
IP地址掩码
自定义掩码模式

Behavior Modes

行为模式

📄 Read: references/behavior-modes.md

ClipMode: Output format control
InputMode: User input behavior
UsageMode: Programmatic usage
Selecting the right mode for your use case

📄 阅读： references/behavior-modes.md

ClipMode：输出格式控制
InputMode：用户输入行为
UsageMode：程序化使用
为你的使用场景选择合适的模式

Text and Value Handling

文本与值处理

📄 Read: references/text-and-value-handling.md

Text property (includes mask literals)
Value property (mask characters only)
DataGroups configuration
Separator settings (Date, Decimal, Thousand, Time)
Input validation patterns

📄 阅读： references/text-and-value-handling.md

Text属性（包含掩码文字字符）
Value属性（仅包含掩码字符）
DataGroups配置
分隔符设置（日期、小数、千分位、时间）
输入验证模式

Appearance Settings

外观设置

📄 Read: references/appearance-settings.md

Border styles and colors
Font properties and sizes
Display options and visibility
Read-only mode
Enabled/disabled states

📄 阅读： references/appearance-settings.md

边框样式和颜色
字体属性和大小
显示选项和可见性
只读模式
启用/禁用状态

Events and Validation

事件与验证

📄 Read: references/events-and-validation.md

Available MaskedEditBox events
Input validation events
Completion and focus events
Event handling examples

📄 阅读： references/events-and-validation.md

可用的MaskedEditBox事件
输入验证事件
完成和焦点事件
事件处理示例

Quick Start Example

快速入门示例

csharp

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"

csharp

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"

Common Patterns

常见模式

Phone Number (US Format)

电话号码（美国格式）

csharp

maskedEditBox.Mask = "(###) ###-####";

csharp

maskedEditBox.Mask = "(###) ###-####";

IP Address

IP地址

csharp

maskedEditBox.Mask = "###.###.###.###";

csharp

maskedEditBox.Mask = "###.###.###.###";

Social Security Number

社保号码

csharp

maskedEditBox.Mask = "###-##-####";

csharp

maskedEditBox.Mask = "###-##-####";

Date (MM/DD/YYYY)

日期（MM/DD/YYYY）

csharp

maskedEditBox.Mask = "##/##/####";

csharp

maskedEditBox.Mask = "##/##/####";

Zip Code (US)

邮政编码（美国）

csharp

maskedEditBox.Mask = "#####";
// Optional: Extended format
maskedEditBox.Mask = "#####-####";

csharp

maskedEditBox.Mask = "#####";
// Optional: Extended format
maskedEditBox.Mask = "#####-####";

Key Properties

关键属性

Property	Purpose	Example
`Mask`	Defines the input format pattern	`"(###) ###-####"`
`Text`	Gets/sets text including mask literals	`"(123) 456-7890"`
`Value`	Gets/sets text without mask characters	`"1234567890"`
`ClipMode`	Controls output format when mask is removed	`ClipModes.IncludeLiterals`
`InputMode`	Controls user input behavior	`InputModes.IgnoreSeparators`
`Border3DStyle`	Border appearance	`Border3DStyle.Raised`
`Font`	Font properties (name, size, style)	`new Font("Arial", 10)`
`ForeColor`	Text color	`Color.Black`
`BackColor`	Background color	`Color.White`
`ReadOnly`	Prevent user input	`true/false`
`Enabled`	Enable/disable control	`true/false`

属性	用途	示例
`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`

Common Use Cases

常见使用场景

1. Phone Number Input with Validation

1. 带验证的电话号码输入

Collect phone numbers in a standard format, preventing invalid entry at the control level.

收集标准格式的电话号码，在控件层面阻止无效输入。

2. International Format Support

2. 国际化格式支持

Configure region-specific separators and date/time formats using separator properties.

使用分隔符属性配置区域特定的分隔符和日期/时间格式。

3. Financial Data Entry

3. 财务数据录入

Use for currency input, account numbers, or formatted numeric data with controlled precision.

用于货币输入、账号或带精度控制的格式化数值数据。

4. Medical/Government Forms

4. 医疗/政府表单

Enforce specific formats for medical IDs, social security numbers, and registration codes.

强制医疗ID、社保号码和注册码等采用特定格式。

5. Network Configuration

5. 网络配置

IP addresses, MAC addresses, and other network identifiers requiring fixed formats.

Next Steps:

Start with getting-started.md to set up the control
Choose your mask format from mask-settings.md
Configure behavior in behavior-modes.md
Handle data with text-and-value-handling.md
Customize appearance in appearance-settings.md
Add events from events-and-validation.md

IP地址、MAC地址和其他需要固定格式的网络标识符。

下一步：

从getting-started.md开始，完成控件设置
从mask-settings.md中选择你的掩码格式
在behavior-modes.md中配置行为模式
通过text-and-value-handling.md处理数据
在appearance-settings.md中自定义外观
从events-and-validation.md中添加事件