syncfusion-maui-toolkit-time-picker

实现 Syncfusion .NET MAUI TimePicker

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

何时使用此技能

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

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

组件概述

SfTimePicker 提供：

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

文档与导航指南

入门

📄 阅读： references/getting-started.md

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

涵盖内容：

• NuGet 包安装（Syncfusion.Maui.Toolkit）
• 注册处理程序（MauiProgram.cs 中的 ConfigureSyncfusionToolkit）
• 基本 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 事件
  • TimePickerSelectionChangedEventArgs，包含 NewValue 和 OldValue
  • IsSelectionImmediate 行为（立即选择与延迟选择）
• 对话框模式事件：
  • Opened 事件（选择器打开时）
  • Closing 事件，带有 CancelEventArgs（可以取消关闭）
  • 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
• 项目文本样式
• 完整的自定义示例

无障碍与本地化

📄 阅读： references/accessibility-localization.md

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

涵盖内容：

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