Back to Details

syncfusion-winforms-numeric-textbox

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Syncfusion WinForms SfNumericTextBox

实现Syncfusion WinForms SfNumericTextBox

The Syncfusion WinForms SfNumericTextBox control is an advanced text input control that displays and accepts numeric values in multiple formats (numeric, currency, percent) with comprehensive validation, customization, and cultural support. It provides formatting options, value constraints, appearance customization, and event-driven capabilities for professional numeric data entry scenarios.
Syncfusion WinForms SfNumericTextBox控件是一款高级文本输入控件，可展示和接收多种格式（数值、货币、百分比）的数值，具备完善的验证、自定义和文化适配支持。它提供了格式化选项、值约束、外观自定义和事件驱动能力，适用于专业的数值数据录入场景。

When to Use This Skill

何时使用该技能

Use this skill ALWAYS and immediately when you need to:
  • Numeric Input: Accept and display numeric values with precision
  • Format Modes: Support numeric, currency, or percent formats
  • Value Validation: Enforce minimum and maximum value constraints
  • Formatting: Apply custom formatting with prefix/suffix, hide trailing zeros
  • Watermark: Display placeholder text when control is empty
  • Cultural Formatting: Support multiple cultures and number formats
  • Appearance Customization: Customize colors based on value (positive/negative/zero)
  • Event Handling: Respond to value changes with ValueChanged event
  • Data Entry Forms: Build professional forms with validated numeric fields
当你有以下需求时，请优先立即使用该技能：
  • 数值输入：接收并展示高精度数值
  • 格式模式：支持数值、货币或百分比格式
  • 值验证：强制遵循最小值和最大值约束
  • 格式化：通过前缀/后缀应用自定义格式，隐藏尾随零
  • 水印：控件为空时展示占位文本
  • 文化适配格式化：支持多文化和多数值格式
  • 外观自定义：根据数值（正/负/零）自定义颜色
  • 事件处理：通过ValueChanged事件响应数值变化
  • 数据录入表单：构建带验证数值字段的专业表单

Component Overview

组件概述

The SfNumericTextBox control is part of Syncfusion Essential Studio for Windows Forms and provides:
  • Multiple Format Modes: Numeric, Currency, and Percent modes
  • Value Range Support: Define and validate minimum and maximum values
  • Precision Preservation: Maintains full precision while displaying formatted text
  • Null Value Support: AllowNull property for nullable numeric fields
  • Watermark Text: Display guidance text when value is null
  • Custom Units: Prefix and suffix support for units and labels
  • Trailing Zeros: Option to hide trailing zeros for cleaner display
  • Validation Modes: KeyPress or LostFocus validation timing
  • Color Customization: Different colors for positive, negative, and zero values
  • Border Styling: Customizable borders with focus and hover states
  • Event System: ValueChanged event with OldValue and NewValue tracking
  • Cultural Support: Culture-aware formatting via NumberFormatInfo
  • Designer Support: Full design-time support via toolbox
SfNumericTextBox控件是Syncfusion Essential Studio for Windows Forms的组成部分，提供以下能力：
  • 多种格式模式：数值、货币和百分比模式
  • 值范围支持：定义和验证最小值与最大值
  • 精度保留：展示格式化文本的同时保留完整精度
  • 空值支持：针对可空数值字段提供AllowNull属性
  • 水印文本：值为空时展示引导文本
  • 自定义单位：支持前缀和后缀用于添加单位和标签
  • 尾随零处理：可选择隐藏尾随零，让展示更简洁
  • 验证模式：按键触发或失焦触发的验证时机
  • 颜色自定义：为正、负、零值设置不同颜色
  • 边框样式：可自定义边框，支持聚焦和悬停状态
  • 事件系统：ValueChanged事件可追踪旧值和新值
  • 文化适配支持：通过NumberFormatInfo实现文化感知的格式化
  • 设计器支持：通过工具箱提供完整的设计时支持

Documentation and Navigation Guide

文档和导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When to read: First-time setup, installation, basic implementation
Topics covered:
  • Assembly deployment and NuGet package installation
  • Adding SfNumericTextBox via designer or code
  • Namespace imports
  • Setting values (Value property)
  • Basic format modes
  • Watermark text basics
  • Min/Max value setup
📄 阅读： references/getting-started.md
适用场景： 首次设置、安装、基础实现
涵盖主题：
  • 程序集部署和NuGet包安装
  • 通过设计器或代码添加SfNumericTextBox
  • 命名空间导入
  • 设置数值（Value属性）
  • 基础格式模式
  • 水印文本基础
  • 最小/最大值设置

Format Modes

格式模式

📄 Read: references/format-modes.md
When to read: Formatting numbers in different modes, cultural support
Topics covered:
  • FormatMode property (Numeric, Currency, Percent)
  • Numeric format mode with decimal control
  • Currency formatting with symbols
  • Percent mode for percentage values
  • Culture-specific formatting
  • NumberFormatInfo customization
  • Decimal separators and group separators
  • Practical examples for each mode
📄 阅读： references/format-modes.md
适用场景： 不同模式下的数值格式化、文化适配支持
涵盖主题：
  • FormatMode属性（数值、货币、百分比）
  • 带小数控制的数值格式模式
  • 带符号的货币格式化
  • 适用于百分比数值的百分比模式
  • 特定文化的格式化
  • NumberFormatInfo自定义
  • 小数分隔符和组分隔符
  • 每种模式的实际示例

Formatting Options

格式化选项

📄 Read: references/formatting-options.md
When to read: Hiding zeros, adding units, displaying watermarks
Topics covered:
  • Hiding trailing zeros (HideTrailingZeros property)
  • Prefix and suffix for custom units
  • Watermark text implementation
  • WatermarkText property and AllowNull
  • Combining watermark with format modes
  • Display examples
  • Edge cases and best practices
📄 阅读： references/formatting-options.md
适用场景： 隐藏零值、添加单位、展示水印
涵盖主题：
  • 隐藏尾随零（HideTrailingZeros属性）
  • 自定义单位的前缀和后缀
  • 水印文本实现
  • WatermarkText属性和AllowNull
  • 水印与格式模式结合使用
  • 展示示例
  • 边界场景和最佳实践

Validation and Value Ranges

验证和值范围

📄 Read: references/validation-and-ranges.md
When to read: Enforcing value constraints, configuring validation behavior
Topics covered:
  • MinValue and MaxValue properties
  • ValidationMode property (KeyPress vs LostFocus)
  • ValueChangeMode property (when value updates)
  • LostFocusValidation modes (Reset, MaxValue, MinValue)
  • Validation flow and event timing
  • Error scenarios and handling
  • Practical validation examples
📄 阅读： references/validation-and-ranges.md
适用场景： 强制值约束、配置验证行为
涵盖主题：
  • MinValue和MaxValue属性
  • ValidationMode属性（按键触发 vs 失焦触发）
  • ValueChangeMode属性（数值更新时机）
  • LostFocusValidation模式（重置、最大值、最小值）
  • 验证流程和事件时机
  • 错误场景和处理
  • 实际验证示例

Appearance and Styling

外观和样式

📄 Read: references/appearance-and-styling.md
When to read: Customizing colors, borders, and visual appearance
Topics covered:
  • PositiveForeColor for positive values
  • NegativeForeColor for negative values
  • ZeroForeColor for zero values
  • WatermarkForeColor for placeholder text
  • BorderColor, FocusBorderColor, HoverBorderColor
  • DisabledBorderColor for disabled state
  • BorderStyle property
  • Background and font customization
  • Visual state examples
📄 阅读： references/appearance-and-styling.md
适用场景： 自定义颜色、边框和视觉外观
涵盖主题：
  • 正数值的PositiveForeColor属性
  • 负数值的NegativeForeColor属性
  • 零值的ZeroForeColor属性
  • 占位文本的WatermarkForeColor属性
  • 边框颜色、聚焦边框颜色、悬停边框颜色
  • 禁用状态的DisabledBorderColor属性
  • BorderStyle属性
  • 背景和字体自定义
  • 视觉状态示例

Events and Advanced Patterns

事件和高级模式

📄 Read: references/events-and-advanced.md
When to read: Handling value changes, advanced scenarios
Topics covered:
  • ValueChanged event and subscription
  • ValueChangedEventArgs (OldValue, NewValue)
  • Event timing and validation interaction
  • Responding to value changes
  • Advanced patterns (conditional formatting, cascading updates)
  • Performance considerations
  • Common event patterns
📄 阅读： references/events-and-advanced.md
适用场景： 处理数值变化、高级场景
涵盖主题：
  • ValueChanged事件和订阅
  • ValueChangedEventArgs（旧值、新值）
  • 事件时机和验证交互
  • 响应数值变化
  • 高级模式（条件格式化、级联更新）
  • 性能注意事项
  • 通用事件模式

Quick Start Example

快速入门示例

Basic Numeric TextBox in Code

代码实现基础数值文本框

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

With Formatting and Validation

带格式化和验证的实现

csharp
// 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}");
};
csharp
// 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}");
};

Key Props and Methods

核心属性和方法

PropertyTypePurpose
Valuedouble?Gets or sets the numeric value
FormatModeFormatModeSets format (Numeric, Currency, Percent)
MinValuedoubleMinimum allowed value
MaxValuedoubleMaximum allowed value
AllowNullboolAllow null values in control
WatermarkTextstringPlaceholder text when empty
HideTrailingZerosboolHide zeros after decimal point
PrefixstringText prepended to value
SuffixstringText appended to value
ValidationModeValidationModeKeyPress or LostFocus
ValueChangeModeValueChangeModeWhen value property updates
NumberFormatInfoNumberFormatInfoCulture-specific number formatting
属性类型用途
Valuedouble?获取或设置数值
FormatModeFormatMode设置格式（数值、货币、百分比）
MinValuedouble允许的最小值
MaxValuedouble允许的最大值
AllowNullbool允许控件接收空值
WatermarkTextstring控件为空时的占位文本
HideTrailingZerosbool隐藏小数点后的零
Prefixstring追加在值前面的文本
Suffixstring追加在值后面的文本
ValidationModeValidationMode按键触发或失焦触发验证
ValueChangeModeValueChangeModevalue属性更新的时机
NumberFormatInfoNumberFormatInfo特定文化的数值格式化

Common Patterns

通用模式

Pattern 1: Currency Input with Range

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

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

Pattern 2: Percentage Display

模式2：百分比展示

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

Pattern 3: Measurement with Units

模式3：带单位的测量值

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

Pattern 4: Validation with Color Feedback

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

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

Next Steps

后续步骤

  1. Start here: Read getting-started.md for installation and basic setup
  2. Choose format: Explore format-modes.md for numeric, currency, or percent modes
  3. Add formatting: Check formatting-options.md for units, watermarks, and display options
  4. Enable validation: Review validation-and-ranges.md for constraints
  5. Customize appearance: Use appearance-and-styling.md for colors and borders
  6. Handle events: Implement events-and-advanced.md for dynamic behavior
  1. 从这里开始：阅读getting-started.md了解安装和基础设置
  2. 选择格式：查看format-modes.md了解数值、货币或百分比模式
  3. 添加格式化：查阅formatting-options.md了解单位、水印和展示选项
  4. 启用验证：参考validation-and-ranges.md设置值约束
  5. 自定义外观：使用appearance-and-styling.md设置颜色和边框
  6. 处理事件：参考events-and-advanced.md实现动态行为