syncfusion-winui-numberbox

实现 WinUI NumberBox

Syncfusion WinUI NumberBox（SfNumberBox）是一种高级数值输入控件，提供验证、自定义格式和交互功能，用于输入数值。

何时使用此组件

在需要以下功能时使用 NumberBox：

• 接受经过验证的数值输入
• 以货币、百分比或小数格式显示数值
• 将输入限制在特定范围内（最小值/最大值）
• 提供 UpDown 按钮以调整数值
• 支持多种数值数据类型（double、decimal、int、long 等）
• 支持通过键盘和鼠标滚轮更改数值
• 处理水印文本和占位值

组件概览

NumberBox 控件集成了以下主要功能：

• 数值验证 - 自动验证并格式化输入
• 多种格式 - 货币（C）、百分比（P）、小数（N）和自定义格式
• 数值控制 - 最小值/最大值边界和 null 处理
• 交互式调整 - UpDown 按钮、键盘方向键、鼠标滚动
• 数据类型支持 - Double、Decimal、Float、Long、Int、UInt、Byte、SByte
• 无障碍功能 - 完整的键盘导航和屏幕阅读器支持

文档与导航指南

快速入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包配置
• 在 XAML 和 C# 中添加 NumberBox
• 创建基本控件
• 支持的数据类型（Double、Decimal、Float、Long、Int、UInt、Byte、SByte）
• 占位文本和说明属性
• 标题自定义
• 按 Enter 键或失去焦点时编辑和验证数值

UpDown 按钮与数值调整

📄 阅读： references/updown-button.md

• UpDown 按钮放置模式（Hidden、Inline、Compact）
• 用于键盘/鼠标递增的 SmallChange
• 用于 Page Up/Page Down 递增的 LargeChange
• TextBox 可见性控制
• 键盘支持（方向键、Page 键）
• 通过鼠标滚动更改数值

数值格式化

📄 阅读： references/formatting.md

• CustomFormat 属性（C2、P2、N3 格式）
• NumberFormatter 类（CurrencyFormatter、PercentFormatter、DecimalFormatter）
• 支持区域/区域性设置的货币格式
• 百分比和小数格式
• 整数位数和小数位数控制
• 特定区域性格式
• 同时处理 CustomFormat 和 NumberFormatter

数值限制与验证

📄 阅读： references/restrictions.md

• 用于处理 null 数值的 AllowNull 属性
• Minimum 和 Maximum 边界
• 范围验证行为
• 用于只读模式的 IsEditable 属性
• 文本编辑限制
• AllowNull=false 时的默认值回退

快速入门示例

基本 NumberBox 设置

XAML：

<editors:SfNumberBox 
    x:Name="priceInput"
    HorizontalAlignment="Center"
    VerticalAlignment="Center"
    Header="Price"
    Value="0"
    Minimum="0"
    Maximum="999.99"
    CustomFormat="C2" />

C#：

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;
};

常见实现模式

模式 1：货币输入字段

适用场景： 用户需要输入金额

<editors:SfNumberBox 
    Header="Amount"
    Value="0"
    CustomFormat="C2"
    Minimum="0"
    Maximum="10000"
    AllowNull="False"
    SmallChange="1" />

模式 2：百分比输入字段

适用场景： 用户需要输入百分比数值

<editors:SfNumberBox 
    Header="Discount"
    Value="0"
    CustomFormat="P2"
    Minimum="0"
    Maximum="100"
    SmallChange="5" />

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

适用场景： 用户选择离散数量

<editors:SfNumberBox 
    Header="Quantity"
    Value="1"
    Minimum="1"
    Maximum="100"
    UpDownPlacementMode="Inline"
    SmallChange="1"
    AllowNull="False" />

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

适用场景： 显示数值并提供 UpDown 按钮，但禁止键入

<editors:SfNumberBox 
    Value="50"
    IsEditable="False"
    UpDownPlacementMode="Inline"
    SmallChange="1" />

模式 5：高精度小数输入

适用场景： 需要进行财务或科学计算

<editors:SfNumberBox 
    ValueType="Decimal"
    Value="1234.56"
    CustomFormat="0.00"
    Minimum="0"
    Maximum="999999.99" />

关键属性速查

数值属性

• Value - 当前数值
• ValueType - 数据类型（Double、Decimal、Float、Long、Int、UInt、Byte、SByte）
• AllowNull - 允许 null/空值（默认值：True）

格式化属性

• CustomFormat - 格式字符串（C2=货币、P2=百分比、N3=小数）
• NumberFormatter - 高级格式化器对象
• Culture - 特定区域性的格式化

范围属性

• Minimum - 允许的最小值
• Maximum - 允许的最大值

显示属性

• Header - 标签文本
• HeaderTemplate - 自定义标题布局
• PlaceholderText - 内容为空时显示的水印
• Description - 控件下方的帮助文本
• ShowClearButton - 显示/隐藏清除按钮

交互属性

• UpDownPlacementMode - 按钮位置（Hidden、Inline、Compact）
• SmallChange - 通过箭头/滚动调整的增量（默认值：1）
• LargeChange - 通过 Page 键调整的增量（默认值：10）
• IsEditable - 是否允许输入文本（默认值：True）
• TextBoxVisibility - 显示/隐藏文本框

事件

• ValueChanged - 验证后值发生变化时触发

常见用例

1. 价格输入 - 使用 C2 格式，并设置合理的最小值/最大值
2. 年龄输入 - 使用 int ValueType，并设置 0-150 的范围
3. 折扣字段 - 使用 P2 格式，并设置 0-100 的范围
4. 数量选择器 - 使用 Inline UpDown，并设置实用的限制
5. 百分比计算 - 使用 P2 格式，并设置合适的小数位数
6. 付款金额 - 使用 C2 格式，并遵循货币规则
7. 小数精度 - 财务数据使用 Decimal 类型

安装

NuGet 包

Install-Package Syncfusion.Editors.WinUI

XAML 命名空间

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

后续步骤

• 阅读入门指南，了解设置详情
• 查看UpDown 按钮功能，了解数值调整
• 探索数值格式化，了解货币/百分比支持
• 查看数值限制，了解验证和范围限制