syncfusion-wpf-currency-textbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WPF Currency TextBox

WPF CurrencyTextBox 货币输入控件

The Syncfusion WPF CurrencyTextBox is a specialized input control that restricts entry to decimal values and displays them in currency format. It provides comprehensive support for data binding, culture-specific formatting, value validation, watermarks, null values, and extensive customization options.

Syncfusion WPF CurrencyTextBox是一款专用输入控件，仅允许输入十进制数值并以货币格式显示。它全面支持数据绑定、区域文化特定格式、数值验证、水印、空值处理以及丰富的自定义选项。

When to Use This Skill

适用场景

Use this skill when implementing WPF applications that require:

Currency input fields for financial applications, invoicing, pricing, or e-commerce
Formatted decimal entry with automatic currency symbols and separators
Culture-specific formatting for international applications
Value validation with minimum/maximum restrictions
Custom number formatting with specific decimal digits, group separators, or currency symbols
Data-bound currency fields in MVVM applications
Styled financial inputs with foreground colors for positive/negative/zero values
Increment/decrement controls using keyboard arrows, mouse wheel, or spin buttons
Read-only currency displays with formatted values
Visual progress indicators for currency values within a range

在开发WPF应用时，若需要以下功能可使用该控件：

金融应用、发票系统、定价或电商场景中的货币输入字段
自动添加货币符号和分隔符的格式化十进制数值录入
面向国际用户的区域文化特定格式支持
带最小/最大值限制的数值验证
自定义小数位数、分组分隔符或货币符号的自定义数值格式
MVVM应用中的数据绑定货币字段
针对正/负/零值设置不同前景色的样式化财务输入框
支持通过键盘箭头、鼠标滚轮或微调按钮调整数值的增减控制
显示格式化数值的只读货币展示框
基于数值范围的可视化进度指示器

Component Overview

组件概述

Key Capabilities:

Restricts input to decimal values only
Automatic currency formatting with culture support
Min/Max value validation with configurable validation modes
Data binding support for MVVM patterns
Custom formatting via Culture, NumberFormatInfo, or dedicated properties
Step interval for keyboard/mouse wheel navigation
Foreground colors for positive, negative, and zero values
Watermark and null value support
Range adorner for visual progress indication
Spin buttons for value increment/decrement
Paste mode with advanced insertion behavior

Assembly:

Syncfusion.Shared.WPF

核心功能：

仅允许输入十进制数值
自动货币格式及区域文化支持
可配置验证模式的最小/最大值验证
支持MVVM模式的数据绑定
通过区域文化、NumberFormatInfo或专用属性实现自定义格式
键盘/鼠标滚轮导航的步长间隔设置
正、负、零值的前景色区分
水印和空值支持
用于可视化进度指示的范围装饰器
数值增减微调按钮
带高级插入行为的粘贴模式

程序集：

Syncfusion.Shared.WPF

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Assembly deployment and NuGet package installation
Adding CurrencyTextBox via designer, XAML, or C#
Setting and binding the Value property
Value changed notification and event handling
Basic min/max value restrictions
Introduction to step interval and culture support

📄 阅读： references/getting-started.md

程序集部署与NuGet包安装
通过设计器、XAML或C#添加CurrencyTextBox
设置与绑定Value属性
值变更通知与事件处理
基础最小/最大值限制
步长间隔与区域文化支持介绍

Formatting and Culture

格式设置与区域文化

📄 Read: references/formatting-culture.md

Culture-based formatting for international applications
NumberFormatInfo configuration (separators, symbols, decimal digits)
Dedicated formatting properties (CurrencySymbol, CurrencyGroupSeparator, etc.)
Currency group sizes and patterns
Positive and negative value patterns
Format property precedence and priority rules

📄 阅读： references/formatting-culture.md

面向国际应用的区域文化格式设置
NumberFormatInfo配置（分隔符、符号、小数位数）
专用格式属性（CurrencySymbol、CurrencyGroupSeparator等）
货币分组大小与模式
正负值显示模式
格式属性优先级规则

Validation and Restrictions

验证与限制

📄 Read: references/validation-restrictions.md

Min/Max value restrictions and validation modes
OnKeyPress vs OnLostFocus validation
MaxValueOnExceedMaxDigit and MinValueOnExceedMinDigit behavior
Decimal digit restrictions (min/max decimal places)
Read-only mode with caret visibility options

📄 阅读： references/validation-restrictions.md

最小/最大值限制与验证模式
OnKeyPress与OnLostFocus验证对比
MaxValueOnExceedMaxDigit和MinValueOnExceedMinDigit行为
小数位数限制（最小/最大小数位）
带光标可见性选项的只读模式

Step Interval and Scrolling

步长间隔与滚动

📄 Read: references/step-interval-scrolling.md

ScrollInterval property for increment/decrement amounts
Arrow key navigation (up/down)
Mouse wheel scrolling with IsScrollingOnCircle
Click-and-drag scrolling with EnableExtendedScrolling
Text selection on focus behavior

📄 阅读： references/step-interval-scrolling.md

用于数值增减的ScrollInterval属性
箭头键导航（上/下）
启用IsScrollingOnCircle的鼠标滚轮滚动
启用EnableExtendedScrolling的点击拖拽滚动
获取焦点时的文本选中行为

Appearance and Styling

外观与样式

📄 Read: references/appearance-styling.md

Foreground colors for positive, negative, and zero values
Background customization
Corner radius for rounded borders
Selection brush and opacity
Text alignment (left, center, right)
Tooltip configuration

📄 阅读： references/appearance-styling.md

正、负、零值的前景色设置
背景自定义
圆角边框的CornerRadius设置
选中文本的画笔与透明度
文本对齐方式（左、中、右）
提示工具（Tooltip）配置

Advanced Features

高级功能

📄 Read: references/advanced-features.md

Null values with UseNullOption and NullValue
Watermark text, templates, and styling
Paste mode (Default vs Advanced)
Spin buttons (ShowSpinButton) for UpDown controls
Range adorner for visual progress indicators
Value changed event handling

📄 阅读： references/advanced-features.md

启用UseNullOption的空值支持
水印文本、模板与样式
粘贴模式（默认 vs 高级）
显示微调按钮的ShowSpinButton
可视化进度指示的范围装饰器
值变更事件处理

Quick Start Example

快速入门示例

XAML Implementation

XAML实现

xml

<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">
    <StackPanel Margin="20">
        <!-- Basic currency input -->
        <syncfusion:CurrencyTextBox 
            x:Name="currencyTextBox" 
            Width="200" 
            Height="30"
            Value="1234.56" />
        
        <!-- With min/max validation -->
        <syncfusion:CurrencyTextBox 
            Width="200" 
            Height="30"
            Value="500"
            MinValue="0"
            MaxValue="10000"
            ScrollInterval="50" />
    </StackPanel>
</Window>

xml

<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">
    <StackPanel Margin="20">
        <!-- 基础货币输入 -->
        <syncfusion:CurrencyTextBox 
            x:Name="currencyTextBox" 
            Width="200" 
            Height="30"
            Value="1234.56" />
        
        <!-- 带最小/最大值验证 -->
        <syncfusion:CurrencyTextBox 
            Width="200" 
            Height="30"
            Value="500"
            MinValue="0"
            MaxValue="10000"
            ScrollInterval="50" />
    </StackPanel>
</Window>

C# Implementation

C#实现

csharp

using Syncfusion.Windows.Shared;

// Create instance
CurrencyTextBox currencyTextBox = new CurrencyTextBox();
currencyTextBox.Width = 200;
currencyTextBox.Height = 30;

// Set value
currencyTextBox.Value = 1234.56;

// Configure validation
currencyTextBox.MinValue = 0;
currencyTextBox.MaxValue = 10000;

// Set culture for formatting
currencyTextBox.Culture = new System.Globalization.CultureInfo("en-US");

// Handle value changes
currencyTextBox.ValueChanged += (d, e) =>
{
    var oldValue = e.OldValue;
    var newValue = e.NewValue;
};

// Add to layout
this.Content = currencyTextBox;

csharp

using Syncfusion.Windows.Shared;

// 创建实例
CurrencyTextBox currencyTextBox = new CurrencyTextBox();
currencyTextBox.Width = 200;
currencyTextBox.Height = 30;

// 设置数值
currencyTextBox.Value = 1234.56;

// 配置验证
currencyTextBox.MinValue = 0;
currencyTextBox.MaxValue = 10000;

// 设置格式区域文化
currencyTextBox.Culture = new System.Globalization.CultureInfo("en-US");

// 处理值变更事件
currencyTextBox.ValueChanged += (d, e) =>
{
    var oldValue = e.OldValue;
    var newValue = e.NewValue;
};

// 添加到布局
this.Content = currencyTextBox;

Common Patterns

常见模式

Basic Currency Input with Validation

带验证的基础货币输入

xml

<syncfusion:CurrencyTextBox 
    x:Name="priceInput"
    Width="150" 
    Height="30"
    Value="99.99"
    MinValue="0"
    MaxValue="9999.99"
    ScrollInterval="10"
    ToolTip="Enter product price" />

xml

<syncfusion:CurrencyTextBox 
    x:Name="priceInput"
    Width="150" 
    Height="30"
    Value="99.99"
    MinValue="0"
    MaxValue="9999.99"
    ScrollInterval="10"
    ToolTip="输入产品价格" />

Formatted Currency with Culture

带区域文化的格式化货币

csharp

CurrencyTextBox currencyTextBox = new CurrencyTextBox();
currencyTextBox.Value = 1234567.89;
currencyTextBox.Culture = new CultureInfo("fr-FR"); // French formatting
// Result: 1 234 567,89 €

csharp

CurrencyTextBox currencyTextBox = new CurrencyTextBox();
currencyTextBox.Value = 1234567.89;
currencyTextBox.Culture = new CultureInfo("fr-FR"); // 法国格式
// 结果: 1 234 567,89 €

Custom Currency Symbol and Formatting

自定义货币符号与格式

csharp

CurrencyTextBox currencyTextBox = new CurrencyTextBox();
currencyTextBox.Value = 123456.789;
currencyTextBox.CurrencySymbol = "£";
currencyTextBox.CurrencyDecimalDigits = 2;
currencyTextBox.CurrencyGroupSeparator = ",";
currencyTextBox.CurrencyDecimalSeparator = ".";
currencyTextBox.GroupSeperatorEnabled = true;
// Result: £123,456.79

csharp

CurrencyTextBox currencyTextBox = new CurrencyTextBox();
currencyTextBox.Value = 123456.789;
currencyTextBox.CurrencySymbol = "£";
currencyTextBox.CurrencyDecimalDigits = 2;
currencyTextBox.CurrencyGroupSeparator = ",";
currencyTextBox.CurrencyDecimalSeparator = ".";
currencyTextBox.GroupSeperatorEnabled = true;
// 结果: £123,456.79

Data Binding with MVVM

MVVM数据绑定

XAML:

xml

<syncfusion:CurrencyTextBox 
    Value="{Binding Price, UpdateSourceTrigger=PropertyChanged}"
    MinValue="0"
    MaxValue="100000"
    Width="150" 
    Height="30" />

ViewModel:

csharp

public class ProductViewModel : INotifyPropertyChanged
{
    private double _price;
    public double Price
    {
        get => _price;
        set
        {
            _price = value;
            OnPropertyChanged(nameof(Price));
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

XAML:

xml

<syncfusion:CurrencyTextBox 
    Value="{Binding Price, UpdateSourceTrigger=PropertyChanged}"
    MinValue="0"
    MaxValue="100000"
    Width="150" 
    Height="30" />

ViewModel:

csharp

public class ProductViewModel : INotifyPropertyChanged
{
    private double _price;
    public double Price
    {
        get => _price;
        set
        {
            _price = value;
            OnPropertyChanged(nameof(Price));
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    protected void OnPropertyChanged(string propertyName)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

Styled with Color-Coded Values

带颜色区分的样式设置

xml

<syncfusion:CurrencyTextBox 
    x:Name="profitLoss"
    Width="150" 
    Height="30"
    Value="-250.00"
    PositiveForeground="Green"
    NegativeForeground="Red"
    ApplyNegativeForeground="True"
    ZeroColor="Gray"
    ApplyZeroColor="True" />

xml

<syncfusion:CurrencyTextBox 
    x:Name="profitLoss"
    Width="150" 
    Height="30"
    Value="-250.00"
    PositiveForeground="Green"
    NegativeForeground="Red"
    ApplyNegativeForeground="True"
    ZeroColor="Gray"
    ApplyZeroColor="True" />

Currency Input with Spin Buttons

带微调按钮的货币输入

xml

<syncfusion:CurrencyTextBox 
    Width="150" 
    Height="30"
    Value="100"
    MinValue="0"
    MaxValue="1000"
    ScrollInterval="25"
    ShowSpinButton="True" />

xml

<syncfusion:CurrencyTextBox 
    Width="150" 
    Height="30"
    Value="100"
    MinValue="0"
    MaxValue="1000"
    ScrollInterval="25"
    ShowSpinButton="True" />

With Watermark for Empty State

带空状态水印

xml

<syncfusion:CurrencyTextBox 
    Width="150" 
    Height="30"
    UseNullOption="True"
    WatermarkText="Enter amount"
    WatermarkTextIsVisible="True"
    WatermarkTextForeground="Gray" />

xml

<syncfusion:CurrencyTextBox 
    Width="150" 
    Height="30"
    UseNullOption="True"
    WatermarkText="输入金额"
    WatermarkTextIsVisible="True"
    WatermarkTextForeground="Gray" />

Key Properties Reference

核心属性参考

Essential Properties

必备属性

Property	Type	Description
`Value`	`double`	Gets or sets the currency value. Use this instead of `Text` property.
`MinValue`	`double`	Minimum allowed value.
`MaxValue`	`double`	Maximum allowed value.
`Culture`	`CultureInfo`	Culture for formatting decimal and group separators.
`ScrollInterval`	`double`	Increment/decrement amount for arrow keys and mouse wheel. Default: 1.

属性	类型	描述
`Value`	`double`	获取或设置货币数值。请使用该属性而非 `Text` 属性。
`MinValue`	`double`	允许的最小数值。
`MaxValue`	`double`	允许的最大数值。
`Culture`	`CultureInfo`	用于设置小数和分组分隔符的区域文化。
`ScrollInterval`	`double`	键盘箭头和鼠标滚轮的数值增减步长。默认值：1。

Formatting Properties

格式设置属性

Property	Type	Description
`CurrencySymbol`	`string`	Currency symbol to display (e.g., "$", "€", "£").
`CurrencyDecimalDigits`	`int`	Number of decimal places. Default: -1 (culture default).
`CurrencyDecimalSeparator`	`string`	Decimal separator character (e.g., ".", ",").
`CurrencyGroupSeparator`	`string`	Group separator for thousands (e.g., ",", " ").
`CurrencyGroupSizes`	`Int32Collection`	Sizes of digit groups (e.g., {3} for thousands).
`GroupSeperatorEnabled`	`bool`	Enables display of group separator.
`NumberFormat`	`NumberFormatInfo`	Complete number format configuration object.
`CurrencyPositivePattern`	`int`	Pattern for positive values (0-3). See formatting reference.
`CurrencyNegativePattern`	`int`	Pattern for negative values (0-15). See formatting reference.

属性	类型	描述
`CurrencySymbol`	`string`	显示的货币符号（例如："$", "€", "£"）。
`CurrencyDecimalDigits`	`int`	小数位数。默认值：-1（使用区域文化默认值）。
`CurrencyDecimalSeparator`	`string`	小数分隔符（例如：".", ","）。
`CurrencyGroupSeparator`	`string`	千位分组分隔符（例如：",", " "）。
`CurrencyGroupSizes`	`Int32Collection`	数字分组大小（例如：{3}表示千位分组）。
`GroupSeperatorEnabled`	`bool`	是否启用分组分隔符显示。
`NumberFormat`	`NumberFormatInfo`	完整的数值格式配置对象。
`CurrencyPositivePattern`	`int`	正值显示模式（0-3）。请参考格式设置文档。
`CurrencyNegativePattern`	`int`	负值显示模式（0-15）。请参考格式设置文档。

Validation Properties

验证属性

Property	Type	Description
`MinValidation`	`MinValidation`	When to validate minimum: `OnKeyPress` or `OnLostFocus` .
`MaxValidation`	`MaxValidation`	When to validate maximum: `OnKeyPress` or `OnLostFocus` .
`MaxValueOnExceedMaxDigit`	`bool`	Set to MaxValue when input exceeds maximum.
`MinValueOnExceedMinDigit`	`bool`	Set to MinValue when input is below minimum.
`MinimumCurrencyDecimalDigits`	`int`	Minimum decimal places to display.
`MaximumCurrencyDecimalDigits`	`int`	Maximum decimal places allowed.
`IsReadOnly`	`bool`	Prevents user input when true.
`IsReadOnlyCaretVisible`	`bool`	Shows caret in read-only mode.

属性	类型	描述
`MinValidation`	`MinValidation`	最小值验证时机： `OnKeyPress` 或 `OnLostFocus` 。
`MaxValidation`	`MaxValidation`	最大值验证时机： `OnKeyPress` 或 `OnLostFocus` 。
`MaxValueOnExceedMaxDigit`	`bool`	当输入超过最大值时，是否自动设置为MaxValue。
`MinValueOnExceedMinDigit`	`bool`	当输入低于最小值时，是否自动设置为MinValue。
`MinimumCurrencyDecimalDigits`	`int`	显示的最小小数位数。
`MaximumCurrencyDecimalDigits`	`int`	允许的最大小数位数。
`IsReadOnly`	`bool`	设为true时禁止用户输入。
`IsReadOnlyCaretVisible`	`bool`	只读模式下是否显示光标。

Appearance Properties

外观属性

Property	Type	Description
`PositiveForeground`	`Brush`	Foreground color for positive values. Default: Black.
`NegativeForeground`	`Brush`	Foreground color for negative values. Default: Red.
`ApplyNegativeForeground`	`bool`	Enables negative foreground color.
`ZeroColor`	`Brush`	Foreground color when value is zero. Default: Green.
`ApplyZeroColor`	`bool`	Enables zero color.
`Background`	`Brush`	Background color of the control.
`CornerRadius`	`CornerRadius`	Corner radius for rounded borders. Default: 1.
`TextAlignment`	`TextAlignment`	Text alignment: Left, Center, or Right.
`SelectionBrush`	`Brush`	Background color for selected text.
`SelectionOpacity`	`double`	Opacity of selection brush.

属性	类型	描述
`PositiveForeground`	`Brush`	正值的前景色。默认值：黑色。
`NegativeForeground`	`Brush`	负值的前景色。默认值：红色。
`ApplyNegativeForeground`	`bool`	是否启用负值前景色。
`ZeroColor`	`Brush`	数值为零时的前景色。默认值：绿色。
`ApplyZeroColor`	`bool`	是否启用零值颜色。
`Background`	`Brush`	控件的背景色。
`CornerRadius`	`CornerRadius`	圆角边框的半径。默认值：1。
`TextAlignment`	`TextAlignment`	文本对齐方式：左对齐、居中或右对齐。
`SelectionBrush`	`Brush`	选中文本的背景色。
`SelectionOpacity`	`double`	选中文本背景的透明度。

Scrolling Properties

滚动属性

Property	Type	Description
`IsScrollingOnCircle`	`bool`	Enables mouse wheel scrolling. Default: true.
`EnableExtendedScrolling`	`bool`	Enables click-and-drag scrolling.
`TextSelectionOnFocus`	`bool`	Auto-selects text when control receives focus. Default: true.

属性	类型	描述
`IsScrollingOnCircle`	`bool`	是否启用鼠标滚轮滚动。默认值：true。
`EnableExtendedScrolling`	`bool`	是否启用点击拖拽滚动。
`TextSelectionOnFocus`	`bool`	控件获取焦点时是否自动选中文本。默认值：true。

Advanced Properties

高级属性

Property	Type	Description
`UseNullOption`	`bool`	Enables null value and watermark support.
`NullValue`	`double?`	Value to display when control is null.
`WatermarkText`	`string`	Text to display when value is null/empty.
`WatermarkTextIsVisible`	`bool`	Shows/hides watermark.
`WatermarkTextForeground`	`Brush`	Foreground color for watermark.
`WatermarkTemplate`	`DataTemplate`	Custom template for watermark appearance.
`PasteMode`	`PasteMode`	Paste behavior: `Default` or `Advanced` .
`ShowSpinButton`	`bool`	Shows UpDown spin buttons.
`EnableRangeAdorner`	`bool`	Shows visual progress indicator based on min/max.
`RangeAdornerBackground`	`Brush`	Background color of range adorner.

属性	类型	描述
`UseNullOption`	`bool`	是否启用空值和水印支持。
`NullValue`	`double?`	控件为空时显示的数值。
`WatermarkText`	`string`	数值为空时显示的文本。
`WatermarkTextIsVisible`	`bool`	是否显示水印。
`WatermarkTextForeground`	`Brush`	水印文本的前景色。
`WatermarkTemplate`	`DataTemplate`	水印外观的自定义模板。
`PasteMode`	`PasteMode`	粘贴行为： `Default` 或 `Advanced` 。
`ShowSpinButton`	`bool`	是否显示增减微调按钮。
`EnableRangeAdorner`	`bool`	是否显示基于最小/最大值的可视化进度指示器。
`RangeAdornerBackground`	`Brush`	范围装饰器的背景色。

Events

事件

Event	Description
`ValueChanged`	Raised when the Value property changes. Provides OldValue and NewValue.

事件	描述
`ValueChanged`	当Value属性变更时触发。提供旧值（OldValue）和新值（NewValue）。

Common Use Cases

常见应用场景

E-commerce Product Pricing - Currency input with validation for product prices
Financial Calculators - Loan amounts, interest rates, payment calculations
Invoicing Systems - Line items, subtotals, tax amounts, totals
Budgeting Applications - Expense tracking, budget allocation, balance display
Point of Sale Systems - Transaction amounts, discounts, change calculation
International Applications - Multi-currency support with culture-specific formatting
Accounting Software - General ledger entries, balance sheets, financial reports
Payroll Systems - Salary entry, deductions, net pay calculation
Inventory Management - Cost tracking, pricing, valuation
Donation Forms - Contribution amounts with preset increments

电商产品定价 - 带验证的货币输入框用于产品定价
金融计算器 - 贷款金额、利率、还款计算
发票系统 - 行项目、小计、税额、总计
预算应用 - 费用跟踪、预算分配、余额展示
收银系统 - 交易金额、折扣、找零计算
国际应用 - 支持多货币的区域文化特定格式
会计软件 - 总账分录、资产负债表、财务报表
薪资系统 - 薪资录入、扣除项、实发工资计算
库存管理 - 成本跟踪、定价、估值
捐赠表单 - 带预设步长的捐款金额输入

Notes

注意事项

Always use
Value
property, not
```
Text
```
, to get/set the currency amount
Format priority: Dedicated properties > NumberFormat > Culture
Validation modes: OnKeyPress prevents invalid input; OnLostFocus validates after entry
Range adorner only displays when both MinValue and MaxValue are set
Watermark only appears when UseNullOption is true and value is null/empty

请始终使用
Value
属性，而非
```
Text
```
属性来获取/设置货币金额
格式优先级：专用属性 > NumberFormat > 区域文化
验证模式：OnKeyPress模式可阻止无效输入；OnLostFocus模式在输入完成后验证
范围装饰器仅在同时设置了MinValue和MaxValue时才会显示
水印仅在UseNullOption为true且数值为空时才会显示