syncfusion-winforms-numericupdown

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing NumericUpDownExt in Syncfusion WinForms

在Syncfusion WinForms中实现NumericUpDownExt

This skill guides you in implementing Syncfusion WinForms NumericUpDownExt control—an enhanced numeric up/down control with XP themes, value constraints, hexadecimal display, decimal formatting, and professional appearance features.
本指南将指导你实现Syncfusion WinForms NumericUpDownExt控件——这是一款增强型数值加减控件,支持XP主题、数值约束、十六进制显示、小数格式化以及专业外观特性。

When to Use This Skill

何时使用本指南

Use this skill when the user needs to:
  • Implement enhanced numeric up/down controls with XP themes support
  • Set value constraints (Minimum, Maximum, Increment values)
  • Display hexadecimal values in numeric input
  • Format numbers with decimal places and thousands separators
  • Apply themed borders (FixedSingle, Fixed3D, ThemedBorder)
  • Use separate colors for negative values (NegativeForeColor)
  • Enable keyboard arrow key input for value changes
  • Support large value entry via keyboard
  • Configure text and button alignment (left/right/center)
  • Create professional numeric input forms with consistent theming
  • Replace standard NumericUpDown with visually enhanced alternatives
NumericUpDownExt is ideal when visual theming and advanced formatting are important for numeric input controls.
当用户需要实现以下需求时可使用本指南:
  • 实现支持XP主题的增强型数值加减控件
  • 设置数值约束(最小值、最大值、步长值)
  • 在数值输入框中展示十六进制数值
  • 为数字设置小数位数千位分隔符格式
  • 应用主题边框(FixedSingle、Fixed3D、ThemedBorder)
  • 负值设置单独的显示颜色(NegativeForeColor)
  • 支持通过键盘方向键调整数值
  • 支持通过键盘输入大数值
  • 配置文本和按钮对齐方式(左/右/居中)
  • 创建主题统一的专业数值输入表单
  • 用视觉效果更优的替代方案替换标准NumericUpDown控件
当数值输入控件需要视觉主题和高级格式化能力时,NumericUpDownExt是理想选择。

Component Overview

组件概述

NumericUpDownExt is an advanced numeric up/down control that extends the standard WinForms NumericUpDown with XP themes and enhanced features. It provides:
  • XP Themes Support: Enhanced look and feel missing in standard .NET control
  • Value Constraints: Minimum, Maximum, Increment properties
  • Display Options: Decimal places, thousands separator, hexadecimal format
  • Appearance Customization: Colors, borders, alignment options
  • Themed Borders: FixedSingle, Fixed3D, None, ThemedBorder
  • Keyboard Support: Arrow keys, large value entry
  • Negative Value Styling: Separate foreground color for negative numbers
  • Layout Control: MinSize, MaxSize properties
Key Difference from Standard NumericUpDown: NumericUpDownExt adds XP themes, hexadecimal display, themed borders, and negative value color styling.
NumericUpDownExt是一款高级数值加减控件,它在标准WinForms NumericUpDown的基础上扩展了XP主题和增强特性。它提供以下能力:
  • XP主题支持:标准.NET控件不具备的增强外观体验
  • 数值约束:最小值、最大值、步长属性
  • 显示选项:小数位数、千位分隔符、十六进制格式
  • 外观自定义:颜色、边框、对齐选项
  • 主题边框:FixedSingle、Fixed3D、None、ThemedBorder
  • 键盘支持:方向键、大数值输入
  • 负值样式:为负数设置单独的前景色
  • 布局控制:最小尺寸、最大尺寸属性
与标准NumericUpDown的核心差异: NumericUpDownExt新增了XP主题、十六进制显示、主题边框和负值颜色样式能力。

Documentation and Navigation Guide

文档和导航指南

Getting Started and Basic Setup

入门与基础设置

📄 Read: references/getting-started.md
Read this reference when users need:
  • Assembly dependencies and NuGet package installation
  • Creating NumericUpDownExt via designer or code
  • Basic properties and configuration
  • Adding NumericUpDownExt to forms
  • Understanding control hierarchy
  • Complete minimal working example
📄 阅读: references/getting-started.md
当用户需要了解以下内容时阅读本参考:
  • 程序集依赖和NuGet包安装
  • 通过设计器或代码创建NumericUpDownExt
  • 基础属性和配置
  • 向表单添加NumericUpDownExt
  • 理解控件层级结构
  • 完整的最小可运行示例

Value Settings and Constraints

数值设置与约束

📄 Read: references/value-settings.md
Read this reference when users need:
  • Value property for current numeric value
  • Minimum and Maximum constraints
  • Increment property for step values
  • Hexadecimal display mode
  • HexValue property for hex representation
  • UpButton/DownButton methods
  • Value constraint examples and patterns
📄 阅读: references/value-settings.md
当用户需要了解以下内容时阅读本参考:
  • 存储当前数值的Value属性
  • 最小值和最大值约束
  • 控制步长的Increment属性
  • 十六进制显示模式
  • 存储十六进制表示的HexValue属性
  • UpButton/DownButton方法
  • 数值约束示例和最佳实践

Display Settings

显示设置

📄 Read: references/display-settings.md
Read this reference when users need:
  • DecimalPlaces property for fractional display
  • ThousandsSeparator for large numbers
  • Display formatting options
  • Currency and percentage formatting
  • Examples with different number formats
📄 阅读: references/display-settings.md
当用户需要了解以下内容时阅读本参考:
  • 控制小数展示位数的DecimalPlaces属性
  • 大数值千位分隔符设置
  • 显示格式化选项
  • 货币和百分比格式化
  • 不同数字格式的示例

Appearance Customization

外观自定义

📄 Read: references/appearance-customization.md
Read this reference when users need:
  • Background and foreground colors
  • NegativeForeColor for negative values
  • Border styles (FixedSingle, Fixed3D, None)
  • ThemedBorder property
  • Text and button alignment
  • Layout settings (MaxSize, MinSize)
  • Complete custom styling examples
📄 阅读: references/appearance-customization.md
当用户需要了解以下内容时阅读本参考:
  • 背景和前景颜色
  • 控制负值显示颜色的NegativeForeColor
  • 边框样式(FixedSingle、Fixed3D、None)
  • ThemedBorder属性
  • 文本和按钮对齐
  • 布局设置(最大尺寸、最小尺寸)
  • 完整的自定义样式示例

Behavior Settings

行为设置

📄 Read: references/behavior-settings.md
Read this reference when users need:
  • InterceptArrowKeys property for keyboard input
  • ReadOnly mode configuration
  • Key support for large value entry
  • Behavior configuration options
  • User interaction patterns
📄 阅读: references/behavior-settings.md
当用户需要了解以下内容时阅读本参考:
  • 控制键盘输入的InterceptArrowKeys属性
  • 只读模式配置
  • 大数值输入的按键支持
  • 行为配置选项
  • 用户交互最佳实践

Themes and Visual Styles

主题与视觉样式

📄 Read: references/themes-and-styles.md
Read this reference when users need:
  • Visual styles overview
  • Applying themes to NumericUpDownExt
  • XP Themes look and feel
  • Theme integration with application
  • Style best practices
📄 阅读: references/themes-and-styles.md
当用户需要了解以下内容时阅读本参考:
  • 视觉样式概述
  • 为NumericUpDownExt应用主题
  • XP主题外观体验
  • 与应用的主题集成
  • 样式最佳实践

Quick Start Example

快速入门示例

Here's a minimal example creating a NumericUpDownExt control with constraints:
csharp
using Syncfusion.Windows.Forms.Tools;
using System;
using System.Drawing;
using System.Windows.Forms;

public class NumericUpDownExample : Form
{
    private NumericUpDownExt numericUpDownExt1;
    
    public NumericUpDownExample()
    {
        // Create NumericUpDownExt
        numericUpDownExt1 = new NumericUpDownExt();
        numericUpDownExt1.Location = new Point(70, 29);
        numericUpDownExt1.Size = new Size(120, 20);
        
        // Set value constraints
        numericUpDownExt1.Minimum = 0;
        numericUpDownExt1.Maximum = 100;
        numericUpDownExt1.Value = 50;
        numericUpDownExt1.Increment = 5;
        
        // Set display formatting
        numericUpDownExt1.DecimalPlaces = 2;
        numericUpDownExt1.ThousandsSeparator = true;
        
        // Add to form
        this.Controls.Add(numericUpDownExt1);
        
        this.Text = "NumericUpDownExt Example";
        this.Size = new Size(300, 150);
    }
}
Result: A numeric up/down control with values ranging 0-100, incrementing by 5, displaying 2 decimal places with thousands separator.
以下是创建带约束的NumericUpDownExt控件的最小示例:
csharp
using Syncfusion.Windows.Forms.Tools;
using System;
using System.Drawing;
using System.Windows.Forms;

public class NumericUpDownExample : Form
{
    private NumericUpDownExt numericUpDownExt1;
    
    public NumericUpDownExample()
    {
        // 创建NumericUpDownExt
        numericUpDownExt1 = new NumericUpDownExt();
        numericUpDownExt1.Location = new Point(70, 29);
        numericUpDownExt1.Size = new Size(120, 20);
        
        // 设置数值约束
        numericUpDownExt1.Minimum = 0;
        numericUpDownExt1.Maximum = 100;
        numericUpDownExt1.Value = 50;
        numericUpDownExt1.Increment = 5;
        
        // 设置显示格式
        numericUpDownExt1.DecimalPlaces = 2;
        numericUpDownExt1.ThousandsSeparator = true;
        
        // 添加到表单
        this.Controls.Add(numericUpDownExt1);
        
        this.Text = "NumericUpDownExt Example";
        this.Size = new Size(300, 150);
    }
}
效果: 数值范围为0-100、步长为5、显示2位小数并带有千位分隔符的数值加减控件。

Common Patterns

常用使用场景

Currency Input Control

货币输入控件

Pattern: Create a numeric control for currency input with proper formatting.
csharp
// Currency input with constraints
NumericUpDownExt currencyInput = new NumericUpDownExt();
currencyInput.Location = new Point(100, 20);
currencyInput.Size = new Size(120, 20);

// Value settings
currencyInput.Minimum = 0;
currencyInput.Maximum = 999999.99m;
currencyInput.Increment = 0.01m;
currencyInput.Value = 0;

// Display formatting
currencyInput.DecimalPlaces = 2;
currencyInput.ThousandsSeparator = true;

// Add label for context
Label label = new Label();
label.Text = "Price: $";
label.Location = new Point(50, 23);
label.AutoSize = true;

this.Controls.Add(label);
this.Controls.Add(currencyInput);
When: User needs currency input with cents precision and large number formatting.
场景: 创建格式规范的货币输入数值控件。
csharp
// 带约束的货币输入
NumericUpDownExt currencyInput = new NumericUpDownExt();
currencyInput.Location = new Point(100, 20);
currencyInput.Size = new Size(120, 20);

// 数值设置
currencyInput.Minimum = 0;
currencyInput.Maximum = 999999.99m;
currencyInput.Increment = 0.01m;
currencyInput.Value = 0;

// 显示格式化
currencyInput.DecimalPlaces = 2;
currencyInput.ThousandsSeparator = true;

// 添加上下文标签
Label label = new Label();
label.Text = "Price: $";
label.Location = new Point(50, 23);
label.AutoSize = true;

this.Controls.Add(label);
this.Controls.Add(currencyInput);
适用场景: 用户需要具备分精度和大数值格式化能力的货币输入框。

Percentage Selector

百分比选择器

Pattern: Numeric control for percentage values (0-100).
csharp
NumericUpDownExt percentInput = new NumericUpDownExt();
percentInput.Location = new Point(100, 50);
percentInput.Size = new Size(100, 20);

// Percentage constraints
percentInput.Minimum = 0;
percentInput.Maximum = 100;
percentInput.Increment = 5;
percentInput.Value = 50;
percentInput.DecimalPlaces = 1;

// Add % suffix label
Label percentLabel = new Label();
percentLabel.Text = "%";
percentLabel.Location = new Point(205, 53);
percentLabel.AutoSize = true;

this.Controls.Add(percentInput);
this.Controls.Add(percentLabel);
When: User needs percentage input with constrained range.
场景: 用于输入百分比数值(0-100)的数值控件。
csharp
NumericUpDownExt percentInput = new NumericUpDownExt();
percentInput.Location = new Point(100, 50);
percentInput.Size = new Size(100, 20);

// 百分比约束
percentInput.Minimum = 0;
percentInput.Maximum = 100;
percentInput.Increment = 5;
percentInput.Value = 50;
percentInput.DecimalPlaces = 1;

// 添加%后缀标签
Label percentLabel = new Label();
percentLabel.Text = "%";
percentLabel.Location = new Point(205, 53);
percentLabel.AutoSize = true;

this.Controls.Add(percentInput);
this.Controls.Add(percentLabel);
适用场景: 用户需要范围受限的百分比输入框。

Hexadecimal Color Value Input

十六进制颜色值输入框

Pattern: Display and edit values in hexadecimal format.
csharp
NumericUpDownExt hexInput = new NumericUpDownExt();
hexInput.Location = new Point(100, 80);
hexInput.Size = new Size(120, 20);

// Hex mode for color values
hexInput.Hexadecimal = true;
hexInput.Minimum = 0;
hexInput.Maximum = 0xFFFFFF; // Max RGB value
hexInput.Increment = 0x10;
hexInput.Value = 0xFF5733; // Example color

// Add label
Label hexLabel = new Label();
hexLabel.Text = "Color (Hex):";
hexLabel.Location = new Point(20, 83);
hexLabel.AutoSize = true;

this.Controls.Add(hexLabel);
this.Controls.Add(hexInput);
When: User needs hexadecimal input for colors, memory addresses, or byte values.
场景: 展示和编辑十六进制格式的数值。
csharp
NumericUpDownExt hexInput = new NumericUpDownExt();
hexInput.Location = new Point(100, 80);
hexInput.Size = new Size(120, 20);

// 颜色值的十六进制模式
hexInput.Hexadecimal = true;
hexInput.Minimum = 0;
hexInput.Maximum = 0xFFFFFF; // RGB最大值
hexInput.Increment = 0x10;
hexInput.Value = 0xFF5733; // 示例颜色

// 添加标签
Label hexLabel = new Label();
hexLabel.Text = "Color (Hex):";
hexLabel.Location = new Point(20, 83);
hexLabel.AutoSize = true;

this.Controls.Add(hexLabel);
this.Controls.Add(hexInput);
适用场景: 用户需要输入颜色、内存地址或字节值的十六进制输入框。

Key Properties

核心属性

Value Properties

数值属性

PropertyTypeDescriptionWhen to Use
Value
decimalCurrent numeric valueGet/set control value
Minimum
decimalMinimum allowed valueSet lower constraint
Maximum
decimalMaximum allowed valueSet upper constraint
Increment
decimalValue change stepControl increment size
Hexadecimal
boolDisplay in hex formatHex value input
HexValue
stringHex representation (read-only)Get hex string
属性类型描述使用场景
Value
decimal当前数值获取/设置控件值
Minimum
decimal允许的最小值设置下限约束
Maximum
decimal允许的最大值设置上限约束
Increment
decimal数值调整步长控制数值增减幅度
Hexadecimal
bool是否以十六进制格式显示十六进制数值输入
HexValue
string十六进制表示(只读)获取十六进制字符串

Display Properties

显示属性

PropertyTypeDescriptionWhen to Use
DecimalPlaces
intNumber of decimal placesFractional precision
ThousandsSeparator
boolShow thousands separatorLarge number formatting
属性类型描述使用场景
DecimalPlaces
int小数位数小数精度控制
ThousandsSeparator
bool是否显示千位分隔符大数值格式化

Appearance Properties

外观属性

PropertyTypeDescriptionWhen to Use
BackColor
ColorBackground colorCustom backgrounds
ForeColor
ColorText colorCustom text colors
NegativeForeColor
ColorColor for negative valuesHighlight negative numbers
BorderStyle
BorderStyleBorder style (FixedSingle/Fixed3D/None)Control appearance
ThemedBorder
boolUse themed borderModern appearance
属性类型描述使用场景
BackColor
Color背景色自定义背景
ForeColor
Color文本颜色自定义文本颜色
NegativeForeColor
Color负值显示颜色高亮负数
BorderStyle
BorderStyle边框样式(FixedSingle/Fixed3D/None)控制外观
ThemedBorder
bool是否使用主题边框现代化外观

Behavior Properties

行为属性

PropertyTypeDescriptionWhen to Use
InterceptArrowKeys
boolAllow arrow key inputKeyboard value changes
ReadOnly
boolPrevent value editingDisplay-only mode
UpDownAlign
LeftRightAlignmentButton position (Left/Right)Layout customization
TextAlign
HorizontalAlignmentText alignmentLeft/Right/Center alignment
属性类型描述使用场景
InterceptArrowKeys
bool是否允许方向键输入键盘调整数值
ReadOnly
bool是否禁止编辑数值只读展示模式
UpDownAlign
LeftRightAlignment按钮位置(左/右)布局自定义
TextAlign
HorizontalAlignment文本对齐方式左/右/居中对齐

Common Use Cases

常见用例

Settings Forms

设置表单

Numeric inputs for application settings:
  • Font size selector (8-72 pt)
  • Timeout values (seconds/minutes)
  • Buffer size settings
  • Thread count configuration
应用设置的数值输入:
  • 字号选择器(8-72 pt)
  • 超时值(秒/分钟)
  • 缓冲区大小设置
  • 线程数配置

Financial Applications

金融应用

Currency and percentage inputs:
  • Price entry with decimal precision
  • Discount percentage selectors
  • Tax rate inputs
  • Account balance displays
货币和百分比输入:
  • 具备小数精度的价格输入
  • 折扣百分比选择器
  • 税率输入
  • 账户余额展示

Scientific/Engineering Tools

科学/工程工具

Precision numeric input:
  • Measurement values with decimal places
  • Calibration parameters
  • Calculation inputs with constraints
  • Unit conversion interfaces
高精度数值输入:
  • 带小数位数的测量值
  • 校准参数
  • 带约束的计算输入
  • 单位转换界面

Color Pickers

颜色选择器

Hexadecimal color value input:
  • RGB component values (0-255)
  • Hex color codes (#000000-#FFFFFF)
  • Alpha channel values
  • Color palette editors
十六进制颜色值输入:
  • RGB分量值(0-255)
  • 十六进制颜色代码(#000000-#FFFFFF)
  • 透明度通道值
  • 调色板编辑器

Implementation Checklist

实现检查清单

When implementing NumericUpDownExt, ensure:
  • Required assemblies referenced (Syncfusion.Tools.Windows.dll, etc.)
  • Namespace included (Syncfusion.Windows.Forms.Tools)
  • NumericUpDownExt instance created and configured
  • Value constraints set (Minimum, Maximum, Increment)
  • Display formatting configured (DecimalPlaces, ThousandsSeparator)
  • Location and Size specified for layout
  • Default value set with Value property
  • Event handlers added for ValueChanged if needed
  • Validation implemented for business rules
  • Testing with boundary values (min, max, zero, negatives)
实现NumericUpDownExt时,请确保:
  • ✅ 引用了所需程序集(Syncfusion.Tools.Windows.dll等)
  • ✅ 引入了命名空间(Syncfusion.Windows.Forms.Tools)
  • ✅ 创建并配置了NumericUpDownExt实例
  • ✅ 设置了数值约束(最小值、最大值、步长)
  • ✅ 配置了显示格式(小数位数、千位分隔符)
  • ✅ 指定了布局所需的位置和尺寸
  • ✅ 通过Value属性设置了默认值
  • ✅ 如需监听数值变化则添加了ValueChanged事件处理器
  • ✅ 针对业务规则实现了校验逻辑
  • ✅ 使用边界值(最小值、最大值、零、负数)完成了测试

Troubleshooting Quick Reference

故障排查快速参考

Issue: Value not changing with arrow keys
  • Set
    InterceptArrowKeys = true
  • Ensure control has focus
  • Check if ReadOnly is false
Issue: Decimal places not displaying
  • Set
    DecimalPlaces
    property to desired count
  • Ensure Value has decimal component
  • Check Value is not integer-only
Issue: Thousands separator not showing
  • Set
    ThousandsSeparator = true
  • Ensure value is >= 1000
  • Verify culture settings support separator
Issue: Cannot set value outside range
  • Check
    Minimum
    and
    Maximum
    properties
  • Ensure desired value is within constraints
  • Use decimal type for large values
Issue: Hexadecimal display not working
  • Set
    Hexadecimal = true
  • Ensure value is valid hex range
  • Use HexValue property to read hex string
Issue: Negative values not showing in different color
  • Set
    NegativeForeColor
    property explicitly
  • Ensure Minimum allows negative values
  • Check value is actually negative
问题: 方向键无法调整数值
  • 设置
    InterceptArrowKeys = true
  • 确保控件已获得焦点
  • 检查ReadOnly属性是否为false
问题: 小数位数未显示
  • DecimalPlaces
    属性设置为所需位数
  • 确保Value包含小数部分
  • 确认Value不是纯整数
问题: 千位分隔符未显示
  • 设置
    ThousandsSeparator = true
  • 确保数值 >= 1000
  • 验证区域设置支持千位分隔符
问题: 无法设置范围外的数值
  • 检查
    Minimum
    Maximum
    属性
  • 确保目标值在约束范围内
  • 大数值请使用decimal类型
问题: 十六进制显示不生效
  • 设置
    Hexadecimal = true
  • 确保数值在有效的十六进制范围内
  • 使用HexValue属性读取十六进制字符串
问题: 负值未显示为不同颜色
  • 显式设置
    NegativeForeColor
    属性
  • 确保Minimum属性允许负值
  • 确认数值确实为负数

Summary

总结

NumericUpDownExt provides enhanced numeric input functionality with:
  • XP Themes: Modern look and feel
  • Value Constraints: Min/Max/Increment control
  • Display Formatting: Decimal places, thousands separator, hexadecimal
  • Visual Customization: Colors, borders, alignment, themed appearance
Use NumericUpDownExt when visual theming, advanced formatting, and precise value control are important for creating professional numeric input controls in WinForms applications.
NumericUpDownExt提供的增强型数值输入能力包括:
  • XP主题:现代化外观体验
  • 数值约束:最小值/最大值/步长控制
  • 显示格式化:小数位数、千位分隔符、十六进制
  • 视觉自定义:颜色、边框、对齐、主题外观
当你在WinForms应用中创建专业数值输入控件,需要视觉主题、高级格式化和精确数值控制能力时,可使用NumericUpDownExt。