syncfusion-winui-time-picker

WinUI TimePicker（SfTimePicker）实现指南

本指南全面介绍了如何在 Windows 桌面应用程序中实现 Syncfusion WinUI TimePicker 控件。SfTimePicker 提供直观、适合触控的界面，通过下拉式滚轮选择时间，并支持时间限制、格式设置、本地化和丰富的自定义选项。

何时使用此技能

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

• 在 WinUI 3 桌面应用程序中实现时间选择
• 添加带下拉式滚轮的时间输入控件
• 创建预约安排或时间录入表单
• 将时间选择限制在特定范围或间隔内
• 实现 12 小时或 24 小时时间格式
• 自定义下拉时间滚轮的外观
• 支持本地化时间输入和 RTL 布局
• 在 Windows 应用中验证和格式化时间输入
• 隐藏或禁用特定时间选项

组件概述

SfTimePicker 控件为 WinUI 应用程序提供现代化的时间选择体验，具有以下功能：

主要功能：

• 下拉式时间滚轮 - 通过小时、分钟和上下午（AM/PM）列选择时间
• 时间限制 - 设置最早和最晚时间，并将特定时间设为不可选
• 多种格式 - 支持 12 小时制和 24 小时制
• 本地化 - 支持多种语言和 RTL 布局
• 编辑模式 - 支持自动更正的掩码编辑或自由格式输入
• 丰富的自定义选项 - 自定义下拉按钮、标题、滚轮单元格和模板
• 验证 - 内置验证，并通过更改事件支持自定义逻辑
• 无障碍访问 - 完整的键盘导航和 WCAG 合规性

控件结构：

• 用于直接输入时间的文本编辑器
• 用于打开时间滚轮的下拉按钮
• 包含小时、分钟和上下午列的下拉滚轮
• 可选的下拉标题，用于显示提示
• 提交/取消按钮（可选）

NuGet 包： Syncfusion.Editors.WinUI

命名空间： Syncfusion.UI.Xaml.Editors

文档与导航指南

开始使用

📄 阅读： references/getting-started.md

请参考此文档完成初始设置和基本实现：

• 安装 Syncfusion.Editors.WinUI NuGet 包
• 在 XAML 和 C# 代码中添加 SfTimePicker
• 了解组件结构（编辑器、下拉菜单、滚轮）
• 使用 SelectedTime 属性以编程方式设置选定时间
• 通过下拉菜单交互式选择时间
• 使用 AllowNull 属性允许空值
• 添加标题和说明文本
• 使用 HeaderTemplate 自定义标题
• 使用 PlaceholderText 设置水印文本
• 使用 SelectedTimeChanged 处理时间更改事件

时间限制

📄 阅读： references/time-restrictions.md

请参考此文档控制时间选择：

• 使用 MinTime 和 MaxTime 属性限制可选时间
• 使用 BlackoutTimes 集合屏蔽特定时间
• 创建自定义时间间隔（例如，5 分钟或 15 分钟的增量）
• 使用 TimeFieldPrepared 事件自定义时间间隔
• 使用 ShowSubmitButtons 属性隐藏提交按钮
• 滚动滚轮时直接选择时间
• 使用 SelectedTimeChanging 事件取消时间更改
• 实现自定义验证逻辑
• 处理边界情况和验证错误

本地化和格式设置

📄 阅读： references/localization-formatting.md

使用此参考了解如何设置时间显示格式并进行本地化：

• 使用 ClockIdentifier 在 12 小时制和 24 小时制之间切换
• 使用 FlowDirection 更改 RTL 语言的流向
• 使用 Language 属性对控件进行本地化
• 使用 DisplayTimeFormat 自定义时间显示格式
• 了解格式模式（hh:mm tt、HH:mm、h:mm 等）
• 使用掩码编辑模式自动更正输入
• 使用普通编辑模式验证自由格式输入
• 输入行为和自动字段更正
• 使用 ShowClearButton 显示/隐藏清除按钮

下拉列表自定义

📄 阅读： references/dropdown-customization.md

使用此参考了解如何自定义下拉列表容器：

• 使用 DropDownButtonTemplate 自定义下拉按钮 UI
• 使用 ShowDropDownButton 属性隐藏下拉按钮
• 使用 DropDownPlacement 更改下拉列表对齐方式
• 使用 IsOpen 属性以编程方式打开/关闭下拉列表
• 使用 DropDownHeight 属性设置下拉列表高度
• 使用 VisibleItemsCount 属性控制可见项数
• 了解下拉列表智能定位
• 打开下拉列表的键盘快捷键（Alt+Down）

下拉列表标题自定义

📄 阅读： references/dropdown-header-customization.md

使用此参考了解如何自定义下拉列表标题：

• 使用 DropDownHeader 属性在下拉列表标题中添加提示
• 使用 ShowDropDownHeader 属性显示/隐藏标题
• 使用 DropDownHeaderTemplate 自定义标题外观
• 创建包含图标和文本的自定义标题布局
• 使用 ShowColumnHeaders 属性隐藏列标题
• 了解列标题自定义
• 标题样式最佳实践

下拉列表微调器自定义

📄 阅读： references/dropdown-spinner-customization.md

使用此参考了解如何自定义下拉列表微调器单元格和列：

• 使用 ItemWidth 和 ItemHeight 属性更改单元格大小
• 使用 MinItemWidth 和 MaxItemWidth 限制单元格宽度
• 使用 ItemContainerStyle 属性设置所有单元格的样式
• 使用 ItemTemplate 自定义单元格模板
• 使用 ItemTemplateSelector 设置条件单元格样式
• 使用 TimeFieldPrepared 事件自定义各个列
• 按列更改列标题、间隔和单元格大小
• 为特定时间单元格添加图标或自定义内容
• 大规模自定义时的性能优化

快速入门示例

基本 TimePicker 实现

XAML：

<Window xmlns:editors="using:Syncfusion.UI.Xaml.Editors">
    <Grid>
        <editors:SfTimePicker 
            x:Name="sfTimePicker"
            Header="Select Time"
            PlaceholderText="Pick a time"
            Width="250" />
    </Grid>
</Window>

C#：

using Syncfusion.UI.Xaml.Editors;

// Create TimePicker programmatically
SfTimePicker timePicker = new SfTimePicker();
timePicker.Header = "Select Time";
timePicker.PlaceholderText = "Pick a time";

// Set selected time
timePicker.SelectedTime = new DateTimeOffset(
    new DateTime(2024, 1, 1, 14, 30, 0));

// Handle time changed event
timePicker.SelectedTimeChanged += (s, e) => {
    var oldTime = e.OldDateTime;
    var newTime = e.NewDateTime;
    // Handle time change
};

常见模式

限制时间选择范围

将时间选择限制在工作时间内（上午 9 点至下午 5 点）：

// Requires: using Syncfusion.UI.Xaml.Editors;
sfTimePicker.MinTime = new DateTimeOffset(
    new DateTime(DateTime.Now.Year, DateTime.Now.Month, 
                 DateTime.Now.Day, 9, 0, 0));
sfTimePicker.MaxTime = new DateTimeOffset(
    new DateTime(DateTime.Now.Year, DateTime.Now.Month, 
                 DateTime.Now.Day, 17, 0, 0));

24 小时制格式

切换为 24 小时制：

<editors:SfTimePicker 
    ClockIdentifier="24HourClock"
    DisplayTimeFormat="HH:mm" />

自定义时间间隔

仅允许以 15 分钟为间隔选择时间：

using System.Collections.ObjectModel;
using Syncfusion.UI.Xaml.Editors;

sfTimePicker.TimeFieldPrepared += (s, e) => {
    if (e.Column?.Field == DateTimeField.Minute) {
        var minutes = new ObservableCollection<string>();
        for (int i = 0; i < 60; i += 15) {
            minutes.Add(i.ToString("00"));
        }
        e.Column.ItemsSource = minutes;
    }
};

禁用午餐时间

禁止在午休时间（中午 12 点至下午 1 点）选择时间：

using Syncfusion.UI.Xaml.Editors;

var blackoutTimes = new DateTimeOffsetCollection();
for (int minute = 0; minute < 60; minute++) {
    blackoutTimes.Add(new DateTimeOffset(
        new DateTime(DateTime.Now.Year, DateTime.Now.Month, 
                     DateTime.Now.Day, 12, minute, 0)));
}
sfTimePicker.BlackoutTimes = blackoutTimes;

关键属性

核心属性

属性	类型	说明
SelectedTime	DateTimeOffset?	获取或设置所选时间值
MinTime	DateTimeOffset	可选时间下限（默认值：1/1/1921 10:37:16 PM）
MaxTime	DateTimeOffset	可选时间上限（默认值：12/31/2121 10:37:16 PM）
BlackoutTimes	DateTimeOffsetCollection	禁止选择的时间集合
AllowNull	bool	允许 SelectedTime 使用 null 值（默认值：false）
PlaceholderText	string	SelectedTime 为 null 时显示的水印文本

格式属性

属性	类型	说明
ClockIdentifier	string	时钟格式：“12HourClock”或“24HourClock”
DisplayTimeFormat	string	时间显示格式模式（例如，“hh:mm tt”、“HH:mm”）
EditMode	DateTimeEditMode	编辑模式：Mask（自动更正）或 Normal（按 Enter 时验证）
ShowClearButton	bool	显示/隐藏清除按钮（默认值：true）

下拉列表属性

属性	类型	说明
ShowDropDownButton	bool	显示/隐藏下拉按钮（默认值：true）
DropDownButtonTemplate	DataTemplate	用于自定义下拉按钮的模板
DropDownPlacement	FlyoutPlacementMode	下拉列表对齐方式（Auto、Bottom、Top 等）
IsOpen	bool	以编程方式打开/关闭下拉列表
DropDownHeight	double	下拉微调器的固定高度
VisibleItemsCount	int	下拉列表中可见项的数量（默认值：-1）

下拉列表标头属性

属性	类型	说明
ShowDropDownHeader	bool	显示/隐藏下拉列表标头（默认值：false）
DropDownHeader	object	下拉列表标头的内容
DropDownHeaderTemplate	DataTemplate	用于自定义下拉列表标头的模板
ShowColumnHeaders	bool	显示/隐藏微调器中的列标题（默认值：true）

微调器自定义属性

属性	类型	说明
ItemWidth	double	微调器单元格的宽度（默认值：80）
ItemHeight	double	微调器单元格的高度（默认值：40）
MinItemWidth	double	微调器单元格的最小宽度（默认值：0）
MaxItemWidth	double	微调器单元格的最大宽度（默认值：Infinity）
ItemContainerStyle	Style	应用于所有微调器单元格的样式
ItemTemplate	DataTemplate	微调器单元格内容的模板
ItemTemplateSelector	DataTemplateSelector	用于微调器单元格的条件模板

事件

事件	说明
SelectedTimeChanged	SelectedTime 更改后触发，并提供旧值和新值
SelectedTimeChanging	SelectedTime 更新前触发，可取消更新
TimeFieldPrepared	下拉微调器列准备就绪时触发，可进行自定义

常见用例

预约安排

使用 TimePicker 预订预约，并限制营业时间、屏蔽午餐时段以及设置 15–30 分钟的间隔。

时间录入表单

在表单中实现时间输入，并支持验证、可空时间值，以及根据用户区域设置自定义格式。

班次管理

创建班次时间选择器并限制时间范围（例如，早班：6AM–2PM，中班：2PM–10PM，夜班：10PM–6AM）。

会议安排

构建会议时间选择器，为已有会议设置禁用时段，并自定义时间间隔（30 分钟或 1 小时）。

计时器应用

使用 TimePicker 设置闹钟时间、倒计时或提醒计划，并采用 24 小时制。

本地化应用

实现时间选择，并为阿拉伯语/希伯来语提供从右到左的布局和区域设置专用格式。

自定义时间间隔

为需要特定间隔的行业创建专用时间选择器（例如，交通时刻表、医疗预约）。