syncfusion-wpf-integer-textbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing IntegerTextBox

实现IntegerTextBox控件

Comprehensive guide for implementing the Syncfusion® WPF IntegerTextBox control in Windows Presentation Foundation applications. The IntegerTextBox restricts text box input to only integer values with support for data binding, watermark, null values, validation, and extensive customization options.

本文是在Windows Presentation Foundation（WPF）应用中实现Syncfusion® WPF IntegerTextBox控件的综合指南。IntegerTextBox控件可将文本框输入限制为仅整数，支持数据绑定、水印、空值处理、验证以及丰富的自定义选项。

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Implement integer-only input controls in WPF applications
Restrict user input to integer values with validation
Set up min/max value constraints for integer inputs
Configure number formatting with culture and grouping support
Customize visual appearance with foreground colors for positive/negative/zero values
Add interactive value adjustment via arrow keys, mouse wheel, or spin buttons
Implement range adorner for visual progress indication
Handle null values and watermarks in integer input fields
Create data-bound integer inputs with MVVM pattern support
Validate integer input with multiple validation modes

This skill covers the complete IntegerTextBox control with Int64 support, providing up to 19-digit integer value handling.

当你需要以下功能时，可以使用本技能：

在WPF应用中实现仅允许整数输入的控件
通过验证限制用户输入为整数
为整数输入设置最小/最大值约束
配置支持区域性和分组的数字格式化
根据正/负/零值自定义前景色，定制视觉外观
通过方向键、鼠标滚轮或微调按钮添加交互式数值调整功能
实现范围装饰器以提供视觉进度指示
在整数输入字段中处理空值和水印
创建支持MVVM模式的数据绑定整数输入控件
通过多种验证模式验证整数输入

本技能涵盖完整的IntegerTextBox控件，支持Int64类型，可处理最多19位的整数值。

Component Overview

组件概述

The IntegerTextBox control is a specialized numeric input control from Syncfusion's WPF library that provides:

Int64 data type support (up to 19 digits)
Min/Max value validation with multiple validation modes
Culture-based number formatting with customizable separators
Visual customization including foreground colors for different value states
Interactive value adjustment via keyboard, mouse wheel, and spin buttons
Range adorner for visual progress bar-like indication
Watermark support for empty state guidance
Null value handling with configurable display
MVVM-ready with full data binding support
Built-in themes and styling options

Assembly Required:

Syncfusion.Shared.WPF

Namespace:

Syncfusion.Windows.Shared

IntegerTextBox控件是Syncfusion WPF库中的一款专用数值输入控件，具备以下特性：

Int64数据类型支持（最多19位）
多种验证模式下的最小/最大值验证
支持自定义分隔符的基于区域性的数字格式化
针对不同数值状态的视觉自定义（如前景色）
通过键盘、鼠标滚轮和微调按钮实现的交互式数值调整
类似进度条的范围装饰器视觉指示
空状态引导的水印支持
可配置显示的空值处理
支持完整数据绑定的MVVM适配
内置主题和样式选项

所需程序集：

Syncfusion.Shared.WPF

命名空间：

Syncfusion.Windows.Shared

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Read this first for initial setup and basic implementation:

Assembly deployment and NuGet package installation
Adding IntegerTextBox via designer, XAML, or C#
Basic property configuration
Data binding setup with ViewModel pattern
Initial min/max value restrictions
Basic formatting examples

📄 阅读： references/getting-started.md

首次使用请先阅读本文，了解初始设置和基础实现：

程序集部署与NuGet包安装
通过设计器、XAML或C#添加IntegerTextBox
基础属性配置
结合ViewModel模式的数据绑定设置
初始最小/最大值限制
基础格式化示例

Value Management

数值管理

📄 Read: references/value-management.md

For managing integer values and user interactions:

Value property usage and binding
Paste mode configuration (Default vs Advanced)
Spin button implementation for increment/decrement
ValueChanged event handling
Null value display with NullValue property
Watermark text configuration and customization
Watermark templates for visual enhancement

📄 阅读： references/value-management.md

了解整数值管理和用户交互相关内容：

Value属性的使用与绑定
粘贴模式配置（默认模式 vs 高级模式）
用于增减数值的微调按钮实现
ValueChanged事件处理
结合NullValue属性的空值显示
水印文本的配置与自定义
用于视觉增强的水印模板

Validation and Restrictions

验证与限制

📄 Read: references/validation-restrictions.md

For input validation and value constraints:

MinValue and MaxValue property configuration
Validation modes (OnKeyPress vs OnLostFocus)
MaxValueOnExceedMaxDigit and MinValueOnExceedMinDigit behavior
Read-only mode with caret visibility
InvalidValueBehavior options (DisplayErrorMessage, ResetValue, None)
ValidationValue property for custom validation
Complete validation workflow examples

📄 阅读： references/validation-restrictions.md

了解输入验证与数值约束相关内容：

MinValue和MaxValue属性配置
验证模式（OnKeyPress vs OnLostFocus）
超出最大位数时的MaxValueOnExceedMaxDigit行为与超出最小位数时的MinValueOnExceedMinDigit行为
支持光标可见性的只读模式
InvalidValueBehavior选项（DisplayErrorMessage、ResetValue、None）
用于自定义验证的ValidationValue属性
完整的验证工作流示例

Formatting and Culture

格式化与区域性

📄 Read: references/formatting-culture.md

For number formatting and internationalization:

Culture property for globalization support
NumberFormat with NumberFormatInfo customization
NumberGroupSeparator configuration
NumberGroupSizes for custom grouping patterns
GroupSeperatorEnabled property
Priority rules (dedicated properties vs NumberFormat vs Culture)
Multiple culture examples (US, Latin, custom)

📄 阅读： references/formatting-culture.md

了解数字格式化与国际化相关内容：

支持全球化的Culture属性
结合NumberFormatInfo自定义的NumberFormat
NumberGroupSeparator配置
用于自定义分组模式的NumberGroupSizes
GroupSeperatorEnabled属性
优先级规则（专用属性 vs NumberFormat vs Culture）
多区域性示例（美国、拉丁语系、自定义）

Appearance and Customization

外观与自定义

📄 Read: references/appearance-customization.md

For visual styling and appearance control:

PositiveForeground, NegativeForeground, and ZeroColor properties
ApplyNegativeForeground and ApplyZeroColor configuration
Background and CornerRadius customization
SelectionBrush and SelectionOpacity for text selection
TextAlignment options (Left, Center, Right)
ToolTip configuration
Complete visual customization examples

📄 阅读： references/appearance-customization.md

了解视觉样式与外观控制相关内容：

PositiveForeground、NegativeForeground和ZeroColor属性
ApplyNegativeForeground和ApplyZeroColor配置
背景与CornerRadius自定义
用于文本选择的SelectionBrush和SelectionOpacity
文本对齐选项（左对齐、居中、右对齐）
工具提示配置
完整的视觉自定义示例

Step Interval and Scrolling

步长间隔与滚动

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

For interactive value adjustment features:

ScrollInterval property for increment/decrement steps
Up/Down arrow key behavior
Mouse wheel scrolling with IsScrollingOnCircle
Click and drag scrolling with EnableExtendedScrolling
TextSelectionOnFocus for auto-selection behavior
Complete interactive input examples

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

了解交互式数值调整功能相关内容：

用于增减步长的ScrollInterval属性
上下方向键行为
结合IsScrollingOnCircle的鼠标滚轮滚动
结合EnableExtendedScrolling的点击拖动滚动
用于自动选择行为的TextSelectionOnFocus
完整的交互式输入示例

Range Adorner

范围装饰器

📄 Read: references/range-adorner.md

For visual progress indication:

EnableRangeAdorner property for progress bar-like display
RangeAdornerBackground for custom adorner colors
Value visualization between min/max range
Use cases for visual feedback

📄 阅读： references/range-adorner.md

了解视觉进度指示相关内容：

用于显示类似进度条效果的EnableRangeAdorner属性
用于自定义装饰器颜色的RangeAdornerBackground
最小/最大值范围内的数值可视化
视觉反馈的使用场景

Quick Start Example

快速入门示例

Basic 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" 
        x:Class="IntegerTextBoxSample.MainWindow"
        Title="IntegerTextBox Sample" Height="350" Width="525">
    <StackPanel Margin="20">
        <!-- Basic IntegerTextBox -->
        <syncfusion:IntegerTextBox x:Name="integerTextBox" 
                                   Width="200" 
                                   Height="30"
                                   Value="100"
                                   MinValue="0"
                                   MaxValue="1000"
                                   VerticalAlignment="Center"/>
    </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" 
        x:Class="IntegerTextBoxSample.MainWindow"
        Title="IntegerTextBox Sample" Height="350" Width="525">
    <StackPanel Margin="20">
        <!-- Basic IntegerTextBox -->
        <syncfusion:IntegerTextBox x:Name="integerTextBox" 
                                   Width="200" 
                                   Height="30"
                                   Value="100"
                                   MinValue="0"
                                   MaxValue="1000"
                                   VerticalAlignment="Center"/>
    </StackPanel>
</Window>

Basic C# Implementation

基础C#实现

csharp

using Syncfusion.Windows.Shared;
using System.Windows;

namespace IntegerTextBoxSample
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            
            // Create IntegerTextBox
            IntegerTextBox integerTextBox = new IntegerTextBox();
            integerTextBox.Width = 200;
            integerTextBox.Height = 30;
            integerTextBox.Value = 100;
            integerTextBox.MinValue = 0;
            integerTextBox.MaxValue = 1000;
            
            // Add to layout
            this.Content = integerTextBox;
        }
    }
}

csharp

using Syncfusion.Windows.Shared;
using System.Windows;

namespace IntegerTextBoxSample
{
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
            
            // Create IntegerTextBox
            IntegerTextBox integerTextBox = new IntegerTextBox();
            integerTextBox.Width = 200;
            integerTextBox.Height = 30;
            integerTextBox.Value = 100;
            integerTextBox.MinValue = 0;
            integerTextBox.MaxValue = 1000;
            
            // Add to layout
            this.Content = integerTextBox;
        }
    }
}

Common Patterns

常见模式

MVVM Data Binding Pattern

MVVM数据绑定模式

Bind IntegerTextBox to ViewModel properties for reactive UI:

xml

<syncfusion:IntegerTextBox Value="{Binding Quantity, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"
                           MinValue="1"
                           MaxValue="999"
                           Width="150"
                           Height="30"/>

csharp

using System.ComponentModel;
using System.Runtime.CompilerServices;

public class ProductViewModel : INotifyPropertyChanged
{
    private int quantity;
    
    public int Quantity
    {
        get => quantity;
        set
        {
            if (quantity != value)
            {
                quantity = value;
                OnPropertyChanged();
                // Trigger calculations or validation
            }
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged([CallerMemberName] string propertyName = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

将IntegerTextBox绑定到ViewModel属性以实现响应式UI：

xml

<syncfusion:IntegerTextBox Value="{Binding Quantity, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"
                           MinValue="1"
                           MaxValue="999"
                           Width="150"
                           Height="30"/>

csharp

using System.ComponentModel;
using System.Runtime.CompilerServices;

public class ProductViewModel : INotifyPropertyChanged
{
    private int quantity;
    
    public int Quantity
    {
        get => quantity;
        set
        {
            if (quantity != value)
            {
                quantity = value;
                OnPropertyChanged();
                // Trigger calculations or validation
            }
        }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged([CallerMemberName] string propertyName = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
    }
}

Formatted Input with Culture

支持区域性的格式化输入

Configure number formatting with group separators:

xml

<syncfusion:IntegerTextBox Value="123456789"
                           Culture="en-US"
                           GroupSeperatorEnabled="True"
                           NumberGroupSeparator=","
                           Width="200"
                           Height="30"/>

配置带有组分隔符的数字格式化：

xml

<syncfusion:IntegerTextBox Value="123456789"
                           Culture="en-US"
                           GroupSeperatorEnabled="True"
                           NumberGroupSeparator=","
                           Width="200"
                           Height="30"/>

Interactive Spinner Pattern

交互式微调器模式

Enable spin buttons for easy value adjustment:

xml

<syncfusion:IntegerTextBox Value="50"
                           MinValue="0"
                           MaxValue="100"
                           ScrollInterval="5"
                           ShowSpinButton="True"
                           IsScrollingOnCircle="True"
                           Width="150"
                           Height="30"/>

启用微调按钮以方便调整数值：

xml

<syncfusion:IntegerTextBox Value="50"
                           MinValue="0"
                           MaxValue="100"
                           ScrollInterval="5"
                           ShowSpinButton="True"
                           IsScrollingOnCircle="True"
                           Width="150"
                           Height="30"/>

Range Adorner Visualization

范围装饰器可视化

Show visual progress indication based on value:

xml

<syncfusion:IntegerTextBox Value="60"
                           MinValue="0"
                           MaxValue="100"
                           EnableRangeAdorner="True"
                           RangeAdornerBackground="LightBlue"
                           Width="200"
                           Height="30"/>

基于数值显示视觉进度指示：

xml

<syncfusion:IntegerTextBox Value="60"
                           MinValue="0"
                           MaxValue="100"
                           EnableRangeAdorner="True"
                           RangeAdornerBackground="LightBlue"
                           Width="200"
                           Height="30"/>

Validation with Color Feedback

带颜色反馈的验证

Visual feedback for positive, negative, and zero values:

xml

<syncfusion:IntegerTextBox Value="-50"
                           MinValue="-100"
                           MaxValue="100"
                           PositiveForeground="Green"
                           NegativeForeground="Red"
                           ApplyNegativeForeground="True"
                           ZeroColor="Gray"
                           ApplyZeroColor="True"
                           Width="150"
                           Height="30"/>

为正、负、零值提供视觉反馈：

xml

<syncfusion:IntegerTextBox Value="-50"
                           MinValue="-100"
                           MaxValue="100"
                           PositiveForeground="Green"
                           NegativeForeground="Red"
                           ApplyNegativeForeground="True"
                           ZeroColor="Gray"
                           ApplyZeroColor="True"
                           Width="150"
                           Height="30"/>

Key Properties Reference

关键属性参考

Property	Type	Default	Description
Value	int?	0	Current integer value of the control
MinValue	int	int.MinValue	Minimum allowed value
MaxValue	int	int.MaxValue	Maximum allowed value
ScrollInterval	int	1	Increment/decrement step value
ShowSpinButton	bool	false	Show up/down spinner buttons
EnableRangeAdorner	bool	false	Show progress bar-like visual
GroupSeperatorEnabled	bool	false	Enable number group separators
NumberGroupSeparator	string	Culture-based	Custom group separator character
Culture	CultureInfo	CurrentCulture	Culture for number formatting
UseNullOption	bool	false	Allow null values
NullValue	int?	null	Value to display when null
WatermarkText	string	string.Empty	Placeholder text when empty
PositiveForeground	Brush	Black	Foreground for positive values
NegativeForeground	Brush	Red	Foreground for negative values
ZeroColor	Brush	Green	Foreground for zero value
IsReadOnly	bool	false	Prevent user input
TextAlignment	TextAlignment	Left	Horizontal text alignment
CornerRadius	CornerRadius	1	Border corner rounding

属性	类型	默认值	描述
Value	int?	0	控件的当前整数值
MinValue	int	int.MinValue	允许的最小值
MaxValue	int	int.MaxValue	允许的最大值
ScrollInterval	int	1	增减数值的步长
ShowSpinButton	bool	false	显示上下微调按钮
EnableRangeAdorner	bool	false	显示类似进度条的视觉效果
GroupSeperatorEnabled	bool	false	启用数字组分隔符
NumberGroupSeparator	string	基于区域性	自定义组分隔符字符
Culture	CultureInfo	CurrentCulture	用于数字格式化的区域性
UseNullOption	bool	false	允许空值
NullValue	int?	null	空值时显示的数值
WatermarkText	string	string.Empty	空状态下的占位符文本
PositiveForeground	Brush	Black	正值的前景色
NegativeForeground	Brush	Red	负值的前景色
ZeroColor	Brush	Green	零值的前景色
IsReadOnly	bool	false	禁止用户输入
TextAlignment	TextAlignment	Left	文本水平对齐方式
CornerRadius	CornerRadius	1	边框圆角半径

Common Use Cases

常见使用场景

Form Input with Validation

带验证的表单输入

Use IntegerTextBox for forms requiring integer input with validation:

xml

<StackPanel>
    <TextBlock Text="Age:" Margin="0,0,0,5"/>
    <syncfusion:IntegerTextBox Value="{Binding Age}"
                               MinValue="0"
                               MaxValue="150"
                               MinValidation="OnKeyPress"
                               MaxValidation="OnLostFocus"
                               Width="150"
                               Height="30"/>
</StackPanel>

在需要整数输入并验证的表单中使用IntegerTextBox：

xml

<StackPanel>
    <TextBlock Text="年龄：" Margin="0,0,0,5"/>
    <syncfusion:IntegerTextBox Value="{Binding Age}"
                               MinValue="0"
                               MaxValue="150"
                               MinValidation="OnKeyPress"
                               MaxValidation="OnLostFocus"
                               Width="150"
                               Height="30"/>
</StackPanel>

Quantity Selectors

数量选择器

Perfect for e-commerce or inventory quantity selection:

xml

<syncfusion:IntegerTextBox Value="{Binding OrderQuantity}"
                           MinValue="1"
                           MaxValue="999"
                           ScrollInterval="1"
                           ShowSpinButton="True"
                           Width="100"
                           Height="30"/>

非常适合电商或库存数量选择场景：

xml

<syncfusion:IntegerTextBox Value="{Binding OrderQuantity}"
                           MinValue="1"
                           MaxValue="999"
                           ScrollInterval="1"
                           ShowSpinButton="True"
                           Width="100"
                           Height="30"/>

Settings and Configuration

设置与配置

Use for numeric settings with visual feedback:

xml

<syncfusion:IntegerTextBox Value="{Binding TimeoutSeconds}"
                           MinValue="0"
                           MaxValue="3600"
                           EnableRangeAdorner="True"
                           RangeAdornerBackground="LightGreen"
                           WatermarkText="Enter timeout (seconds)"
                           Width="200"
                           Height="30"/>

用于带有视觉反馈的数值设置：

xml

<syncfusion:IntegerTextBox Value="{Binding TimeoutSeconds}"
                           MinValue="0"
                           MaxValue="3600"
                           EnableRangeAdorner="True"
                           RangeAdornerBackground="LightGreen"
                           WatermarkText="输入超时时间（秒）"
                           Width="200"
                           Height="30"/>

Financial Applications

金融应用

Handle integer amounts with proper formatting:

xml

<syncfusion:IntegerTextBox Value="{Binding Amount}"
                           Culture="en-US"
                           GroupSeperatorEnabled="True"
                           MinValue="0"
                           MinValidation="OnKeyPress"
                           Width="200"
                           Height="30"/>

处理整数金额并应用正确的格式化：

xml

<syncfusion:IntegerTextBox Value="{Binding Amount}"
                           Culture="en-US"
                           GroupSeperatorEnabled="True"
                           MinValue="0"
                           MinValidation="OnKeyPress"
                           Width="200"
                           Height="30"/>

Progress Input

进度输入

Allow users to input progress values with visual indication:

xml

<syncfusion:IntegerTextBox Value="{Binding CompletionPercentage}"
                           MinValue="0"
                           MaxValue="100"
                           EnableRangeAdorner="True"
                           RangeAdornerBackground="CornflowerBlue"
                           ScrollInterval="10"
                           IsScrollingOnCircle="True"
                           Width="250"
                           Height="30"/>

允许用户输入进度值并提供视觉指示：

xml

<syncfusion:IntegerTextBox Value="{Binding CompletionPercentage}"
                           MinValue="0"
                           MaxValue="100"
                           EnableRangeAdorner="True"
                           RangeAdornerBackground="CornflowerBlue"
                           ScrollInterval="10"
                           IsScrollingOnCircle="True"
                           Width="250"
                           Height="30"/>

Important Notes

重要提示

Value Property vs Text Property

Value属性 vs Text属性

⚠️ Critical: Do NOT use the

Text

property to set values. Always use the

Value

property for IntegerTextBox. The

Text

property is inherited from TextBox but should not be used as it may cause unexpected behavior.

csharp

// ✅ CORRECT
integerTextBox.Value = 100;

// ❌ INCORRECT - Do not use
// integerTextBox.Text = "100";

⚠️ 注意： 请勿使用

Text

属性设置数值。始终使用IntegerTextBox的

Value

属性。

Text

属性继承自TextBox，但使用它可能导致意外行为。

csharp

// ✅ 正确用法
integerTextBox.Value = 100;

// ❌ 错误用法 - 请勿使用
// integerTextBox.Text = "100";

Null Value Display

空值显示

To display null or custom values when the control is empty:

Set
```
UseNullOption
```
to
```
true
```
Configure
```
NullValue
```
property (null or custom integer)
If both
```
NullValue
```
and
```
WatermarkText
```
are set, only
```
NullValue
```
displays

若要在控件为空时显示空值或自定义数值：

将
```
UseNullOption
```
设置为
```
true
```
配置
```
NullValue
```
属性（空值或自定义整数）
若同时设置了
```
NullValue
```
和
```
WatermarkText
```
，将仅显示
```
NullValue
```

Validation Modes

验证模式

Choose validation timing based on user experience needs:

OnKeyPress - Immediate validation, prevents invalid input (stricter)
OnLostFocus - Validation on focus loss, allows temporary invalid input (more flexible)

Next Steps: Use the navigation guide above to read specific reference files based on your implementation needs. Start with

getting-started.md

for initial setup, then explore feature-specific documentation as needed.

根据用户体验需求选择验证时机：

OnKeyPress - 即时验证，阻止无效输入（限制更严格）
OnLostFocus - 失去焦点时验证，允许临时无效输入（更灵活）

下一步： 根据你的实现需求，使用上述导航指南阅读特定的参考文档。初始设置请从

getting-started.md

开始，之后可根据需要探索特定功能的文档。