Back to Details

syncfusion-winui-numberbox

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing WinUI NumberBox

实现WinUI NumberBox

The Syncfusion WinUI NumberBox (SfNumberBox) is an advanced numeric input control that provides validation, custom formatting, and interactive features for entering numeric values.
Syncfusion WinUI NumberBox (SfNumberBox) 是一款高级数值输入控件，提供验证、自定义格式和交互功能，用于接收数值输入。

When to Use This Component

何时使用该组件

Use NumberBox when you need to:
  • Accept numeric input with validation
  • Display values in currency, percentage, or decimal formats
  • Restrict input to a specific range (min/max)
  • Provide UpDown buttons for value adjustment
  • Support multiple numeric data types (double, decimal, int, long, etc.)
  • Enable keyboard and mouse wheel value changes
  • Handle watermark text and placeholder values
当你需要实现以下需求时可使用NumberBox：
  • 接收带校验的数值输入
  • 以货币、百分比或小数格式展示数值
  • 将输入限制在特定区间（最小值/最大值）
  • 提供UpDown按钮用于调整数值
  • 支持多种数值数据类型（double、decimal、int、long等）
  • 支持通过键盘和鼠标滚轮修改数值
  • 支持水印文本和占位符值

Component Overview

组件概述

The NumberBox control combines these key features:
  • Numeric Validation - Automatically validates and formats input
  • Multiple Formats - Currency (C), Percentage (P), Decimal (N), and custom formats
  • Value Control - Min/max bounds and null handling
  • Interactive Adjustment - UpDown buttons, keyboard arrows, mouse scrolling
  • Data Type Support - Double, Decimal, Float, Long, Int, UInt, Byte, SByte
  • Accessibility - Full keyboard navigation and screen reader support
NumberBox控件包含以下核心特性：
  • 数值校验 - 自动校验并格式化输入内容
  • 多种格式 - 货币(C)、百分比(P)、小数(N)及自定义格式
  • 数值控制 - 最小值/最大值边界和空值处理
  • 交互调整 - UpDown按钮、键盘方向键、鼠标滚动调整
  • 数据类型支持 - Double、Decimal、Float、Long、Int、UInt、Byte、SByte
  • 可访问性 - 全键盘导航和屏幕阅读器支持

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and NuGet package setup
  • Adding NumberBox in XAML and C#
  • Basic control creation
  • Supported data types (Double, Decimal, Float, Long, Int, UInt, Byte, SByte)
  • Placeholder text and description properties
  • Header customization
  • Value editing and validation on Enter/focus loss
📄 阅读: references/getting-started.md
  • 安装和NuGet包设置
  • 在XAML和C#中添加NumberBox
  • 基础控件创建
  • 支持的数据类型（Double、Decimal、Float、Long、Int、UInt、Byte、SByte）
  • 占位符文本和描述属性
  • 头部自定义
  • 回车/失焦时的数值编辑和校验

UpDown Button & Value Adjustment

UpDown按钮与数值调整

📄 Read: references/updown-button.md
  • UpDown button placement modes (Hidden, Inline, Compact)
  • SmallChange for keyboard/mouse increment
  • LargeChange for Page Up/Page Down increment
  • TextBox visibility control
  • Keyboard support (Arrow, Page keys)
  • Mouse scrolling for value changes
📄 阅读: references/updown-button.md
  • UpDown按钮放置模式（Hidden、Inline、Compact）
  • 键盘/鼠标微调的步长SmallChange
  • Page Up/Page Down调整的步长LargeChange
  • 文本框可见性控制
  • 键盘支持（方向键、翻页键）
  • 鼠标滚动修改数值

Value Formatting

数值格式化

📄 Read: references/formatting.md
  • CustomFormat property (C2, P2, N3 formats)
  • NumberFormatter classes (CurrencyFormatter, PercentFormatter, DecimalFormatter)
  • Currency formatting with region/culture support
  • Percentage and decimal formatting
  • Integer and fractional digit control
  • Culture-specific formatting
  • Handling both CustomFormat and NumberFormatter
📄 阅读: references/formatting.md
  • CustomFormat属性（C2、P2、N3格式）
  • NumberFormatter类（CurrencyFormatter、PercentFormatter、DecimalFormatter）
  • 支持区域/文化的货币格式化
  • 百分比和小数格式化
  • 整数和小数位数控制
  • 特定文化格式适配
  • 同时处理CustomFormat和NumberFormatter的逻辑

Value Restrictions & Validation

数值限制与校验

📄 Read: references/restrictions.md
  • AllowNull property for null value handling
  • Minimum and Maximum bounds
  • Range validation behavior
  • IsEditable property for read-only mode
  • Text editing restrictions
  • Default value fallback when AllowNull=false
📄 阅读: references/restrictions.md
  • 用于空值处理的AllowNull属性
  • 最小值和最大值边界
  • 区间校验行为
  • 用于只读模式的IsEditable属性
  • 文本编辑限制
  • AllowNull为false时的默认值回退

Quick Start Example

快速入门示例

Basic NumberBox Setup

基础NumberBox设置

XAML:
xaml
<editors:SfNumberBox 
    x:Name="priceInput"
    HorizontalAlignment="Center"
    VerticalAlignment="Center"
    Header="Price"
    Value="0"
    Minimum="0"
    Maximum="999.99"
    CustomFormat="C2" />
C#:
csharp
SfNumberBox priceInput = new SfNumberBox();
priceInput.Header = "Price";
priceInput.Value = 0;
priceInput.Minimum = 0;
priceInput.Maximum = 999.99;
priceInput.CustomFormat = "C2";

// Handle value changes
priceInput.ValueChanged += (s, e) => {
    var newValue = e.NewValue;
    var oldValue = e.OldValue;
};
XAML:
xaml
<editors:SfNumberBox 
    x:Name="priceInput"
    HorizontalAlignment="Center"
    VerticalAlignment="Center"
    Header="Price"
    Value="0"
    Minimum="0"
    Maximum="999.99"
    CustomFormat="C2" />
C#:
csharp
SfNumberBox priceInput = new SfNumberBox();
priceInput.Header = "Price";
priceInput.Value = 0;
priceInput.Minimum = 0;
priceInput.Maximum = 999.99;
priceInput.CustomFormat = "C2";

// 处理数值变化
priceInput.ValueChanged += (s, e) => {
    var newValue = e.NewValue;
    var oldValue = e.OldValue;
};

Common Implementation Patterns

常见实现模式

Pattern 1: Currency Input Field

模式1：货币输入框

When: User needs to enter monetary amounts
xaml
<editors:SfNumberBox 
    Header="Amount"
    Value="0"
    CustomFormat="C2"
    Minimum="0"
    Maximum="10000"
    AllowNull="False"
    SmallChange="1" />
适用场景： 用户需要输入金额
xaml
<editors:SfNumberBox 
    Header="Amount"
    Value="0"
    CustomFormat="C2"
    Minimum="0"
    Maximum="10000"
    AllowNull="False"
    SmallChange="1" />

Pattern 2: Percentage Input Field

模式2：百分比输入框

When: User needs to enter percentage values
xaml
<editors:SfNumberBox 
    Header="Discount"
    Value="0"
    CustomFormat="P2"
    Minimum="0"
    Maximum="100"
    SmallChange="5" />
适用场景： 用户需要输入百分比数值
xaml
<editors:SfNumberBox 
    Header="Discount"
    Value="0"
    CustomFormat="P2"
    Minimum="0"
    Maximum="100"
    SmallChange="5" />

Pattern 3: Quantity Selector with UpDown Buttons

模式3：带UpDown按钮的数量选择器

When: User selects discrete quantities
xaml
<editors:SfNumberBox 
    Header="Quantity"
    Value="1"
    Minimum="1"
    Maximum="100"
    UpDownPlacementMode="Inline"
    SmallChange="1"
    AllowNull="False" />
适用场景： 用户选择离散数量
xaml
<editors:SfNumberBox 
    Header="Quantity"
    Value="1"
    Minimum="1"
    Maximum="100"
    UpDownPlacementMode="Inline"
    SmallChange="1"
    AllowNull="False" />

Pattern 4: Read-Only Display with Adjustment

模式4：带调整功能的只读展示

When: Display value with UpDown buttons but prevent typing
xaml
<editors:SfNumberBox 
    Value="50"
    IsEditable="False"
    UpDownPlacementMode="Inline"
    SmallChange="1" />
适用场景： 展示数值并提供UpDown按钮但禁止手动输入
xaml
<editors:SfNumberBox 
    Value="50"
    IsEditable="False"
    UpDownPlacementMode="Inline"
    SmallChange="1" />

Pattern 5: High-Precision Decimal Input

模式5：高精度小数输入

When: Financial or scientific calculations needed
xaml
<editors:SfNumberBox 
    ValueType="Decimal"
    Value="1234.56"
    CustomFormat="0.00"
    Minimum="0"
    Maximum="999999.99" />
适用场景： 需要财务或科学计算的场景
xaml
<editors:SfNumberBox 
    ValueType="Decimal"
    Value="1234.56"
    CustomFormat="0.00"
    Minimum="0"
    Maximum="999999.99" />

Key Properties Quick Reference

核心属性速查

Value Properties

数值属性

  • Value - Current numeric value
  • ValueType - Data type (Double, Decimal, Float, Long, Int, UInt, Byte, SByte)
  • AllowNull - Permit null/empty values (default: True)
  • Value - 当前数值
  • ValueType - 数据类型（Double、Decimal、Float、Long、Int、UInt、Byte、SByte）
  • AllowNull - 是否允许空/空白值（默认：True）

Formatting Properties

格式化属性

  • CustomFormat - Format string (C2=currency, P2=percent, N3=decimal)
  • NumberFormatter - Advanced formatter objects
  • Culture - Culture-specific formatting
  • CustomFormat - 格式字符串（C2=货币、P2=百分比、N3=小数）
  • NumberFormatter - 高级格式化对象
  • Culture - 特定文化格式化

Range Properties

区间属性

  • Minimum - Lowest allowed value
  • Maximum - Highest allowed value
  • Minimum - 允许的最小值
  • Maximum - 允许的最大值

Display Properties

展示属性

  • Header - Label text
  • HeaderTemplate - Custom header layout
  • PlaceholderText - Watermark when empty
  • Description - Help text below control
  • ShowClearButton - Show/hide clear button
  • Header - 标签文本
  • HeaderTemplate - 自定义头部布局
  • PlaceholderText - 为空时的水印文本
  • Description - 控件下方的帮助文本
  • ShowClearButton - 显示/隐藏清空按钮

Interaction Properties

交互属性

  • UpDownPlacementMode - Button position (Hidden, Inline, Compact)
  • SmallChange - Increment for arrows/scrolling (default: 1)
  • LargeChange - Increment for Page keys (default: 10)
  • IsEditable - Allow text input (default: True)
  • TextBoxVisibility - Show/hide text box
  • UpDownPlacementMode - 按钮位置（Hidden、Inline、Compact）
  • SmallChange - 方向键/滚动的步长（默认：1）
  • LargeChange - 翻页键的步长（默认：10）
  • IsEditable - 是否允许文本输入（默认：True）
  • TextBoxVisibility - 显示/隐藏文本框

Events

事件

  • ValueChanged - Fires when value changes after validation
  • ValueChanged - 校验通过后数值变化时触发

Common Use Cases

常见使用场景

  1. Price Input - Use C2 format, set realistic min/max bounds
  2. Age Input - Use int ValueType, set 0-150 range
  3. Discount Field - Use P2 format, set 0-100 range
  4. Quantity Picker - Use Inline UpDown, set practical limits
  5. Percentage Calculation - Use P2 format with appropriate decimals
  6. Payment Amount - Use C2 format with currency rules
  7. Decimal Precision - Use Decimal type for financial data
  1. 价格输入 - 使用C2格式，设置合理的最小/最大边界
  2. 年龄输入 - 使用int类型的ValueType，设置0-150的区间
  3. 折扣字段 - 使用P2格式，设置0-100的区间
  4. 数量选择器 - 使用Inline模式的UpDown按钮，设置合理的限制
  5. 百分比计算 - 使用P2格式并设置合适的小数位数
  6. 支付金额 - 使用C2格式并遵循货币规则
  7. 小数精度控制 - 财务数据使用Decimal类型

Installation

安装

NuGet Package

NuGet包

Install-Package Syncfusion.Editors.WinUI
Install-Package Syncfusion.Editors.WinUI

XAML Namespace

XAML命名空间

xaml
xmlns:editors="using:Syncfusion.UI.Xaml.Editors"
xaml
xmlns:editors="using:Syncfusion.UI.Xaml.Editors"

Next Steps

后续步骤

  • Read Getting Started for setup details
  • Review UpDown Button Features for value adjustment
  • Explore Value Formatting for currency/percentage support
  • Check Value Restrictions for validation and bounds
  • 阅读入门指南了解设置详情
  • 查看UpDown按钮特性了解数值调整功能
  • 探索数值格式化了解货币/百分比支持
  • 查阅数值限制了解校验和边界设置