syncfusion-maui-numeric-entry

实现 .NET MAUI 数字输入框

Syncfusion .NET MAUI 数字输入框控件旨在为数值数据提供友好且高级的输入体验。它支持多种数字格式，包括货币、百分比、小数和其他可配置的数字类型。凭借丰富的功能，该控件可提升整体用户体验，同时简化数字输入验证和格式设置。

何时使用此技能

当用户需要执行以下操作时，请使用此技能：

• 接受经过验证和格式设置的数字输入
• 创建货币、百分比或小数输入字段
• 使用向上／向下按钮实现数值递增／递减
• 将数值限制在最小值和最大值范围内
• 使用特定于区域设置的模式设置数字格式
• 提供支持键盘快捷键（箭头键、翻页键）的数字输入
• 构建价格输入字段、数量选择器或评分系统
• 创建年龄输入框、折扣计算器或测量字段
• 使用按钮控件实现只读数字显示
• 为数字输入添加现代半透明玻璃效果

组件概览

Syncfusion .NET MAUI 数字输入框 (SfNumericEntry) 是一种专用输入控件，专为数值数据输入而设计，并提供高级功能：

主要功能

• 数字验证：限制字母输入，并在按下 Enter 键或失去焦点时进行验证
• 格式支持：货币 (C)、百分比 (P)、小数 (N) 和自定义格式
• 数值控件：使用向上／向下按钮、键盘箭头和鼠标滚动更改数值
• 范围限制：强制执行最小值和最大值约束
• 自定义：全面控制外观、字体、颜色、边框和按钮
• 区域设置支持：适配不同地区的数字格式
• 无障碍功能：符合 WCAG 标准，并支持 AutomationId

文档与导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 首次设置数字输入框或需要基本实现时

涵盖主题：

• 创建 .NET MAUI 项目
• 安装 Syncfusion.Maui.Inputs NuGet 包
• 在 MauiProgram.cs 中使用 ConfigureSyncfusionCore() 注册处理程序
• 添加命名空间和基本数字输入框控件（XAML/C#）
• 在按下 Enter 键或失去焦点时通过验证编辑数值
• 使用 CustomFormat 属性更改数字格式
• 使用 AllowNull 接受或限制空值
• UI 自定义（PlaceholderColor、TextColor、Font 属性）
• 光标和选择控制（CursorPosition、SelectionLength）
• 方法：Focus()、Unfocus()
• 事件：Focused、Unfocused，以及 FocusEventArgs

基本功能和配置

📄 阅读： references/basic-features.md

阅读时机： 配置占位符、清除按钮、事件、边框或文本对齐方式时

涵盖主题：

• 使用 Placeholder 属性设置占位文本
• 清除按钮的显示状态 (ShowClearButton) 和颜色 (ClearButtonColor)
• 使用 ClearButtonPath 自定义清除按钮路径
• 使用 ValueChanged 事件接收数值更改通知
• 数值更改模式（OnLostFocus、OnKeyFocus）
• Completed 事件（按下 Return 键）
• ClearButtonClicked 事件
• 边框自定义（Stroke、ShowBorder）
• 文本对齐方式（HorizontalTextAlignment、VerticalTextAlignment）
• 使用 SelectAllOnFocus 在获得焦点时选中全部文本
• 使用 ReturnType 配置键盘 Return 键类型
• 返回命令（ReturnCommand、ReturnCommandParameter）
• 用于 UI 测试和无障碍功能的 AutomationId

值格式设置

📄 阅读： references/formatting.md

阅读时机： 需要将值格式化为货币、百分比或自定义数字格式时

涵盖主题：

• 货币格式（C2）：$1,234.56
• 百分比格式（P2）：45.50%
• 小数格式（N2）：1,234.56
• 使用 0 和 # 占位符的自定义格式字符串
• 使用零占位符设置整数位数格式
• 小数位数格式
• 自定义格式组合（例如 "$00.00##"）
• 使用 Culture 属性进行基于区域性的格式设置
• 百分比显示模式（Value 或 Compute）
• 使用 MaximumNumberDecimalDigits 设置最大小数位数

值限制

📄 阅读： references/restrictions.md

阅读时机： 需要强制设置最小值／最大值或禁止空值时

涵盖主题：

• 使用 AllowNull 属性限制空值
• AllowNull 为 false 时的行为（返回 0 或 Minimum）
• 使用 Minimum 和 Maximum 将值限制在范围内
• 默认值（double.MinValue、double.MaxValue）
• 使用 IsEditable 属性禁止文本编辑
• 仍可通过按钮、按键和滚动更改值
• 范围验证和边界情况

上下按钮

📄 阅读： references/updown-buttons.md

阅读时机： 实现递增／递减按钮或通过键盘／鼠标更改值时

涵盖主题：

• 使用键盘方向键和 Page 键增大／减小值
• SmallChange（方向键、鼠标滚动、上下按钮）
• LargeChange（Page Up／Down 键）
• 上下按钮的放置模式：
  • Hidden（默认，不显示按钮）
  • Inline（水平按钮）
  • InlineVertical（垂直堆叠按钮）
• 按钮对齐方式（Left、Right、Both）
• 按钮顺序（UpThenDown、DownThenUp）
• 自定义按钮颜色（UpDownButtonColor）
• 自定义按钮模板（UpButtonTemplate、DownButtonTemplate）
• 自动反向行为（使用 AutoReverse 在最小值／最大值处重新开始）

液态玻璃效果

📄 阅读： references/liquid-glass-effect.md

阅读时机： 实现现代半透明玻璃设计（.NET 10、iOS 26+、macOS 26+）时

涵盖主题：

• 液态玻璃效果概述
• 将 Numeric Entry 包装在 SfGlassEffectView 中
• 将 Background 设置为 Transparent 以实现玻璃效果
• 配置 EffectType 和 EnableShadowEffect
• 平台要求和限制