syncfusion-wpf-numericupdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF NumericUpdown (UpDown)

实现Syncfusion WPF NumericUpdown（UpDown）控件

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Create numeric input fields with increment/decrement buttons
Restrict values within minimum and maximum limits
Format numbers with specific decimal places or grouping
Apply localization and culture-specific formatting
Customize appearance with colors based on value (positive, negative, zero)
Implement keyboard and mouse interactions for numeric input
Handle null values with watermark text

当你需要以下功能时使用该技能：

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

Component Overview

组件概述

The Syncfusion WPF NumericUpdown (UpDown) control displays and manages numeric values with built-in spin buttons for incrementing and decrementing. It provides features for value restrictions, number formatting, event handling, and extensive styling options.

Key Components:

Text area: Displays the numeric value
Increment button: Repeat button to increase value
Decrement button: Repeat button to decrease value

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

核心组件：

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

Documentation Navigation Guide

文档导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and assembly references
Adding UpDown via designer, XAML, and C# code
Basic value and step properties
Theme application and styling

📄 阅读： references/getting-started.md

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

Value and Restrictions

值与限制

📄 Read: references/value-and-restrictions.md

Setting and managing values
Value change events (ValueChanged, ValueChanging)
Minimum and maximum value constraints
Validation modes and behaviors
Null value handling and watermarks
Controlling edit permissions

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

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

Number Formatting

数字格式化

📄 Read: references/number-formatting.md

Decimal digit formatting
Group separator configuration
NumberFormatInfo customization
Culture and localization support
Text alignment options

📄 阅读： references/number-formatting.md

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

Styling and Appearance

样式与外观

📄 Read: references/styling-and-appearance.md

Customizing positive, negative, and zero value colors
Focused state styling
Theme integration with SfSkinManager
Custom theme creation with ThemeStudio

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

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

Advanced Configuration

高级配置

📄 Read: references/advanced-configuration.md

Step interval management
Keyboard and mouse interaction patterns
Animation support
Culture-specific behaviors
Complex use cases and scenarios

📄 阅读： references/advanced-configuration.md

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

Quick Start Example

快速入门示例

Basic XAML Setup

基础XAML设置

xaml

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

xaml

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

Basic C# Setup

基础C#设置

csharp

// 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);

csharp

// 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);

Handling Value Changes

处理值变更

csharp

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;
};

csharp

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;
};

Common Patterns

常见模式

Pattern 1: Validated Numeric Input with Restricted Range

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

When users need to validate input within a specific range (e.g., quantity 1-999):

csharp

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

When to use: Product quantity, age validation, percentage fields.

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

csharp

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

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

Pattern 2: Currency Input with Formatting

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

When users need formatted currency display with decimal places:

csharp

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

When to use: Price input, monetary values, financial calculations.

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

csharp

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

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

Pattern 3: Value-Based Visual Feedback

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

When users need different colors for positive, negative, and zero values:

csharp

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

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

When to use: Profit/loss display, balance sheets, variance analysis.

当用户需要为正、负、零值设置不同颜色时：

csharp

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

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

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

Pattern 4: Null Value with Watermark

模式4：带水印的空值处理

When users need to handle uninitialized or "no value" scenarios:

csharp

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

When to use: Optional numeric fields, initial empty states.

当用户需要处理未初始化或"无值"场景时：

csharp

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

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

Key Properties

核心属性

Property	Type	Purpose
Value	double?	Current numeric value
Step	double	Increment/decrement interval
MinValue	double	Minimum allowed value
MaxValue	double	Maximum allowed value
NumberDecimalDigits	int	Decimal places to display
GroupSeperatorEnabled	bool	Show thousand separators
Culture	CultureInfo	Localization format
AllowEdit	bool	Allow direct text editing
UseNullOption	bool	Support null values
NullValueText	string	Watermark text when null

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

Common Use Cases

常见使用场景

Product Quantity Input: Restrict to integers with min/max range
Price Input: Format with 2 decimal places and currency symbol
Age Input: Restrict to valid age range (18-120)
Percentage Input: Restrict to 0-100 with no decimals
Temperature Control: Allow negative values with culture-specific format
Discount Calculator: Show positive in green, negative in red
Scoring System: Restrict to specific range (1-5 for ratings)
Time Duration: Format with step intervals (15-minute increments)

Next Steps: Choose a reference file above based on your implementation needs, or read "Getting Started" for basic setup instructions.

产品数量输入：限制为整数并设置最小/最大值范围
价格输入：格式化为2位小数并显示货币符号
年龄输入：限制为有效年龄范围（18-120）
百分比输入：限制为0-100且无小数位
温度控制：允许负值并使用区域文化特定格式
折扣计算器：正值显示为绿色，负值显示为红色
评分系统：限制为特定范围（1-5级评分）
时间时长：按步长间隔格式化（15分钟递增）

下一步： 根据你的实现需求选择上述参考文件，或阅读《入门指南》了解基础设置说明。