syncfusion-winforms-integer-textbox

实现 Syncfusion Windows Forms Integer TextBox

何时使用此技能

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

• 创建仅接受整数值的数值输入字段
• 设置值约束（最小值和最大值）
• 使用自定义分隔符格式化和显示数字
• 处理负值和验证
• 在 Windows Forms 应用程序中响应值更改和验证错误
• 为数值输入应用视觉样式（颜色、边框）

组件概述

IntegerTextBox 是一种专用的 Windows Forms 控件，派生自标准 TextBox。它：

• 仅接受并显示整数数据类型
• 自动强制执行最小值／最大值约束
• 支持使用组分隔符自定义数字格式
• 提供值更改和验证错误事件
• 支持通过颜色和样式进行视觉自定义
• 处理空值和只读状态
• 支持前导零和负值处理

主要特性：

• 仅允许输入整数值
• 实时验证输入
• 提供用于处理空值的包装属性
• 提供无需主题或本地化的格式选项
• 轻量且能快速响应用户操作

---

文档与导航指南

选择与当前任务匹配的参考文档：

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包配置
• 通过设计器添加控件
• 在 C# 代码中手动添加控件
• 设置最小值和最大值约束
• 初始配置模式

外观

📄 阅读： references/appearance.md

• 设置背景色
• 根据值类型（正数／负数／零）配置文本颜色
• 边框样式
• 只读状态的外观
• 颜色重置方法

数据处理与格式化

📄 阅读： references/data-formatting.md

• 数字格式选项
• 组分隔符和组大小
• 处理负值和按键输入
• 支持前导零
• 空值管理
• 使用单独颜色设置只读状态

事件与交互

📄 阅读： references/events.md

• BindableValueChanged 事件的用法
• IntegerValueChanged 事件处理
• ValidationError 事件模式
• FormattedTextChanged 和 ClipTextChanged
• 事件处理程序实现示例

---

快速入门示例

以下是一个最小可运行示例：

using Syncfusion.Windows.Forms.Tools;

// Add assembly reference: Syncfusion.Shared.Base
// Include namespace: Syncfusion.Windows.Forms.Tools

// Create and add control
IntegerTextBox integerTextBox1 = new IntegerTextBox();
this.Controls.Add(integerTextBox1);

// Set constraints
integerTextBox1.MaxValue = 999999;
integerTextBox1.MinValue = -999999;
integerTextBox1.IntegerValue = 0;

---

常见模式

模式 1：基于值的颜色编码

将正数显示为绿色、负数显示为红色、零显示为灰色：

integerTextBox1.PositiveColor = System.Drawing.Color.Green;
integerTextBox1.NegativeColor = System.Drawing.Color.Red;
integerTextBox1.ZeroColor = System.Drawing.Color.Gray;

模式 2：使用分隔符格式化数字

使用自定义分隔符格式化大数（例如，“1,234,567”）：

integerTextBox1.NumberGroupSeparator = ",";
integerTextBox1.NumberGroupSizes = new int[] { 3 };
integerTextBox1.IntegerValue = 1234567;

模式 3：处理值更改

在用户输入新值时作出响应：

integerTextBox1.BindableValueChanged += 
    (sender, e) => MessageBox.Show($"New value: {integerTextBox1.IntegerValue}");

模式 4：带错误处理的验证

捕获并响应验证错误：

integerTextBox1.ValidationError += (sender, e) =>
{
    MessageBox.Show("Invalid input! Please enter a valid integer.");
};

---

主要属性

属性	用途	示例
MaxValue	整数值的上限	integerTextBox1.MaxValue = 100;
MinValue	整数值的下限	integerTextBox1.MinValue = 0;
IntegerValue	获取/设置当前整数值	int val = integerTextBox1.IntegerValue;
BindableValue	用于安全访问可空值的包装器	integerTextBox1.BindableValue = null;
AllowLeadingZeros	允许数字前有前导零（例如，“0123”）	integerTextBox1.AllowLeadingZeros = true;
NumberGroupSeparator	用于分隔数字组的字符	integerTextBox1.NumberGroupSeparator = ",";
NumberGroupSizes	每组数字的位数	integerTextBox1.NumberGroupSizes = new int[] { 3 };
PositiveColor	正数的颜色	integerTextBox1.PositiveColor = Color.Green;
NegativeColor	负数的颜色	integerTextBox1.NegativeColor = Color.Red;
ZeroColor	数值为零时的颜色	integerTextBox1.ZeroColor = Color.Gray;
BackColor	控件背景色	integerTextBox1.BackColor = Color.White;
ReadOnlyBackColor	只读时的背景色	integerTextBox1.ReadOnlyBackColor = Color.LightGray;
ReadOnly	禁止用户编辑	integerTextBox1.ReadOnly = true;
DeleteSelectionOnNegative	按下减号时删除选中的文本	integerTextBox1.DeleteSelectionOnNegative = true;

---

常见用例

用例 1：带约束的金融输入 创建一个用于输入金额的文本框（0 到 999,999）：

integerTextBox1.MinValue = 0;
integerTextBox1.MaxValue = 999999;
integerTextBox1.NumberGroupSeparator = ",";
integerTextBox1.NumberGroupSizes = new int[] { 3 };

用例 2：温度输入（负数和正数） 允许输入 -50 到 50 度的温度：

integerTextBox1.MinValue = -50;
integerTextBox1.MaxValue = 50;
integerTextBox1.NegativeColor = Color.Blue;
integerTextBox1.PositiveColor = Color.Red;

用例 3：只读显示 显示用户无法修改的数值：

integerTextBox1.IntegerValue = 42;
integerTextBox1.ReadOnly = true;
integerTextBox1.ReadOnlyBackColor = Color.LightGray;

用例 4：带验证的可空整数 允许空值并进行错误处理：

integerTextBox1.BindableValueChanged += (sender, e) =>
{
    if (integerTextBox1.BindableValue == null)
        MessageBox.Show("Value cleared (null)");
    else
        MessageBox.Show($"Value: {integerTextBox1.IntegerValue}");
};

---

后续步骤

• 从入门指南开始，安装并创建控件
• 使用视觉外观自定义外观
• 使用数据格式处理数据
• 使用事件响应用户交互