syncfusion-maui-masked-entry

实现 .NET MAUI 掩码输入框

Syncfusion .NET MAUI 掩码输入框（SfMaskedEntry）是一种高级输入控件，可使用可自定义的掩码模式限制并格式化用户输入。它提供自动验证、格式化和视觉反馈，适用于电话号码、日期、电子邮件、产品密钥等结构化数据的输入。

何时使用此技能

当用户需要以下功能时，请使用此技能：

• 格式化输入字段：电话号码、日期、时间、SSN、信用卡号、邮政编码、产品密钥
• 限制字符输入：仅接受特定字符（数字、字母、字母数字字符）
• 模式验证：根据固定或可变长度模式验证输入
• 自动格式化：在用户输入时应用分隔符、定界符和格式
• 特定区域性输入：处理货币符号、日期/时间分隔符和小数格式
• 带掩码的密码字段：显示/隐藏字符，并可自定义延迟时间
• 电子邮件和 URL 验证：使用 RegEx 模式进行复杂验证
• 数据输入表单：通过引导式输入和即时反馈改善用户体验
• 无障碍需求：通过提示和验证明确输入要求

组件概览

主要功能：

• 两种掩码类型：Simple（固定模式）和 RegEx（灵活模式）
• 可自定义提示字符，用于显示预期输入位置
• 灵活的值格式化（包含/排除提示字符和字面字符）
• 支持多种验证模式的实时验证
• 丰富的事件系统，可监控和控制输入
• 丰富的自定义选项（颜色、字体、边框、清除按钮）
• 支持国际格式的区域性设置
• 支持可控制可见性的密码掩码
• 集成现代 Liquid Glass 效果
• 全面的无障碍功能和自动化支持

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• 在 MauiProgram.cs 中注册处理程序
• 基本的 MaskedEntry 实现
• 设置掩码模式和类型
• 配置提示字符
• 设置和获取值
• 第一个可运行示例

掩码类型和模式

📄 阅读： references/mask-types.md

• Simple 掩码类型和元素（0、9、#、L、?、C、A、<、>）
• RegEx 掩码类型和模式
• 完整的元素参考表
• 示例：电话号码、日期、电子邮件、产品密钥
• 大小写转换和特殊字符
• 何时使用 Simple 或 RegEx
• 性能注意事项

值格式化和显示

📄 阅读： references/value-formatting.md

• ValueMaskFormat 选项
• ExcludePromptAndLiterals（仅输入内容）
• IncludePrompt（包含提示字符）
• IncludeLiterals（包含分隔符）
• IncludePromptAndLiterals（包含所有字符）
• 数据存储与显示的适用场景
• 视觉对比和示例

验证和事件

📄 阅读： references/validation-and-events.md

• ValidationMode（KeyPress、LostFocus）
• 用于表示验证状态的 HasError 属性
• Focused/Unfocused 事件
• Focus() 和 Unfocus() 方法
• ValueChanging 事件（可取消，包含 IsValid、NewValue、OldValue、Cancel）
• ValueChanged 事件（包含 IsMaskCompleted）
• Completed 事件（回车键）
• ClearButtonClicked 事件
• 事件生命周期和最佳实践

自定义和样式设置

📄 阅读： references/customization.md

• 清除按钮配置（可见性、颜色、自定义路径）
• 字体属性（大小、样式、字体系列）
• 文本和占位符样式
• 边框自定义（描边、可见性）
• 背景和透明度
• 光标位置控制
• 键盘配置
• SelectAllOnFocus 行为
• IsReadOnly 模式
• 回车键处理（ReturnType、ReturnCommand）
• 支持 UI 测试的 AutomationId
• 平台特定注意事项

高级功能

📄 阅读：references/advanced-features.md

• 文化支持（货币、日期/时间分隔符、小数/千位分隔符）
• HidePromptOnLeave，让界面更简洁
• 密码掩码（PasswordChar、PasswordDelayDuration）
• 集成 Liquid Glass Effect
• RTL 支持
• 无障碍功能
• 性能优化
• 边缘情况和故障排除