syncfusion-wpf-percent-textbox

实现 Syncfusion WPF PercentTextBox

何时使用此技能

当用户需要执行以下操作时，请使用此技能：

• 在 WPF 应用程序中实现百分比输入控件，并限制和格式化数值
• 配置数值验证，包括最小值／最大值限制和验证时机（OnKeyPress 与 OnLostFocus）
• 应用数字格式，设置区域性特定的分隔符、小数位数和分组大小
• 自定义外观，为正数、负数和零设置不同的前景色
• 启用交互功能，例如滚动间隔、鼠标滚轮支持，以及通过单击并拖动更改数值
• 使用范围装饰器显示视觉进度，展示数值相对于最小值／最大值范围的位置
• 从 ViewModel 绑定百分比数据，并通过属性更改通知进行更新
• 处理空值，设置自定义空值显示或水印文本
• 实现国际化格式，使用基于区域性的十进制分隔符、分组分隔符和百分比符号

PercentTextBox 控件将输入限制为 double 值，并将其显示为百分比，同时提供丰富的自定义选项，可用于数据绑定、验证、格式化和外观设置。

组件概览

Syncfusion WPF PercentTextBox 是一种专用输入控件，具有以下功能：

• 将输入限制为仅 double 值（不允许文本）
• 将数值显示为百分比，并支持自定义符号和模式
• 支持最小值／最大值验证，并可配置验证时机
• 为 MVVM 模式提供数据绑定支持
• 支持区域性特定的格式化，包括分组分隔符和小数位数
• 可为正数、负数和零设置不同的前景色
• 支持通过键盘方向键、鼠标滚轮和单击拖动交互式更改数值
• 包含用于直观显示进度的范围装饰器
• 支持使用水印文本处理空值
• 提供内置视觉样式和主题

文档与导航指南

入门

📄 阅读： references/getting-started.md

需要执行以下操作时，请参考本文档：

• 通过设计器、XAML 或 C# 将 PercentTextBox 添加到 WPF 项目
• 配置程序集部署和 NuGet 包（Syncfusion.Shared.WPF）
• 了解 PercentValue 属性的基本用法
• 设置控件的初始尺寸和位置
• 了解控件的基本声明模式

数值管理与绑定

📄 阅读： references/value-management.md

需要执行以下操作时，请参考本文档：

• 使用 PercentValue 属性设置和更改百分比值
• 使用 ViewModel 实现单向或双向数据绑定
• 处理 PercentValueChanged 事件以跟踪数值变化
• 使用 NullValue 和 UseNullOption 属性配置空值行为
• 在控件为空或为 null 时显示水印文本
• 使用前景色或模板自定义水印外观
• 使用 PasteMode 属性控制粘贴行为（Default 与 Advanced）
• 添加用于递增／递减数值的微调按钮

验证与限制

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

需要执行以下操作时，请参考本文档：

• 将数值限制在最小值和最大值范围内（MinValue、MaxValue）
• 配置验证时机（MinValidation、MaxValidation：OnKeyPress 与 OnLostFocus）
• 控制超出限制时的行为（MaxValueOnExceedMaxDigit、MinValueOnExceedMinDigit）
• 使用 MinPercentDecimalDigits 和 MaxPercentDecimalDigits 限制小数位数
• 了解小数位数设置的属性优先级
• 启用只读模式，同时允许选择文本并显示插入光标
• 阻止按键输入无效内容，或在焦点丢失时进行验证

数字格式和区域性

📄 阅读： references/number-formatting.md

需要以下操作时，请参阅此文档：

• 使用 Culture 属性应用特定区域性的格式
• 配置 NumberFormatInfo 以自定义数字模式
• 设置组分隔符（PercentGroupSeparator）和组大小（PercentGroupSizes）
• 自定义小数分隔符和位数
• 更改百分比符号（PercentageSymbol）
• 使用 GroupSeperatorEnabled 启用组分隔符显示
• 定义正值模式（PercentPositivePattern：4 个选项）
• 定义负值模式（PercentNegativePattern：12 个选项）
• 了解属性优先级（专用属性、NumberFormat 与 Culture）

外观自定义

📄 阅读： references/appearance-customization.md

需要以下操作时，请参阅此文档：

• 为正值设置不同的前景色（PositiveForeground）
• 使用 ApplyNegativeForeground 和 NegativeForeground 应用负值前景色
• 使用自定义颜色显示零值（ApplyZeroColor、ZeroColor）
• 自定义控件的背景画刷
• 为边框应用圆角半径
• 配置高亮文本的选取画刷和不透明度
• 使用 TextAlignment 对齐文本（左对齐、居中、右对齐）
• 添加包含自定义信息的工具提示

交互功能

📄 阅读： references/interactive-features.md

最佳实践

📄 阅读： references/best-practices.md

需要以下操作时，请参阅此文档：

• 配置值递增／递减的滚动间隔
• 启用使用向上／向下箭头键的键盘导航
• 使用 IsScrollingOnCircle 启用鼠标滚轮滚动
• 使用 EnableExtendedScrolling 启用单击并拖动来更改值
• 控制获得焦点时的文本选取行为（TextSelectionOnFocus）
• 显示用于手动递增／递减的微调按钮
• 启用范围装饰器以直观显示进度（EnableRangeAdorner）
• 自定义范围装饰器的背景色
• 了解显示范围装饰器所需的最小值／最大值要求

快速入门示例

XAML 中的基本 PercentTextBox

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:syncfusion="http://schemas.syncfusion.com/wpf"
    x:Class="PercentTextBoxSample.MainWindow">
    <Grid>
        <syncfusion:PercentTextBox x:Name="percentTextBox" 
                                   Width="150" 
                                   Height="30"
                                   PercentValue="75.5"
                                   MinValue="0"
                                   MaxValue="100"/>
    </Grid>
</Window>

C# 中的基本 PercentTextBox

using Syncfusion.Windows.Shared;

// Create instance
PercentTextBox percentTextBox = new PercentTextBox();
percentTextBox.Width = 150;
percentTextBox.Height = 30;

// Set value and limits
percentTextBox.PercentValue = 75.5;
percentTextBox.MinValue = 0;
percentTextBox.MaxValue = 100;

// Add to container
this.Content = percentTextBox;

数据绑定示例

<syncfusion:PercentTextBox PercentValue="{Binding DiscountPercentage, UpdateSourceTrigger=PropertyChanged}"
                           Width="150" Height="30"
                           MinValue="0" MaxValue="100"/>

// ViewModel.cs
public class ViewModel : INotifyPropertyChanged
{
    private double discountPercentage;
    public double DiscountPercentage
    {
        get { return discountPercentage; }
        set
        {
            discountPercentage = value;
            OnPropertyChanged(nameof(DiscountPercentage));
        }
    }

    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

常见模式

模式 1：带验证的百分比输入

需要在按键时立即验证百分比输入时：

<syncfusion:PercentTextBox PercentValue="50"
                           MinValue="0"
                           MaxValue="100"
                           MinValidation="OnKeyPress"
                           MaxValidation="OnKeyPress"
                           MaxValueOnExceedMaxDigit="True"
                           MinValueOnExceedMinDigit="True"/>

为何有效： OnKeyPress 验证可立即阻止无效输入；超出范围时，超限属性会将值重置为边界值。

模式 2：使用区域性格式化百分比

需要按特定区域性格式化百分比时：

<syncfusion:PercentTextBox PercentValue="1234.567"
                           Culture="de-DE"
                           GroupSeperatorEnabled="True"
                           PercentDecimalDigits="2"/>

为何有效： 德国区域性使用“.”作为组分隔符，使用“,”作为小数分隔符，可自动格式化显示内容。

模式 3：使用颜色区分百分比值

需要通过视觉效果区分正值、负值和零值时：

<syncfusion:PercentTextBox PercentValue="-15"
                           PositiveForeground="Green"
                           NegativeForeground="Red"
                           ApplyNegativeForeground="True"
                           ZeroColor="Gray"
                           ApplyZeroColor="True"/>

为何有效： 不同的颜色可以帮助用户快速识别值的状态，而无需读取数字。

模式 4：可滚动交互的百分比

需要通过键盘／鼠标快速调整值时：

<syncfusion:PercentTextBox PercentValue="25"
                           ScrollInterval="5"
                           IsScrollingOnCircle="True"
                           EnableExtendedScrolling="True"
                           ShowSpinButton="True"/>

为何有效： 多种交互方式（箭头键、鼠标滚轮、微调按钮、单击并拖动）可满足不同用户的偏好。

模式 5：使用范围装饰器提供视觉反馈

需要直观显示进度时：

<syncfusion:PercentTextBox PercentValue="65"
                           MinValue="0"
                           MaxValue="100"
                           EnableRangeAdorner="True"
                           RangeAdornerBackground="LightBlue"/>

为何有效： 范围装饰器会按比例填充控件背景，让用户一目了然地看到进度，类似进度条。

模式 6：使用水印显示空值

需要为空状态显示占位文本时：

<syncfusion:PercentTextBox UseNullOption="True"
                           NullValue="{x:Null}"
                           WatermarkText="Enter discount %"
                           WatermarkTextIsVisible="True"
                           WatermarkTextForeground="Gray"/>

为何有效： 控件为空时，水印可为用户提供引导，从而改善用户体验。

关键属性参考

数值属性

• PercentValue - 获取或设置百分比数值（double）
• MinValue - 允许的最小值
• MaxValue - 允许的最大值
• NullValue - 当 UseNullOption 为 true 且数值为 null 时显示的值
• UseNullOption - 启用 null 值处理

验证属性

• MinValidation - 最小值的验证时机（OnKeyPress、OnLostFocus）
• MaxValidation - 最大值的验证时机（OnKeyPress、OnLostFocus）
• MinValueOnExceedMinDigit - 超出时重置为 MinValue（bool）
• MaxValueOnExceedMaxDigit - 超出时重置为 MaxValue（bool）

格式属性

• Culture - 数字格式所用的区域性（CultureInfo）
• NumberFormat - 自定义 NumberFormatInfo 对象
• PercentGroupSeparator - 分组字符（例如，“,”）
• PercentGroupSizes - 分组大小数组（例如，{3, 2}）
• PercentDecimalSeparator - 小数点字符（例如，“.”）
• PercentDecimalDigits - 小数位数
• MinPercentDecimalDigits - 最少小数位数
• MaxPercentDecimalDigits - 最大小数位数
• PercentageSymbol - 百分比符号（默认值为“%”）
• GroupSeperatorEnabled - 显示/隐藏分组分隔符（bool）
• PercentPositivePattern - 正值格式（0-3）
• PercentNegativePattern - 负值格式（0-11）

外观属性

• PositiveForeground - 正值的前景画笔
• NegativeForeground - 负值的前景画笔
• ApplyNegativeForeground - 启用负值前景色（bool）
• ZeroColor - 零值的前景画笔
• ApplyZeroColor - 启用零值颜色（bool）
• Background - 控件背景画笔
• CornerRadius - 边框圆角半径
• SelectionBrush - 选中文本的背景
• SelectionOpacity - 选中文本的不透明度（0-1）
• TextAlignment - 文本对齐方式（Left、Center、Right）

交互属性

• ScrollInterval - 增减步长
• IsScrollingOnCircle - 启用鼠标滚轮滚动（bool）
• EnableExtendedScrolling - 启用单击并拖动滚动（bool）
• ShowSpinButton - 显示向上/向下按钮（bool）
• TextSelectionOnFocus - 获得焦点时自动选中文本（bool）
• EnableRangeAdorner - 显示范围装饰器（bool）
• RangeAdornerBackground - 范围装饰器填充画笔

水印属性

• WatermarkText - 占位文本字符串
• WatermarkTextIsVisible - 显示水印（bool）
• WatermarkTextForeground - 水印文本颜色
• WatermarkTemplate - 自定义 DataTemplate 水印

其他属性

• IsReadOnly - 禁止用户编辑（bool）
• IsReadOnlyCaretVisible - 在只读模式下显示插入符（bool）
• PasteMode - 粘贴行为（Default、Advanced）
• ToolTip - 工具提示文本或对象

常见用例

1. 折扣/税费计算器

使用 PercentTextBox 输入折扣或税率百分比，范围为 0-100%，保留 2 位小数，并立即进行验证。

2. 进度/完成度跟踪器

显示项目完成百分比，并通过范围装饰器提供视觉反馈，将范围限制在 0-100%。

3. 财务计算

处理利率、投资回报率（ROI）百分比或增长率，并使用特定区域性的格式和多位小数。

4. 调查/评分系统

收集基于百分比的评分，并使用颜色编码的前景色（高分为绿色，低分为红色）。

5. 资源分配

输入百分比分配值（例如，预算分配），并通过验证确保总值不超过 100%。

6. 配置设置

设置性能阈值、缓存大小或缓冲区百分比，并使用滚动间隔快速调整。

7. 数据分析表单

收集统计百分比，为较大的数值添加分组分隔符，并使用特定区域性的格式。

8. 仪表板控件

显示 KPI 百分比，并使用范围装饰器展示目标完成进度，同时绑定实时数据。

---

后续步骤：

1. 根据具体的实现需求阅读相应的参考文件
2. 以快速入门示例为基础
3. 应用符合使用场景的常见模式
4. 参考关键属性，微调行为和外观