syncfusion-winforms-percent-textbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WinForms PercentTextBox

实现Syncfusion WinForms PercentTextBox

The PercentTextBox is a textbox-derived control that enables users to display, enter, and manage percentage values in Windows Forms applications. It provides built-in formatting, validation, and data binding capabilities for percentage inputs.

PercentTextBox 是继承自文本框的控件，支持开发者在Windows Forms应用中展示、输入和管理百分比值。它为百分比输入提供了内置的格式化、验证和数据绑定能力。

When to Use This Skill

什么时候使用本技能

Use this skill when you need to:

Collect percentage values from users in a Windows Forms application
Display percentage data with consistent formatting
Validate percentage inputs within min/max bounds
Bind percentage values to data sources
Handle value changes and validation errors programmatically
Customize number formatting for percentages (decimal places, separators)
Support both percent and decimal representations of the same value

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

在Windows Forms应用中收集用户输入的百分比值
以统一的格式展示百分比数据
验证百分比输入是否在最小/最大范围内
将百分比值绑定到数据源
以编程方式处理值变更和验证错误
自定义百分比的数字格式（小数位数、分隔符）
支持同一值的百分比和小数两种表示形式

Component Overview

组件概述

PercentTextBox derives from the Windows Forms TextBox and adds:

Automatic percentage formatting and validation
Support for multiple value representations (PercentValue, DoubleValue, BindableValue)
Min/Max constraint enforcement with validation
Customizable number formatting (decimal digits, separators)
Rich event system for value changes and validation
Null value handling
Keyboard input control for negative values

PercentTextBox 继承自Windows Forms TextBox，额外提供了以下能力：

自动百分比格式化和验证
支持多种值表示形式（PercentValue、DoubleValue、BindableValue）
带验证的最小/最大约束强制执行
可自定义的数字格式（小数位数、分隔符）
用于值变更和验证的丰富事件系统
空值处理
负值的键盘输入控制

Documentation Navigation Guide

文档导航指南

Select a reference based on what you need to accomplish:

根据你需要完成的任务选择对应的参考文档：

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and assembly references
Adding control via designer and code
Basic value initialization
Minimal working example

📄 阅读： references/getting-started.md

安装和程序集引用
通过设计器和代码添加控件
基础值初始化
最小可运行示例

Value Management

值管理

📄 Read: references/value-management.md

PercentValue vs DoubleValue properties
BindableValue and BindablePercentValue for data binding
DefaultValue property usage
Value retrieval and conversion patterns

📄 阅读： references/value-management.md

PercentValue 与 DoubleValue 属性的区别
用于数据绑定的 BindableValue 和 BindablePercentValue
DefaultValue 属性的用法
值获取和转换模式

Constraints and Validation

约束与验证

📄 Read: references/constraints-and-validation.md

Setting minimum and maximum percentage values
Min/Max enforcement during validation
Null value handling (AllowNull, NullString, NullFormat)
ValidationError event handling
Validation error prevention strategies

📄 阅读： references/constraints-and-validation.md

设置百分比的最小和最大值
验证过程中最小/最大值的强制执行
空值处理（AllowNull、NullString、NullFormat）
ValidationError 事件处理
验证错误预防策略

Formatting and Display

格式化与展示

📄 Read: references/formatting-and-display.md

Customizing decimal digits (PercentDecimalDigits)
Decimal and group separators
Group size configuration
Format customization examples
Number format patterns

📄 阅读： references/formatting-and-display.md

自定义小数位数（PercentDecimalDigits）
小数和组分隔符
组大小配置
格式自定义示例
数字格式模式

Behavior and Input

行为与输入

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

Negative value input handling (NegativeInputPendingOnSelectAll)
ClipText property for unformatted text
User input processing
Keyboard behavior control

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

负值输入处理（NegativeInputPendingOnSelectAll）
用于获取未格式化文本的 ClipText 属性
用户输入处理
键盘行为控制

Events and Data Binding

事件与数据绑定

📄 Read: references/events-and-data-binding.md

BindablePercentValueChanged event
BindableValueChanged event
DoubleValueChanged event
Data binding to BindablePercentValue
Event handler implementation patterns
Responding to value changes

📄 阅读： references/events-and-data-binding.md

BindablePercentValueChanged 事件
BindableValueChanged 事件
DoubleValueChanged 事件
绑定到 BindablePercentValue
事件处理程序实现模式
响应值变更

Properties and API Reference

属性与API参考

📄 Read: references/properties-and-api-reference.md

Complete property reference organized by category
Essential methods (ResetMaxValue, ResetMinValue, etc.)
Read-only properties (FormattedText, ClipText)
Quick lookup guide for common scenarios

📄 阅读： references/properties-and-api-reference.md

按类别整理的完整属性参考
核心方法（ResetMaxValue、ResetMinValue等）
只读属性（FormattedText、ClipText）
常见场景快速查找指南

Quick Start Example

快速入门示例

Basic Setup (Designer)

基础设置（设计器）

Drag
```
PercentTextBox
```
from toolbox to form
Set
```
PercentValue
```
property to initial value (e.g., 50)
Set
```
MaxValue
```
and
```
MinValue
```
for constraints
Subscribe to
```
BindablePercentValueChanged
```
event to handle changes

将
```
PercentTextBox
```
从工具箱拖拽到窗体上
将
```
PercentValue
```
属性设置为初始值（例如50）
设置
```
MaxValue
```
和
```
MinValue
```
作为输入约束
订阅
```
BindablePercentValueChanged
```
事件来处理值变更

Basic Setup (Code)

基础设置（代码）

csharp

using Syncfusion.Windows.Forms.Tools;

// Create instance
PercentTextBox percentTextBox1 = new PercentTextBox();
this.Controls.Add(percentTextBox1);

// Set value
percentTextBox1.PercentValue = 50;

// Set constraints
percentTextBox1.MaxValue = 100;
percentTextBox1.MinValue = 0;

// Subscribe to value changed event
percentTextBox1.BindablePercentValueChanged += (sender, e) => 
{
    Console.WriteLine($"Percent: {percentTextBox1.PercentValue}%");
};

csharp

using Syncfusion.Windows.Forms.Tools;

// Create instance
PercentTextBox percentTextBox1 = new PercentTextBox();
this.Controls.Add(percentTextBox1);

// Set value
percentTextBox1.PercentValue = 50;

// Set constraints
percentTextBox1.MaxValue = 100;
percentTextBox1.MinValue = 0;

// Subscribe to value changed event
percentTextBox1.BindablePercentValueChanged += (sender, e) => 
{
    Console.WriteLine($"Percent: {percentTextBox1.PercentValue}%");
};

Common Patterns

常见模式

Pattern 1: Initialize with Default Value and Constraints

模式1：使用默认值和约束初始化

csharp

var percentBox = new PercentTextBox();
percentBox.PercentValue = 25;
percentBox.MinValue = 0;
percentBox.MaxValue = 100;
percentBox.PercentDecimalDigits = 2;

csharp

var percentBox = new PercentTextBox();
percentBox.PercentValue = 25;
percentBox.MinValue = 0;
percentBox.MaxValue = 100;
percentBox.PercentDecimalDigits = 2;

Pattern 2: Bind to Data Source

模式2：绑定到数据源

csharp

percentTextBox1.DataBindings.Add("BindablePercentValue", dataSource, "PercentageField");

csharp

percentTextBox1.DataBindings.Add("BindablePercentValue", dataSource, "PercentageField");

Pattern 3: Handle Validation Errors

模式3：处理验证错误

csharp

percentTextBox1.ValidationError += (sender, e) =>
{
    MessageBox.Show($"Invalid input: {e.ErrorMessage}");
};

csharp

percentTextBox1.ValidationError += (sender, e) =>
{
    MessageBox.Show($"Invalid input: {e.ErrorMessage}");
};

Pattern 4: Custom Number Format

模式4：自定义数字格式

csharp

percentTextBox1.PercentDecimalDigits = 3;
percentTextBox1.PercentDecimalSeparator = ".";
percentTextBox1.PercentGroupSeparator = ",";
percentTextBox1.PercentGroupSizes = new int[] { 2 };

csharp

percentTextBox1.PercentDecimalDigits = 3;
percentTextBox1.PercentDecimalSeparator = ".";
percentTextBox1.PercentGroupSeparator = ",";
percentTextBox1.PercentGroupSizes = new int[] { 2 };

Key Properties

核心属性

Property	Type	Purpose
`PercentValue`	double	Gets/sets the percentage value (0-100)
`DoubleValue`	double	Gets/sets the decimal value (0-1)
`BindablePercentValue`	double?	Nullable percent value for data binding
`BindableValue`	double?	Nullable decimal value for data binding
`MaxValue`	double	Maximum allowed value
`MinValue`	double	Minimum allowed value
`DefaultValue`	double	Default value when reset
`AllowNull`	bool	Allows null/empty input
`NullString`	string	Display text when null
`PercentDecimalDigits`	int	Number of decimal places
`PercentDecimalSeparator`	string	Decimal separator character
`PercentGroupSeparator`	string	Thousands separator
`PercentGroupSizes`	int[]	Group size for thousands
`NegativeInputPendingOnSelectAll`	bool	Allow negative on select-all

属性	类型	用途
`PercentValue`	double	获取/设置百分比值（0-100）
`DoubleValue`	double	获取/设置小数值（0-1）
`BindablePercentValue`	double?	用于数据绑定的可空百分比值
`BindableValue`	double?	用于数据绑定的可空小数值
`MaxValue`	double	允许的最大值
`MinValue`	double	允许的最小值
`DefaultValue`	double	重置时的默认值
`AllowNull`	bool	允许空/空白输入
`NullString`	string	值为空时的展示文本
`PercentDecimalDigits`	int	小数位数
`PercentDecimalSeparator`	string	小数分隔符
`PercentGroupSeparator`	string	千位分隔符
`PercentGroupSizes`	int[]	千位分组大小
`NegativeInputPendingOnSelectAll`	bool	全选时允许输入负值

Common Use Cases

常见使用场景

Use Case 1: Percentage of Total

场景1：占总计的百分比

Collect a percentage that must be between 0-100 and represents a portion of a whole.

Reference: value-management.md + constraints-and-validation.md

收集必须介于0-100之间、代表整体一部分的百分比值。

参考文档： value-management.md + constraints-and-validation.md

Use Case 2: Discount or Commission Rate

场景2：折扣或佣金费率

Accept percentage rates for calculations with specific decimal precision.

Reference: formatting-and-display.md + value-management.md

接收用于计算的百分比费率，支持指定小数精度。

参考文档： formatting-and-display.md + value-management.md

Use Case 3: Form with Validation

场景3：带验证的表单

Build a form that prevents invalid percentage entries and shows errors.

Reference: constraints-and-validation.md + events-and-data-binding.md

构建可防止无效百分比输入并展示错误提示的表单。

参考文档： constraints-and-validation.md + events-and-data-binding.md

Use Case 4: Data Binding Scenario

场景4：数据绑定场景

Bind PercentTextBox to a data model field with automatic synchronization.

Reference: events-and-data-binding.md + value-management.md

Next: Choose a reference file above based on your current need, or start with getting-started.md if new to PercentTextBox.

将PercentTextBox绑定到数据模型字段，实现自动同步。

参考文档： events-and-data-binding.md + value-management.md

下一步： 根据你当前的需求选择上面的参考文件，如果你是首次使用PercentTextBox，可以从getting-started.md开始。