syncfusion-wpf-numericupdown

实现 Syncfusion WPF NumericUpdown（UpDown）

何时使用此技能

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

• 创建带有增量／减量按钮的数值输入字段
• 将值限制在最小值和最大值范围内
• 使用特定的小数位数或分组格式化数字
• 应用本地化和特定区域性的格式
• 根据值（正数、负数、零）自定义外观颜色
• 实现数值输入的键盘和鼠标交互
• 使用水印文本处理空值

组件概述

Syncfusion WPF NumericUpdown（UpDown）控件可显示和管理数值，并内置用于递增和递减数值的微调按钮。它提供值限制、数字格式化、事件处理和丰富的样式选项等功能。

主要组件：

• 文本区域：显示数值
• 递增按钮：用于增加数值的重复按钮
• 递减按钮：用于减少数值的重复按钮

文档导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集引用
• 通过设计器、XAML 和 C# 代码添加 UpDown
• 基本值和步长属性
• 主题应用和样式设置

值和限制

📄 阅读： references/value-and-restrictions.md

• 设置和管理值
• 值更改事件（ValueChanged、ValueChanging）
• 最小值和最大值约束
• 验证模式和行为
• 空值处理和水印
• 控制编辑权限

数字格式化

📄 阅读： references/number-formatting.md

• 小数位格式化
• 分组分隔符配置
• NumberFormatInfo 自定义
• 区域性和本地化支持
• 文本对齐选项

样式和外观

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

• 自定义正数、负数和零值的颜色
• 聚焦状态样式
• 使用 SfSkinManager 集成主题
• 使用 ThemeStudio 创建自定义主题

高级配置

📄 阅读： references/advanced-configuration.md

• 步长间隔管理
• 键盘和鼠标交互模式
• 动画支持
• 特定区域性的行为
• 复杂用例和场景

快速入门示例

基本 XAML 设置

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        
        <syncfusion:UpDown Name="upDown" 
                          Height="25" 
                          Width="100"
                          Value="10"
                          Step="5"
                          MinValue="0"
                          MaxValue="100" />
    </Grid>
</Window>

基本 C# 设置

// Create UpDown control
UpDown updown = new UpDown();
updown.Width = 100;
updown.Height = 25;
updown.Value = 10;
updown.Step = 5;
updown.MinValue = 0;
updown.MaxValue = 100;

// Add to container
grid.Children.Add(updown);

处理值更改

updown.ValueChanged += (d, e) => 
{
    var newValue = e.NewValue;
    var oldValue = e.OldValue;
};

updown.ValueChanging += (s, e) => 
{
    // Can cancel the change
    if ((double)e.NewValue > 50)
        e.Cancel = true;
};

常见模式

模式 1：限制范围的已验证数值输入

当用户需要在特定范围内验证输入时（例如，数量为 1-999）：

var updown = new UpDown();
updown.MinValue = 1;
updown.MaxValue = 999;
updown.MinValidation = MinValidation.OnKeyPress;
updown.MaxValidation = MaxValidation.OnKeyPress;

适用场景： 商品数量、年龄验证、百分比字段。

模式 2：带格式的货币输入

当用户需要显示带小数位的格式化货币时：

updown.NumberDecimalDigits = 2;
updown.GroupSeperatorEnabled = true;
updown.Culture = new CultureInfo("en-US");

适用场景： 价格输入、货币值、财务计算。

模式 3：基于值的视觉反馈

当用户需要为正数、负数和零值显示不同颜色时：

updown.EnableNegativeColors = true;
updown.NegativeBackground = Brushes.LightCoral;
updown.NegativeForeground = Brushes.DarkRed;

updown.ApplyZeroColor = true;
updown.ZeroColor = Brushes.Gray;

适用场景： 盈亏显示、资产负债表、差异分析。

模式 4：带水印的空值

当用户需要处理未初始化或“无值”的情况时：

updown.UseNullOption = true;
updown.Value = null;
updown.NullValueText = "Enter a value";

适用场景： 可选数值字段、初始空状态。

主要属性

属性	类型	用途
Value	double?	当前数值
Step	double	递增／递减间隔
MinValue	double	允许的最小值
MaxValue	double	允许的最大值
NumberDecimalDigits	int	要显示的小数位数
GroupSeperatorEnabled	bool	显示千位分隔符
Culture	CultureInfo	本地化格式
AllowEdit	bool	允许直接编辑文本
UseNullOption	bool	支持空值
NullValueText	string	值为空时显示的水印文本

常见用例

1. 产品数量输入：限制为整数，并设置最小值和最大值
2. 价格输入：保留 2 位小数并添加货币符号
3. 年龄输入：限制在有效年龄范围内（18-120）
4. 百分比输入：限制在 0-100 之间且不保留小数
5. 温度控制：允许负值，并使用符合区域设置的格式
6. 折扣计算器：正值显示为绿色，负值显示为红色
7. 评分系统：限制在特定范围内（评分为 1-5）
8. 时长：按步长间隔格式化（每 15 分钟递增）

---

后续步骤： 根据实现需求选择上方的参考文件，或阅读“入门指南”了解基本设置说明。