syncfusion-winforms-numeric-textbox

实现 Syncfusion WinForms SfNumericTextBox

Syncfusion WinForms SfNumericTextBox 控件是一种高级文本输入控件，可采用多种格式（数值、货币、百分比）显示并接受数值，并提供全面的验证、自定义和区域性支持。它提供格式选项、数值限制、外观自定义和事件驱动功能，适用于专业数值数据录入场景。

何时使用此技能

在需要以下功能时，始终立即使用此技能：

• 数值输入：以精确的方式接受并显示数值
• 格式模式：支持数值、货币或百分比格式
• 数值验证：强制执行最小值和最大值限制
• 格式设置：应用带前缀/后缀的自定义格式，并隐藏末尾零
• 水印：控件为空时显示占位文本
• 区域性格式设置：支持多种区域性和数字格式
• 外观自定义：根据数值（正数/负数/零）自定义颜色
• 事件处理：通过 ValueChanged 事件响应数值变化
• 数据录入窗体：构建包含经过验证的数值字段的专业窗体

组件概述

SfNumericTextBox 控件是 Syncfusion Essential Studio for Windows Forms 的一部分，提供以下功能：

• 多种格式模式：数值、货币和百分比模式
• 数值范围支持：定义并验证最小值和最大值
• 保留精度：在显示格式化文本的同时保留完整精度
• 支持空值：AllowNull 属性可用于可空数值字段
• 水印文本：数值为空时显示引导文本
• 自定义单位：支持为单位和标签添加前缀与后缀
• 末尾零：提供隐藏末尾零的选项，让显示更简洁
• 验证模式：按键或失去焦点时进行验证
• 颜色自定义：为正数、负数和零设置不同的颜色
• 边框样式：可自定义边框及焦点和悬停状态
• 事件系统：ValueChanged 事件可跟踪 OldValue 和 NewValue
• 区域性支持：通过 NumberFormatInfo 实现区域性感知的格式设置
• 设计器支持：通过工具箱提供完整的设计时支持

文档与导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 首次设置、安装和基本实现

涵盖主题：

• 程序集部署和 NuGet 包安装
• 通过设计器或代码添加 SfNumericTextBox
• 命名空间导入
• 设置数值（Value 属性）
• 基本格式模式
• 水印文本基础
• 设置最小值/最大值

---

格式模式

📄 阅读： references/format-modes.md

阅读时机： 以不同模式格式化数字、区域性支持

涵盖主题：

• FormatMode 属性（Numeric、Currency、Percent）
• 可控制小数位数的数值格式模式
• 使用货币符号进行格式设置
• 用于百分比数值的 Percent 模式
• 区域性特定的格式设置
• NumberFormatInfo 自定义
• 小数分隔符和组分隔符
• 各模式的实用示例

---

格式设置选项

📄 阅读： references/formatting-options.md

阅读时机： 隐藏零、添加单位、显示水印

涵盖主题：

• 隐藏末尾零（HideTrailingZeros 属性）
• 为自定义单位添加前缀和后缀
• 水印文本的实现
• WatermarkText 属性和 AllowNull
• 将水印与格式模式结合使用
• 显示示例
• 边界情况和最佳实践

---

验证和取值范围

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

阅读时机： 强制执行取值约束、配置验证行为时

涵盖主题：

• MinValue 和 MaxValue 属性
• ValidationMode 属性（KeyPress 或 LostFocus）
• ValueChangeMode 属性（值更新时机）
• LostFocusValidation 模式（Reset、MaxValue、MinValue）
• 验证流程和事件时机
• 错误场景和处理方式
• 实用的验证示例

---

外观和样式

📄 阅读： references/appearance-and-styling.md

阅读时机： 自定义颜色、边框和视觉外观时

涵盖主题：

• 用于正值的 PositiveForeColor
• 用于负值的 NegativeForeColor
• 用于零值的 ZeroForeColor
• 用于占位文本的 WatermarkForeColor
• BorderColor、FocusBorderColor、HoverBorderColor
• 用于禁用状态的 DisabledBorderColor
• BorderStyle 属性
• 背景和字体自定义
• 视觉状态示例

---

事件和高级模式

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

阅读时机： 处理值变化、高级场景时

涵盖主题：

• ValueChanged 事件和订阅
• ValueChangedEventArgs（OldValue、NewValue）
• 事件时机和验证交互
• 响应值变化
• 高级模式（条件格式设置、级联更新）
• 性能注意事项
• 常见事件模式

---

快速入门示例

代码中的基本数值 TextBox

using Syncfusion.WinForms.Input;

// Create SfNumericTextBox
var numericTextBox = new SfNumericTextBox();
numericTextBox.Size = new System.Drawing.Size(150, 20);
numericTextBox.Value = 123.45;
this.Controls.Add(numericTextBox);

设置格式和验证

// Set format mode to currency
numericTextBox.FormatMode = Syncfusion.WinForms.Input.Enums.FormatMode.Currency;

// Set value constraints
numericTextBox.MinValue = 0;
numericTextBox.MaxValue = 10000;

// Add watermark
numericTextBox.WatermarkText = "Enter amount";
numericTextBox.AllowNull = true;

// Subscribe to value changes
numericTextBox.ValueChanged += (sender, e) => 
{
    MessageBox.Show($"Value changed from {e.OldValue} to {e.NewValue}");
};

---

主要属性和方法

属性	类型	用途
Value	double?	获取或设置数值
FormatMode	FormatMode	设置格式（Numeric、Currency、Percent）
MinValue	double	允许的最小值
MaxValue	double	允许的最大值
AllowNull	bool	允许控件中的 null 值
WatermarkText	string	为空时显示的占位文本
HideTrailingZeros	bool	隐藏小数点后的零
Prefix	string	添加到值前面的文本
Suffix	string	添加到值后面的文本
ValidationMode	ValidationMode	KeyPress 或 LostFocus
ValueChangeMode	ValueChangeMode	值属性的更新时机
NumberFormatInfo	NumberFormatInfo	区域性专用的数字格式

---

常见模式

模式 1：带范围的货币输入

// Currency field with $0-$10,000 range
numericTextBox.FormatMode = FormatMode.Currency;
numericTextBox.MinValue = 0;
numericTextBox.MaxValue = 10000;
numericTextBox.WatermarkText = "Enter amount (0-10000)";

模式 2：百分比显示

// Display and accept percentages
numericTextBox.FormatMode = FormatMode.Percent;
numericTextBox.MinValue = 0;
numericTextBox.MaxValue = 100;
numericTextBox.HideTrailingZeros = true;

模式 3：带单位的测量值

// Display with custom units
numericTextBox.Suffix = " inches";
numericTextBox.Value = 25.5;
numericTextBox.HideTrailingZeros = true;

模式 4：带颜色反馈的验证

// Color based on value
numericTextBox.Style.PositiveForeColor = Color.Green;
numericTextBox.Style.NegativeForeColor = Color.Red;
numericTextBox.Style.ZeroForeColor = Color.Gray;

---

后续步骤

1. 从这里开始： 阅读 getting-started.md，了解安装和基本设置
2. 选择格式： 查看 format-modes.md，了解 Numeric、Currency 或 Percent 模式
3. 添加格式设置： 查看 formatting-options.md，了解单位、水印和显示选项
4. 启用验证： 查看 validation-and-ranges.md，了解约束
5. 自定义外观： 使用 appearance-and-styling.md 设置颜色和边框
6. 处理事件： 实现 events-and-advanced.md，实现动态行为