syncfusion-winforms-currency-textbox

实现 Syncfusion Windows Forms CurrencyTextBox

Syncfusion CurrencyTextBox 是一种专用文本输入控件，派生自 System.Windows.Forms.TextBox，提供货币专属的验证、格式设置和行为。它会自动处理键盘输入验证、符合区域性设置的小数格式以及数值约束。

何时使用此技能

• 创建带自动验证的货币输入字段
• 构建财务数据录入表单（发票、付款、预算）
• 实现带正负值颜色编码的货币显示
• 处理小数精度和分组分隔符
• 处理货币数据的剪贴板操作
• 添加用于乘算数值的键盘快捷键（Mega、Kilo 等）
• 强制执行货币数值的最小值和最大值
• 为较大的数字显示溢出指示器

组件概述

CurrencyTextBox 控件会拦截用户的键盘输入，并阻止输入无效的货币字符。它会根据小数位数、分组分隔符和货币符号自动设置显示格式。与标准 TextBox 不同，它会根据最小值／最大值范围进行验证，并支持货币专属事件。

主要功能：

• 自动验证键盘输入
• 符合区域性设置的小数格式
• 强制执行最大值／最小值约束
• 对正值、负值和零值进行颜色编码
• 支持剪贴板，并可选择移除格式
• 带工具提示的溢出指示器
• 用于乘算数值的键盘快捷键
• 用于处理无效输入的 ValidationError 事件

文档导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集依赖项
• 创建项目并添加控件
• 通过设计器和代码创建控件
• 设置 MaxValue/MinValue 约束
• 配置货币符号
• 基本控件属性

文本字段自定义

📄 阅读： references/text-field-customization.md

• 文本显示和对齐方式（Left、Center、Right）
• 多行支持和自动换行
• 密码字符掩码
• 空状态的横幅文本
• 数字和小数位数格式
• 处理负值和符号
• Null 字符串配置

数值格式设置

📄 阅读： references/value-formatting.md

• 通过 DecimalValue 以编程方式访问
• 自定义货币符号
• 数字格式（小数点前的总位数）
• 小数位数精度
• 配置分组分隔符
• 移除末尾的小数零
• 货币正负值模式

事件处理

📄 阅读： references/event-handling.md

• 用于键盘快捷键的 KeyDown 事件
• 添加乘数按键（G、M、K，分别表示 Giga、Mega、Kilo）
• 用于无效输入的 ValidationError 事件
• 使用 StartPosition 处理错误消息
• 使用 ErrorProvider 提供视觉反馈
• 自定义验证场景

外观自定义

📄 阅读： references/appearance-customization.md

• 边框样式（FixedSingle、Fixed3D、None）
• 3D 边框效果（Raised、Sunken、Flat 等）
• 配置边框颜色和边框位置
• 根据数值进行颜色编码（正值、负值、零值）
• ReadOnly 背景颜色
• 应用视觉样式

高级功能

📄 阅读： references/advanced-features.md

• 支持剪贴板并提供格式设置选项
• 显示溢出指示器
• 溢出指示器工具提示
• 多种剪贴板模式
• 数据保留策略

验证和约束

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

• 设置最小值／最大值边界
• 在验证过程中强制执行约束
• 选中文本时负数输入的行为
• AllowNull 配置
• NullString 自定义显示值
• 强制执行数值范围

快速入门示例

using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

public partial class Form1 : Form
{
    private CurrencyTextBox currencyTextBox1;
    
    public Form1()
    {
        InitializeComponent();
        
        // Create and configure CurrencyTextBox
        currencyTextBox1 = new CurrencyTextBox();
        currencyTextBox1.Location = new System.Drawing.Point(10, 10);
        currencyTextBox1.Size = new System.Drawing.Size(200, 25);
        
        // Set currency format
        currencyTextBox1.CurrencySymbol = "$";
        currencyTextBox1.CurrencyDecimalDigits = 2;
        currencyTextBox1.CurrencyGroupSeparator = ",";
        currencyTextBox1.CurrencyGroupSizes = new int[] { 3 };
        
        // Set value constraints
        currencyTextBox1.MaxValue = 999999.99m;
        currencyTextBox1.MinValue = 0m;
        currencyTextBox1.DecimalValue = 100.00m;
        
        // Set colors for value states
        currencyTextBox1.PositiveColor = System.Drawing.Color.Black;
        currencyTextBox1.NegativeColor = System.Drawing.Color.Red;
        currencyTextBox1.ZeroColor = System.Drawing.Color.Gray;
        
        this.Controls.Add(currencyTextBox1);
    }
}

常用模式

货币输入表单

// For collecting currency amounts (payments, invoices, etc.)
currencyTextBox.MaxValue = decimal.MaxValue;
currencyTextBox.MinValue = 0m;
currencyTextBox.CurrencySymbol = "$";
currencyTextBox.CurrencyDecimalDigits = 2;
currencyTextBox.AllowNull = false;

盈亏显示

// Color-code by sign (green for profit, red for loss)
currencyTextBox.PositiveColor = System.Drawing.Color.Green;
currencyTextBox.NegativeColor = System.Drawing.Color.Red;
currencyTextBox.MaxValue = decimal.MaxValue;
currencyTextBox.MinValue = decimal.MinValue;

带占位符的可选金额

// Allow null values with custom placeholder text
currencyTextBox.AllowNull = true;
currencyTextBox.NullString = "(Not Specified)";
currencyTextBox.Text = "";

大数的键盘快捷键

// Handle KeyDown event to add multiplier shortcuts
private void currencyTextBox1_KeyDown(object sender, KeyEventArgs e)
{
    decimal value = currencyTextBox1.DecimalValue;
    switch(e.KeyCode)
    {
        case Keys.G: // Giga (billion)
            currencyTextBox1.DecimalValue = value * 1000000000m;
            break;
        case Keys.M: // Mega (million)
            currencyTextBox1.DecimalValue = value * 1000000m;
            break;
        case Keys.K: // Kilo (thousand)
            currencyTextBox1.DecimalValue = value * 1000m;
            break;
    }
}

关键属性参考

属性	类型	用途	常见值
DecimalValue	decimal	以编程方式获取/设置数值	任意有效的 decimal
CurrencySymbol	string	显示货币符号	"$", "€", "£", "¥"
CurrencyDecimalDigits	int	显示的小数位数	2, 3, 4
CurrencyGroupSeparator	string	千位分隔符	",", ".", " "
MaxValue	decimal	允许的最大值	999999.99, 100000 等
MinValue	decimal	允许的最小值	0, -999999.99 等
PositiveColor	Color	正数的颜色	Color.Black, Color.Green
NegativeColor	Color	负数的颜色	Color.Red, Color.Maroon
ZeroColor	Color	零值的颜色	Color.Gray, Color.DarkGray
TextAlign	HorizontalAlignment	文本位置	Left, Center, Right
BorderStyle	BorderStyle	边框外观	FixedSingle, Fixed3D, None
AllowNull	bool	允许空值/null 值	true, false
ShowOverflowIndicator	bool	数值超出范围时显示指示器	true, false

按场景划分的使用案例

金融应用

• 使用正数/负数颜色编码
• 设置 MaxValue 以防止数据类型溢出
• 处理 ValidationError 以记录审计日志
• 支持剪贴板粘贴操作

预算输入表单

• 设置合理的 MaxValue（例如 999999.99）
• 使用 TextAlign.Right，符合数字排版惯例
• 为必填字段显示提示横幅
• 如果金额必须为正数，则将 MinValue 设为 0

多币种显示

• 根据用户区域设置更改 CurrencySymbol
• 保持 CurrencyDecimalDigits 一致（通常为 2）
• 根据地区调整 CurrencyGroupSeparator
• 在数据库中一致地显示 DecimalValue

大数处理

• 启用键盘乘数快捷键（G、M、K）
• 对超出可见空间的数值使用 ShowOverflowIndicator
• 使用 RemoveDecimalZeros 属性移除小数末尾的零
• 使用 CurrencyNumberDigits 增加数字位数

后续步骤

• 选择与任务匹配的参考文件
• 按照代码示例实现控件
• 使用有效值和边界情况进行测试
• 为无效输入处理 ValidationError 事件
• 在业务逻辑中使用 DecimalValue，在显示时使用 Text