syncfusion-winui-time-picker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WinUI TimePicker (SfTimePicker) Implementation Guide

WinUI TimePicker (SfTimePicker) 实现指南

Comprehensive guide for implementing the Syncfusion WinUI TimePicker control in Windows desktop applications. The SfTimePicker provides an intuitive, touch-friendly interface to select time from a dropdown spinner with support for time restrictions, formatting, localization, and extensive customization.

本指南全面介绍如何在Windows桌面应用中实现Syncfusion WinUI TimePicker控件。SfTimePicker提供了直观、适配触控操作的界面，用户可通过下拉选择器选择时间，支持时间限制、格式化、本地化及大量自定义配置。

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Implement time selection in WinUI 3 desktop applications
Add time input controls with dropdown spinner
Create appointment scheduling or time entry forms
Restrict time selection to specific ranges or intervals
Implement 12-hour or 24-hour time formats
Customize dropdown time spinner appearance
Support localized time input with RTL layouts
Validate and format time input in Windows apps
Hide or disable specific times from selection

当你需要完成以下需求时可使用本技能：

在WinUI 3桌面应用中实现时间选择功能
新增带下拉选择器的时间输入控件
构建预约排班或时间录入表单
将可选时间限制在特定范围或时间间隔内
实现12小时制或24小时制的时间格式
自定义下拉时间选择器的外观
支持带RTL布局的本地化时间输入
在Windows应用中校验并格式化时间输入
隐藏或禁用部分可选时间

Component Overview

组件概览

The SfTimePicker control provides a modern time selection experience for WinUI applications with:

Key Features:

Dropdown Time Spinner - Select time from hour, minute, and meridiem (AM/PM) columns
Time Restrictions - Set minimum/maximum times and blackout specific times
Multiple Formats - Support for 12-hour and 24-hour clock formats
Localization - Multi-language support with RTL layout
Edit Modes - Mask editing with auto-correction or free-form input
Extensive Customization - Customize dropdown button, header, spinner cells, and templates
Validation - Built-in validation with change events for custom logic
Accessibility - Full keyboard navigation and WCAG compliance

Control Structure:

Text editor for direct time input
Dropdown button to open time spinner
Dropdown spinner with hour, minute, and meridiem columns
Optional dropdown header for hints
Submit/Cancel buttons (optional)

NuGet Package:

Syncfusion.Editors.WinUI

Namespace:

Syncfusion.UI.Xaml.Editors

SfTimePicker控件为WinUI应用提供了现代化的时间选择体验，具备以下特性：

核心特性：

下拉时间选择器 - 可从时、分、meridiem（上午/下午）列中选择时间
时间限制 - 可设置最小/最大可选时间，以及禁用特定时间
多格式支持 - 支持12小时制和24小时制时钟格式
本地化 - 多语言支持，兼容RTL布局
编辑模式 - 带自动校正的掩码编辑或自由格式输入
高度可自定义 - 可自定义下拉按钮、头部、选择器单元格及模板
校验功能 - 内置校验，支持通过变更事件实现自定义逻辑
可访问性 - 支持全键盘导航，符合WCAG标准

控件结构：

支持直接输入时间的文本编辑器
用于打开时间选择器的下拉按钮
包含时、分、上午/下午列的下拉选择器
可选的下拉头部提示信息
提交/取消按钮（可选）

NuGet包：

Syncfusion.Editors.WinUI

命名空间：

Syncfusion.UI.Xaml.Editors

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Use this reference for initial setup and basic implementation:

Installing the Syncfusion.Editors.WinUI NuGet package
Adding SfTimePicker to XAML and C# code
Understanding component structure (editor, dropdown, spinner)
Setting selected time programmatically with
```
SelectedTime
```
property
Interactive time selection from dropdown
Allowing null values with
```
AllowNull
```
property
Adding header and description text
Customizing header with
```
HeaderTemplate
```
Setting watermark text with
```
PlaceholderText
```
Handling time changed events with
```
SelectedTimeChanged
```

📄 阅读： references/getting-started.md

该参考文档用于初始配置与基础实现：

安装Syncfusion.Editors.WinUI NuGet包
在XAML和C#代码中添加SfTimePicker
理解组件结构（编辑器、下拉框、选择器）
通过
```
SelectedTime
```
属性以编程方式设置选中时间
通过下拉框进行交互式时间选择
通过
```
AllowNull
```
属性支持空值
添加头部和描述文本
通过
```
HeaderTemplate
```
自定义头部
通过
```
PlaceholderText
```
设置水印文本
通过
```
SelectedTimeChanged
```
处理时间变更事件

Time Restrictions

时间限制

📄 Read: references/time-restrictions.md

Use this reference for controlling time selection:

Limiting available times with
```
MinTime
```
and
```
MaxTime
```
properties
Blocking specific times using
```
BlackoutTimes
```
collection
Creating custom time intervals (e.g., 5-minute, 15-minute increments)
Using
```
TimeFieldPrepared
```
event to customize time intervals
Hiding submit buttons with
```
ShowSubmitButtons
```
property
Selecting time directly as you scroll the spinner
Canceling time changes with
```
SelectedTimeChanging
```
event
Implementing custom validation logic
Handling edge cases and validation errors

📄 阅读： references/time-restrictions.md

该参考文档用于控制时间选择范围：

通过
```
MinTime
```
和
```
MaxTime
```
属性限制可选时间范围
通过
```
BlackoutTimes
```
集合禁用特定时间
自定义时间间隔（例如5分钟、15分钟增量）
使用
```
TimeFieldPrepared
```
事件自定义时间间隔
通过
```
ShowSubmitButtons
```
属性隐藏提交按钮
滚动选择器时直接选中时间
通过
```
SelectedTimeChanging
```
事件取消时间变更
实现自定义校验逻辑
处理边界情况与校验错误

Localization and Formatting

本地化与格式化

📄 Read: references/localization-formatting.md

Use this reference for formatting and localizing time display:

Switching between 12-hour and 24-hour formats with
```
ClockIdentifier
```
Changing flow direction for RTL languages with
```
FlowDirection
```
Localizing the control with
```
Language
```
property
Customizing time display format with
```
DisplayTimeFormat
```
Understanding format patterns (hh:mm tt, HH:mm, h:mm, etc.)
Using mask edit mode for auto-correcting input
Using normal edit mode for free-form input validation
Input behavior and automatic field correction
Showing/hiding the clear button with
```
ShowClearButton
```

📄 阅读： references/localization-formatting.md

该参考文档用于格式化与本地化时间展示：

通过
```
ClockIdentifier
```
切换12小时制和24小时制
通过
```
FlowDirection
```
为RTL语言修改布局方向
通过
```
Language
```
属性实现控件本地化
通过
```
DisplayTimeFormat
```
自定义时间展示格式
理解格式模式（hh:mm tt、HH:mm、h:mm等）
使用掩码编辑模式实现输入自动校正
使用普通编辑模式实现自由格式输入校验
输入行为与自动字段校正
通过
```
ShowClearButton
```
显示/隐藏清除按钮

Dropdown Customization

下拉框自定义

📄 Read: references/dropdown-customization.md

Use this reference for customizing the dropdown container:

Customizing dropdown button UI with
```
DropDownButtonTemplate
```
Hiding dropdown button with
```
ShowDropDownButton
```
property
Changing dropdown alignment with
```
DropDownPlacement
```
Opening/closing dropdown programmatically with
```
IsOpen
```
property
Setting dropdown height with
```
DropDownHeight
```
property
Controlling visible items with
```
VisibleItemsCount
```
property
Understanding dropdown smart positioning
Keyboard shortcuts for opening dropdown (Alt+Down)

📄 阅读： references/dropdown-customization.md

该参考文档用于自定义下拉容器：

通过
```
DropDownButtonTemplate
```
自定义下拉按钮UI
通过
```
ShowDropDownButton
```
属性隐藏下拉按钮
通过
```
DropDownPlacement
```
修改下拉框对齐方式
通过
```
IsOpen
```
属性以编程方式打开/关闭下拉框
通过
```
DropDownHeight
```
属性设置下拉框高度
通过
```
VisibleItemsCount
```
属性控制可见项数量
理解下拉框智能定位
打开下拉框的快捷键（Alt+向下箭头）

Dropdown Header Customization

下拉框头部自定义

📄 Read: references/dropdown-header-customization.md

Use this reference for customizing the dropdown header:

Adding hints in dropdown header with
```
DropDownHeader
```
property
Showing/hiding header with
```
ShowDropDownHeader
```
property
Customizing header appearance with
```
DropDownHeaderTemplate
```
Creating custom header layouts with icons and text
Hiding column headers with
```
ShowColumnHeaders
```
property
Understanding column header customization
Header styling best practices

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

该参考文档用于自定义下拉框头部：

通过
```
DropDownHeader
```
属性在下拉框头部添加提示信息
通过
```
ShowDropDownHeader
```
属性显示/隐藏头部
通过
```
DropDownHeaderTemplate
```
自定义头部外观
创建带图标和文本的自定义头部布局
通过
```
ShowColumnHeaders
```
属性隐藏列头部
理解列头部自定义
头部样式最佳实践

Dropdown Spinner Customization

下拉选择器自定义

📄 Read: references/dropdown-spinner-customization.md

Use this reference for customizing dropdown spinner cells and columns:

Changing cell size with
```
ItemWidth
```
and
```
ItemHeight
```
properties
Restricting cell width with
```
MinItemWidth
```
and
```
MaxItemWidth
```
Styling all cells with
```
ItemContainerStyle
```
property
Customizing cell templates with
```
ItemTemplate
```
Conditional cell styling with
```
ItemTemplateSelector
```
Customizing individual columns with
```
TimeFieldPrepared
```
event
Changing column headers, intervals, and cell sizes per column
Adding icons or custom content to specific time cells
Performance optimization for large customizations

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

该参考文档用于自定义下拉选择器单元格与列：

通过
```
ItemWidth
```
和
```
ItemHeight
```
属性修改单元格尺寸
通过
```
MinItemWidth
```
和
```
MaxItemWidth
```
限制单元格宽度
通过
```
ItemContainerStyle
```
属性为所有单元格设置样式
通过
```
ItemTemplate
```
自定义单元格模板
通过
```
ItemTemplateSelector
```
实现单元格条件样式
通过
```
TimeFieldPrepared
```
事件自定义单列
单独修改每列的头部、间隔和单元格尺寸
为特定时间单元格添加图标或自定义内容
大量自定义时的性能优化

Quick Start Example

快速入门示例

Basic TimePicker Implementation

基础TimePicker实现

XAML:

xml

<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#:

csharp

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
};

XAML：

xml

<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#：

csharp

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
};

Common Patterns

常用实现模式

Time Selection with Restrictions

带限制的时间选择

Restrict time selection to business hours (9 AM - 5 PM):

csharp

// 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));

将可选时间限制为工作时间（上午9点 - 下午5点）：

csharp

// 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-Hour Format

24小时制格式

Switch to 24-hour clock format:

xml

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

切换为24小时制时钟格式：

xml

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

Custom Time Intervals

自定义时间间隔

Allow only 15-minute intervals:

csharp

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;
    }
};

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

csharp

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;
    }
};

Blocking Lunch Hour

禁用午休时间

Prevent selection during lunch break (12 PM - 1 PM):

csharp

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;

禁止选择午休时段（中午12点 - 下午1点）：

csharp

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;

Key Properties

核心属性

Core Properties

基础属性

Property	Type	Description
`SelectedTime`	DateTimeOffset?	Gets or sets the selected time value
`MinTime`	DateTimeOffset	Minimum selectable time (default: 1/1/1921 10:37:16 PM)
`MaxTime`	DateTimeOffset	Maximum selectable time (default: 12/31/2121 10:37:16 PM)
`BlackoutTimes`	DateTimeOffsetCollection	Collection of times to disable from selection
`AllowNull`	bool	Allows null value for SelectedTime (default: false)
`PlaceholderText`	string	Watermark text shown when SelectedTime is null

属性	类型	描述
`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为空值（默认值：false）
`PlaceholderText`	string	SelectedTime为空时展示的水印文本

Formatting Properties

格式化属性

Property	Type	Description
`ClockIdentifier`	string	Clock format: "12HourClock" or "24HourClock"
`DisplayTimeFormat`	string	Format pattern for displaying time (e.g., "hh:mm tt", "HH:mm")
`EditMode`	DateTimeEditMode	Edit mode: Mask (auto-correct) or Normal (validate on Enter)
`ShowClearButton`	bool	Shows/hides the clear button (default: true)

属性	类型	描述
`ClockIdentifier`	string	时钟格式："12HourClock"（12小时制）或"24HourClock"（24小时制）
`DisplayTimeFormat`	string	时间展示的格式模式（例如"hh:mm tt"、"HH:mm"）
`EditMode`	DateTimeEditMode	编辑模式：Mask（自动校正）或Normal（按回车时校验）
`ShowClearButton`	bool	是否显示清除按钮（默认值：true）

Dropdown Properties

下拉框属性

Property	Type	Description
`ShowDropDownButton`	bool	Shows/hides dropdown button (default: true)
`DropDownButtonTemplate`	DataTemplate	Template for customizing dropdown button
`DropDownPlacement`	FlyoutPlacementMode	Dropdown alignment (Auto, Bottom, Top, etc.)
`IsOpen`	bool	Opens/closes dropdown programmatically
`DropDownHeight`	double	Fixed height for dropdown spinner
`VisibleItemsCount`	int	Number of visible items in dropdown (default: -1)

属性	类型	描述
`ShowDropDownButton`	bool	是否显示下拉按钮（默认值：true）
`DropDownButtonTemplate`	DataTemplate	自定义下拉按钮的模板
`DropDownPlacement`	FlyoutPlacementMode	下拉框对齐方式（Auto、Bottom、Top等）
`IsOpen`	bool	以编程方式打开/关闭下拉框
`DropDownHeight`	double	下拉选择器的固定高度
`VisibleItemsCount`	int	下拉框中可见项的数量（默认值：-1）

Dropdown Header Properties

下拉框头部属性

Property	Type	Description
`ShowDropDownHeader`	bool	Shows/hides dropdown header (default: false)
`DropDownHeader`	object	Content for dropdown header
`DropDownHeaderTemplate`	DataTemplate	Template for dropdown header customization
`ShowColumnHeaders`	bool	Shows/hides column headers in spinner (default: true)

属性	类型	描述
`ShowDropDownHeader`	bool	是否显示下拉框头部（默认值：false）
`DropDownHeader`	object	下拉框头部的内容
`DropDownHeaderTemplate`	DataTemplate	自定义下拉框头部的模板
`ShowColumnHeaders`	bool	是否显示选择器中的列头部（默认值：true）

Spinner Customization Properties

选择器自定义属性

Property	Type	Description
`ItemWidth`	double	Width of spinner cells (default: 80)
`ItemHeight`	double	Height of spinner cells (default: 40)
`MinItemWidth`	double	Minimum width for spinner cells (default: 0)
`MaxItemWidth`	double	Maximum width for spinner cells (default: Infinity)
`ItemContainerStyle`	Style	Style applied to all spinner cells
`ItemTemplate`	DataTemplate	Template for spinner cell content
`ItemTemplateSelector`	DataTemplateSelector	Conditional templates for spinner cells

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

Events

事件

Event	Description
`SelectedTimeChanged`	Fires after SelectedTime changes, provides old and new values
`SelectedTimeChanging`	Fires before SelectedTime updates, allows cancellation
`TimeFieldPrepared`	Fires when dropdown spinner columns are prepared, allows customization

事件	描述
`SelectedTimeChanged`	SelectedTime变更后触发，返回旧值和新值
`SelectedTimeChanging`	SelectedTime更新前触发，支持取消操作
`TimeFieldPrepared`	下拉选择器列准备完成后触发，支持自定义

Common Use Cases

常见使用场景

Appointment Scheduling

预约排班

Use TimePicker for booking appointments with restricted business hours, blocked lunch times, and 15-30 minute intervals.

使用TimePicker实现预约预订功能，支持限制工作时间、禁用午休时间、设置15-30分钟的可选时间间隔。

Time Entry Forms

时间录入表单

Implement time input in forms with validation, nullable times, and custom formats based on user locale.

在表单中实现时间输入功能，支持校验、空值时间、基于用户地区的自定义格式。

Shift Management

班次管理

Create shift time selectors with restricted ranges (e.g., morning: 6AM-2PM, evening: 2PM-10PM, night: 10PM-6AM).

创建班次时间选择器，支持限制可选范围（例如早班：6点-14点，晚班：14点-22点，夜班：22点-6点）。

Meeting Scheduler

会议日程

Build meeting time pickers with blackout times for existing meetings and custom intervals (30 min or 1 hour slots).

构建会议时间选择器，支持禁用已占用会议时间、自定义间隔（30分钟或1小时时段）。

Timer Applications

计时器应用

Use TimePicker for setting alarm times, countdown timers, or reminder schedules with 24-hour format.

使用TimePicker设置闹钟时间、倒计时、提醒日程，支持24小时制格式。

Localized Applications

本地化应用

Implement time selection with right-to-left layout for Arabic/Hebrew languages and locale-specific formats.

实现支持阿拉伯语/希伯来语等从右到左布局、适配地区格式的时间选择功能。

Custom Time Intervals

自定义时间间隔

Create specialized time pickers for industries requiring specific intervals (e.g., transportation schedules, medical appointments).

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