syncfusion-winforms-percent-textbox

实现 Syncfusion WinForms PercentTextBox

PercentTextBox 是一个派生自文本框的控件，可让用户在 Windows Forms 应用程序中显示、输入和管理百分比值。它为百分比输入提供内置的格式设置、验证和数据绑定功能。

何时使用此技能

在以下情况需要使用此技能：

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

组件概述

PercentTextBox 派生自 Windows Forms TextBox，并添加了以下功能：

• 自动设置百分比格式并进行验证
• 支持多种值表示形式（PercentValue、DoubleValue、BindableValue）
• 强制执行 Min/Max 限制并进行验证
• 可自定义数字格式（小数位数、分隔符）
• 丰富的值更改和验证事件系统
• 空值处理
• 控制负值的键盘输入

文档导航指南

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

入门

📄 阅读： references/getting-started.md

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

值管理

📄 阅读： references/value-management.md

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

限制和验证

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

• 设置百分比的最小值和最大值
• 验证期间强制执行 Min/Max 限制
• 空值处理（AllowNull、NullString、NullFormat）
• ValidationError 事件处理
• 防止验证错误的策略

格式设置和显示

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

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

行为和输入

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

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

事件和数据绑定

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

• BindablePercentValueChanged 事件
• BindableValueChanged 事件
• DoubleValueChanged 事件
• 将数据绑定到 BindablePercentValue
• 事件处理程序实现模式
• 响应值更改

属性和 API 参考

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

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

快速入门示例

基本设置（设计器）

1. 将 PercentTextBox 从工具箱拖到窗体上
2. 将 PercentValue 属性设置为初始值（例如，50）
3. 设置 MaxValue 和 MinValue 作为限制
4. 订阅 BindablePercentValueChanged 事件以处理更改

基本设置（代码）

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

常见模式

模式 1：使用默认值和限制进行初始化

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

模式 2：绑定到数据源

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

模式 3：处理验证错误

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

模式 4：自定义数字格式

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

主要属性

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

常见用例

用例 1：总量的百分比

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

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

用例 2：折扣率或佣金率

接受用于计算且具有特定小数精度的百分比率。

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

用例 3：带验证的表单

构建一个可阻止无效百分比输入并显示错误的表单。

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

用例 4：数据绑定场景

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

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

---

下一步： 根据当前需求选择上方的参考文件；如果刚开始使用 PercentTextBox，请从 getting-started.md 开始。