syncfusion-maui-toolkit-numeric-updown

Syncfusion .NET MAUI NumericUpDown

SfNumericUpDown 控件提供友好的数字输入体验，内置验证、格式设置选项以及便捷的递增／递减按钮。非常适合构建需要验证数字输入的专业表单。

何时使用此技能

在以下情况下使用此技能：

• 在 .NET MAUI 应用程序中构建数字输入字段
• 将数字格式化为货币（C2）、百分比（P2）或小数（N2）
• 将输入限制在有效范围内（Minimum/Maximum 值）
• 使用向上／向下箭头按钮或键盘控件快速调整数值
• 为空数字字段显示占位符
• 使用 OnKeyFocus 或 OnLostFocus 模式自动处理验证
• 自定义按钮、颜色、边框和字体的外观
• 支持区域性格式，以根据区域性显示数字

组件概述

SfNumericUpDown（或 NumericUpDown）控件是一种专用输入字段，用于在 .NET MAUI 应用程序中输入和编辑数值。它结合了三种交互方式：

功能：

• 接受数字输入，并可选择使用文本字段直接输入
• 提供递增／递减按钮（向上／向下箭头），以便快速调整数值
• 支持键盘导航（箭头键、Page Up/Down、Tab、Return）
• 通过可配置范围（Minimum/Maximum）执行验证
• 根据区域性、货币或自定义规范设置数字格式
• 未设置值时显示占位文本

主要特点：

• 智能验证： OnKeyFocus（实时）或 OnLostFocus（延迟）验证模式
• 灵活格式设置： 货币（C2）、百分比（P2）、小数（N2）或自定义格式
• 可自定义按钮： 放置模式（Inline、InlineVertical）、对齐方式（Left、Right、Both）、颜色和自定义模板
• 约束支持： 最小值／最大值范围、空值处理（AllowNull）、仅文本模式（IsEditable=false）
• 事件驱动： ValueChanged、Completed、Focused/Unfocused 事件，可用于表单集成
• 无障碍支持： 支持 WCAG 合规性、屏幕阅读器和仅使用键盘的导航

何时选择 NumericUpDown：

• 需要带内置递增按钮的专业数字输入控件
• 希望无需编写自定义代码即可自动验证和设置格式
• 构建财务表单（价格、折扣、百分比）
• 创建库存系统（数量、库存水平）
• 实现设置或偏好设置页面
• 需要支持区域性的数字格式

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和设置 NuGet 包
• 在 MauiProgram.cs 中注册处理程序
• 添加基本的 NumericUpDown 控件
• XAML 和 C# 初始化模式
• 首次呈现和验证模式

值管理与约束

📄 阅读： references/value-management.md

• 设置和绑定数字值
• 最小值和最大值限制
• 使用 AllowNull 属性处理空值
• 默认值和初始设置
• 使用 IsEditable 阻止手动编辑文本

格式与显示选项

📄 阅读： references/formatting-display.md

• 自定义数字格式（货币、百分比、小数）
• 占位文本和占位符颜色自定义
• 支持区域性的数字显示
• 管理最大小数位数
• 百分比显示模式（Value 与 Compute）
• 自定义格式说明符（0、#、C、P、N）

验证与事件

📄 阅读： references/validation-events.md

• 包含 OldValue 和 NewValue 的 ValueChanged 事件
• 编辑完成时触发的 Completed 事件
• Focused 和 Unfocused 事件
• ValueChangeMode（OnKeyFocus 与 OnLostFocus）
• 以编程方式管理焦点
• Return 键命令

上/下按钮控制

📄 阅读： references/buttons-updown.md

• SmallChange 和 LargeChange 增量
• 键盘快捷键（方向键、Page Up/Down）
• 支持鼠标滚轮
• 上/下按钮位置模式（Inline、InlineVertical）
• 按钮对齐方式（Left、Right、Both）
• 自定义按钮颜色
• 自定义按钮模板
• 自动反向行为

自定义与 UI 功能

📄 阅读： references/customization.md

• 边框可见性和描边颜色
• 自定义文本颜色和对齐方式
• 字体系列、大小和属性
• 清除按钮的可见性和自定义
• 光标位置和文本选择
• Return 键类型和键盘行为
• 高级样式模式
• 常见问题及故障排除