syncfusion-winforms-double-textbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WinForms DoubleTextBox

实现Syncfusion WinForms DoubleTextBox

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Accept and display double-precision floating-point values in a Windows Forms application
Implement numeric input with customizable decimal places and group separators
Apply min/max value constraints to numeric input
Handle value change events or keyboard shortcuts for incrementing/decrementing values
Override the control's default keystroke handling for custom behavior
Apply visual styling based on positive, negative, or zero values

当你需要完成以下需求时可使用本技能：

在Windows Forms应用中接收并展示双精度浮点值
实现可自定义小数位数和分组分隔符的数字输入功能
为数字输入添加最大值/最小值约束
处理数值变化事件，或支持通过快捷键增减数值
重写控件默认的按键处理逻辑以实现自定义行为
根据数值为正、负或零应用不同的视觉样式

Component Overview

组件概述

The DoubleTextBox is a specialized text box control derived from the Windows Forms Framework that handles double data type values. It provides:

Automatic double value validation and formatting
Customizable number display (decimal digits, separators, patterns)
Min/max value constraints
Event handling for value changes and keyboard input
Keyboard shortcut support for incrementing/decrementing values
Extensibility through method overrides

DoubleTextBox 是派生自Windows Forms框架的专用文本框控件，用于处理双精度数据类型值，它提供以下能力：

自动双精度数值校验和格式化
可自定义的数字展示（小数位数、分隔符、展示模式）
最大值/最小值约束
数值变化和键盘输入的事件处理
支持通过快捷键增减数值
支持通过重写方法扩展功能

Documentation Navigation Guide

文档导航指南

Getting Started

入门

📄 Read: references/getting-started.md

Assembly deployment and setup
Adding control via designer
Adding control via C# code
Setting maximum and minimum values
Customizing number format

📄 阅读： references/getting-started.md

程序集部署和配置
通过设计器添加控件
通过C#代码添加控件
设置最大值和最小值
自定义数字格式

Number and Format Settings

数值与格式设置

📄 Read: references/number-and-format-settings.md

Number formatting properties overview
Decimal digits and separators
Value range configuration (MaxValue/MinValue)
Banner text support
Hiding trailing zeros

📄 阅读： references/number-and-format-settings.md

数字格式化属性概览
小数位数与分隔符配置
数值范围配置（MaxValue/MinValue）
占位提示文本支持
隐藏末尾零

Appearance and Behavior

外观与行为

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

Border style settings
Color settings for value states
Keyboard support configuration
Overflow indicator display
Active when disabled behavior

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

边框样式设置
不同数值状态的颜色配置
键盘支持配置
溢出指示器展示
禁用状态下的交互行为配置

Event Handling and Customization

事件处理与自定义

📄 Read: references/event-handling-and-customization.md

DoubleValueChanged event handling
Keyboard events for increment/decrement
Overriding control behavior
Custom HandleSubtractKey implementation
Extending control functionality

📄 阅读： references/event-handling-and-customization.md

DoubleValueChanged事件处理
数值增减的键盘事件处理
重写控件行为
自定义HandleSubtractKey实现
扩展控件功能

Quick Start Example

快速开始示例

Basic setup in C#:

csharp

using Syncfusion.Windows.Forms.Tools;

// Create instance
DoubleTextBox doubleTextBox1 = new DoubleTextBox();
this.Controls.Add(doubleTextBox1);

// Set value constraints
doubleTextBox1.MaxValue = 100;
doubleTextBox1.MinValue = 0;

// Handle value changes
doubleTextBox1.DoubleValueChanged += (s, e) => 
    MessageBox.Show("Value changed");

Key properties:

```
DoubleValue
```
- Gets or sets the double value
```
MaxValue
```
- Maximum allowed value
```
MinValue
```
- Minimum allowed value
```
NumberDecimalDigits
```
- Number of decimal places to display
```
NumberDecimalSeparator
```
- Character used as decimal separator
```
NumberGroupSeparator
```
- Character used as thousands separator

C#基础配置：

csharp

using Syncfusion.Windows.Forms.Tools;

// Create instance
DoubleTextBox doubleTextBox1 = new DoubleTextBox();
this.Controls.Add(doubleTextBox1);

// Set value constraints
doubleTextBox1.MaxValue = 100;
doubleTextBox1.MinValue = 0;

// Handle value changes
doubleTextBox1.DoubleValueChanged += (s, e) => 
    MessageBox.Show("Value changed");

核心属性：

```
DoubleValue
```
- 获取或设置双精度数值
```
MaxValue
```
- 允许输入的最大值
```
MinValue
```
- 允许输入的最小值
```
NumberDecimalDigits
```
- 展示的小数位数
```
NumberDecimalSeparator
```
- 用作小数分隔符的字符
```
NumberGroupSeparator
```
- 用作千位分隔符的字符

Common Patterns

常见使用模式

Pattern 1: Accept Percentage Input (0-100)

模式1：接收百分比输入（0-100）

csharp

doubleTextBox1.MinValue = 0;
doubleTextBox1.MaxValue = 100;
doubleTextBox1.NumberDecimalDigits = 2;
doubleTextBox1.Text = "50";

csharp

doubleTextBox1.MinValue = 0;
doubleTextBox1.MaxValue = 100;
doubleTextBox1.NumberDecimalDigits = 2;
doubleTextBox1.Text = "50";

Pattern 2: Accept Currency Values

模式2：接收货币值

csharp

doubleTextBox1.NumberDecimalDigits = 2;
doubleTextBox1.NumberGroupSeparator = ",";
doubleTextBox1.NumberDecimalSeparator = ".";
doubleTextBox1.Text = "1234.56";

csharp

doubleTextBox1.NumberDecimalDigits = 2;
doubleTextBox1.NumberGroupSeparator = ",";
doubleTextBox1.NumberDecimalSeparator = ".";
doubleTextBox1.Text = "1234.56";

Pattern 3: Increment/Decrement with Keyboard

模式3：通过键盘增减数值

csharp

doubleTextBox1.KeyDown += (s, e) =>
{
    if (e.KeyCode == Keys.Up)
        doubleTextBox1.DoubleValue++;
    else if (e.KeyCode == Keys.Down)
        doubleTextBox1.DoubleValue--;
};

csharp

doubleTextBox1.KeyDown += (s, e) =>
{
    if (e.KeyCode == Keys.Up)
        doubleTextBox1.DoubleValue++;
    else if (e.KeyCode == Keys.Down)
        doubleTextBox1.DoubleValue--;
};

Pattern 4: Allow Null/Empty Values

模式4：允许空/空白值

csharp

doubleTextBox1.AllowNull = true;
doubleTextBox1.NullString = "";
doubleTextBox1.Text = "";

csharp

doubleTextBox1.AllowNull = true;
doubleTextBox1.NullString = "";
doubleTextBox1.Text = "";

Key Properties

核心属性

Property	Type	Purpose
`DoubleValue`	double	Gets or sets the double value of the textbox
`MaxValue`	double	Maximum allowed value
`MinValue`	double	Minimum allowed value
`NumberDecimalDigits`	int	Number of decimal places to display
`NumberDecimalSeparator`	string	Decimal separator character
`NumberGroupSeparator`	string	Thousands separator character
`NumberGroupSizes`	int[]	Sizes of number groups
`NumberNegativePattern`	int	Pattern for negative numbers
`HideTrailingZeros`	bool	Hide trailing zeros in display
`AllowNull`	bool	Allow null/empty values
`NullString`	string	String representation of null

属性	类型	用途
`DoubleValue`	double	获取或设置文本框的双精度数值
`MaxValue`	double	允许输入的最大值
`MinValue`	double	允许输入的最小值
`NumberDecimalDigits`	int	展示的小数位数
`NumberDecimalSeparator`	string	小数分隔符字符
`NumberGroupSeparator`	string	千位分隔符字符
`NumberGroupSizes`	int[]	数字分组的大小
`NumberNegativePattern`	int	负数的展示模式
`HideTrailingZeros`	bool	是否隐藏展示中的末尾零
`AllowNull`	bool	是否允许空/空白值
`NullString`	string	空值的字符串表示

Common Use Cases

常见使用场景

Financial Applications - Currency input with two decimal places, value constraints
Measurement Input - Scientific data with variable decimal precision
Percentage Fields - Constrained to 0-100 range with validation
Configuration Settings - Numeric parameters for application tuning
Data Entry Forms - Validated numeric fields with formatting
Calculate Totals - Increment/decrement values with keyboard shortcuts

金融应用 - 带两位小数、数值约束的货币输入
测量值输入 - 支持可变小数精度的科学数据输入
百分比字段 - 约束在0-100范围，自带校验
配置设置 - 用于应用调优的数值参数配置
数据录入表单 - 带格式化的已校验数字字段
合计计算 - 支持通过快捷键增减数值