syncfusion-maui-time-picker

实现 Syncfusion .NET MAUI TimePicker

Syncfusion .NET MAUI TimePicker（SfTimePicker）是一款功能强大的控件，用户可通过直观的可滚动界面选择时间值。它支持多种时间格式、自定义间隔、对话框模式、时间限制和丰富的样式选项。

何时使用此技能

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

• 在 .NET MAUI 应用程序中实现时间选择
• 将 SfTimePicker 控件添加到 XAML 或 C# 代码中
• 配置时间格式（12/24 小时制、包含/不包含秒和毫秒）
• 设置对话框或定位选择器模式
• 定义时间选择的小时/分钟/秒间隔
• 限制可选时间（营业时间、预约时段、禁用时间）
• 处理时间选择事件或使用 MVVM 命令
• 自定义选择器外观（标题、页脚、选中视图、文本显示）
• 实现无障碍或本地化时间选择器
• 排查 TimePicker 配置或行为问题

组件概述

SfTimePicker 提供：

• 14 种预定义时间格式，支持 12/24 小时制，以及小时、分钟、秒和毫秒
• 三种选择器模式：默认（内联）、对话框（弹出窗口）和 RelativeDialog（定位弹出窗口）
• 时间间隔，适用于小时、分钟、秒和毫秒
• 时间限制，包括最早/最晚时间和禁用时间
• 循环支持，可在首项和末项之间无缝导航
• 丰富的事件系统，包括选择变更、对话框生命周期和页脚按钮事件
• MVVM 支持，可通过命令实现（SelectionChangedCommand、AcceptCommand、DeclineCommand）
• 丰富的自定义选项，适用于标题、页脚、列标题、选中视图和文本显示模式
• 无障碍和本地化支持，适用于全球化应用程序

文档和导航指南

开始使用

📄 阅读： references/getting-started.md

阅读时机： 首次设置 TimePicker、安装或进行基本实现时。

涵盖内容：

• NuGet 包安装（Syncfusion.Maui.Picker）
• 处理程序注册（MauiProgram.cs 中的 ConfigureSyncfusionCore）
• SfTimePicker 基本初始化（XAML 和 C#）
• 设置标题和页脚视图
• 配置高度和宽度
• 使用 SelectedTime 属性
• 清除选中项支持

时间格式

📄 阅读： references/formatting.md

阅读时机： 配置时间显示方式（12/24 小时制、包含/不包含秒和毫秒）时。

涵盖内容：

• Format 属性概述
• 14 种预定义时间格式：
  • H_mm、H_mm_ss（24 小时制，不带前导零）
  • HH_mm、HH_mm_ss、HH_mm_ss_fff（24 小时制，带前导零）
  • h_mm_tt、h_mm_ss_tt（12 小时制，不带前导零 + AM/PM）
  • hh_mm_tt、hh_mm_ss_tt、hh_mm_ss_fff_tt、hh_tt（12 小时制，带前导零 + AM/PM）
  • mm_ss、mm_ss_fff、ss_fff（分钟/秒组合）
  • Default（基于区域性设置的格式）
• 格式使用示例以及格式间切换

选择器模式和显示

📄 阅读： references/picker-modes.md

阅读时机： 配置选择器的显示方式（内联、弹出对话框、定位对话框）时。

涵盖内容：

• Mode 属性（Default、Dialog、RelativeDialog）
• 对话框模式配置
• 使用 IsOpen 属性以编程方式控制选择器
• RelativeDialog 模式，用于显示定位弹出窗口
• RelativePosition 选项（8 种对齐位置）：
  • AlignTop、AlignBottom、AlignToLeftOf、AlignToRightOf
  • AlignTopLeft、AlignTopRight、AlignBottomLeft、AlignBottomRight
• RelativeView 属性，用于相对于特定控件定位
• 自定义弹出窗口大小（PopupWidth、PopupHeight 属性）
• 各种模式的代码示例

时间间隔与循环

📄 阅读： references/time-intervals-looping.md

何时阅读： 设置时间值之间的间隔或启用连续循环。

涵盖内容：

• HourInterval 属性（例如，每 2 小时显示一次）
• MinuteInterval 属性（例如，每 5、10、15 分钟显示一次）
• SecondInterval 属性（例如，每 10 秒显示一次）
• 用于精确选择时间的 MilliSecondInterval 属性
• 用于在首项 ↔ 末项之间无缝导航的 EnableLooping 属性
• 将间隔与不同时间格式结合使用
• 实际场景（预约、时间跟踪）

时间限制

📄 阅读： references/time-restrictions.md

何时阅读： 限制可选时间（营业时间、最小值/最大值范围、禁用时间）。

涵盖内容：

• 用于设置最早可选时间的 MinimumTime 属性
• 用于设置最晚可选时间的 MaximumTime 属性
• 用于禁用特定时间的 BlackoutTimes 集合
• 时间范围验证规则
• 使用场景（营业时间：上午 9 点至下午 5 点、预约时段、禁用午餐时间）
• 将限制与格式和间隔结合使用

事件与命令

📄 阅读： references/events-commands.md

何时阅读： 处理时间选择变更、对话框生命周期或使用 MVVM 命令。

涵盖内容：

• SelectionChanged 事件
  • 包含 NewValue 和 OldValue 的 TimePickerSelectionChangedEventArgs
  • IsSelectionImmediate 行为（立即选择与延迟选择）
• 对话框模式事件：
  • Opened 事件（选择器打开时触发）
  • 带有 CancelEventArgs 的 Closing 事件（可取消关闭）
  • Closed 事件（选择器关闭后触发）
• 底部视图事件：
  • OkButtonClicked 事件
  • CancelButtonClicked 事件
• MVVM 命令：
  • SelectionChangedCommand
  • AcceptCommand（确定按钮）
  • DeclineCommand（取消按钮）
• 事件使用模式和最佳实践

自定义与样式

📄 阅读： references/customization.md

何时阅读： 自定义选择器外观（颜色、字体、页眉/页脚、视觉效果）。

涵盖内容：

• 页眉视图自定义
  • Text、Height、Background、TextStyle 属性
• 页脚视图自定义
  • OkButtonText、CancelButtonText
  • ShowOkButton、Height、Background、TextStyle
• 列标题视图自定义
  • 每列的 Text、Height、TextStyle
• 选择视图自定义
  • Background、Stroke、StrokeThickness、CornerRadius、TextStyle
• TextDisplayMode 选项：
  • Default、Fade、Shrink、FadeAndShrink
• 用于现代 UI 的液态玻璃效果
• 项目文本样式
• 完整的自定义示例

无障碍与本地化

📄 阅读： references/accessibility-localization.md

何时阅读： 实现无障碍控件或支持多种语言/区域设置。

涵盖内容：

• WCAG 合规功能
• 屏幕阅读器支持
• 键盘导航
• 用于无障碍功能的语义属性
• 本地化配置
• 区域设置特定的时间格式
• RTL（从右到左）语言支持
• 多语言实现示例