syncfusion-wpf-timepicker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing WPF TimePicker (SfTimePicker)

实现WPF TimePicker（SfTimePicker）

The SfTimePicker is a WPF control that enables touch-friendly time value selection with customizable formatting, time selector UI, and comprehensive styling options. This skill guides you through implementing, configuring, and customizing time picker controls for WPF applications.

SfTimePicker是一款WPF控件，支持触控友好的时间值选择，具备可自定义的格式、时间选择器UI以及全面的样式设置选项。本技能将指导你在WPF应用中实现、配置和自定义时间选择器控件。

When to Use This Skill

何时使用本技能

Adding a time picker control to a WPF application for user time input
Setting and managing time values programmatically or through binding
Formatting time display in different formats (12-hour, 24-hour, culture-specific)
Customizing the time selector with templates, sizing, and spacing
Styling and theming the time picker (colors, backgrounds, RTL support)
Handling time value changes with events and callbacks
Controlling editing modes (free editing vs. dropdown selection)

为WPF应用添加时间选择器控件以实现用户时间输入
通过编程或绑定方式设置和管理时间值
以不同格式（12小时制、24小时制、特定区域格式）格式化时间显示
使用模板、尺寸和间距自定义时间选择器
设置时间选择器的外观和主题（颜色、背景、RTL支持）
通过事件和回调处理时间值变更
控制编辑模式（自由编辑 vs 下拉选择）

Navigation Guide

导航指南

Choose your task below to jump to the relevant documentation:

选择下方任务跳转到对应文档：

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and assembly references
Adding control via designer, XAML, and C#
Basic time picker setup
Handling the ValueChanged event
Applying themes

📄 阅读： references/getting-started.md

安装和程序集引用
通过设计器、XAML和C#添加控件
基础时间选择器设置
处理ValueChanged事件
应用主题

Setting Time Values

设置时间值

📄 Read: references/setting-time-values.md

Setting time using the Value property
Allowing and setting null values
Watermark text for prompts
UpdateValueOnLostFocus behavior
Event-based time detection

📄 阅读： references/setting-time-values.md

使用Value属性设置时间
允许并设置空值
提示用水印文本
UpdateValueOnLostFocus行为
基于事件的时间检测

Time Formatting

时间格式化

📄 Read: references/time-formatting.md

FormatString for display formatting
SelectorFormatString for time picker format
Common format patterns
Culture-specific formatting

📄 阅读： references/time-formatting.md

用于显示格式化的FormatString
用于时间选择器格式的SelectorFormatString
常见格式模式
特定区域格式化

Customizing the Time Selector

自定义时间选择器

📄 Read: references/time-selector-customization.md

Overview of SfTimeSelector control
Hour, minute, and meridiem cell templates
Cell sizing and spacing properties
Advanced template customization

📄 阅读： references/time-selector-customization.md

SfTimeSelector控件概述
时、分和上/下午单元格模板
单元格尺寸和间距属性
高级模板自定义

Appearance & Styling

外观与样式

📄 Read: references/appearance-and-styling.md

Foreground and background colors
Selected item styling
Flow direction (right-to-left support)
Editing modes (inline vs. dropdown)
Theme integration

📄 阅读： references/appearance-and-styling.md

前景色和背景色
选中项样式
流向（从右到左支持）
编辑模式（内联 vs 下拉）
主题集成

Quick Start

快速开始

xaml

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <!-- Basic time picker -->
        <syncfusion:SfTimePicker x:Name="timePicker" 
                                 Width="200" 
                                 Value="04:30:00"
                                 ValueChanged="TimePicker_ValueChanged"/>
    </Grid>
</Window>

csharp

using Syncfusion.Windows.Controls.Input;

SfTimePicker timePicker = new SfTimePicker();
timePicker.Value = new TimeSpan(14, 30, 00); // 2:30 PM
timePicker.ValueChanged += (d, e) => 
    Console.WriteLine($"Time changed to: {e.NewValue}");

xaml

<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Grid>
        <!-- Basic time picker -->
        <syncfusion:SfTimePicker x:Name="timePicker" 
                                 Width="200" 
                                 Value="04:30:00"
                                 ValueChanged="TimePicker_ValueChanged"/>
    </Grid>
</Window>

csharp

using Syncfusion.Windows.Controls.Input;

SfTimePicker timePicker = new SfTimePicker();
timePicker.Value = new TimeSpan(14, 30, 00); // 2:30 PM
timePicker.ValueChanged += (d, e) => 
    Console.WriteLine($"Time changed to: {e.NewValue}");

Common Patterns

常见模式

Pattern 1: 24-Hour Time Display

模式1：24小时制时间显示

xaml

<syncfusion:SfTimePicker FormatString="HH:mm:ss" 
                         SelectorFormatString="HH:mm"/>

xaml

<syncfusion:SfTimePicker FormatString="HH:mm:ss" 
                         SelectorFormatString="HH:mm"/>

Pattern 2: Allow Null Values with Watermark

模式2：允许空值并添加水印

xaml

<syncfusion:SfTimePicker AllowNull="True"
                         Value="{x:Null}"
                         Watermark="Select a time"/>

xaml

<syncfusion:SfTimePicker AllowNull="True"
                         Value="{x:Null}"
                         Watermark="Select a time"/>

Pattern 3: Read-Only Time Display

模式3：只读时间显示

xaml

<syncfusion:SfTimePicker AllowInlineEditing="False"
                         ShowDropDownButton="False"
                         Value="09:00:00"/>

xaml

<syncfusion:SfTimePicker AllowInlineEditing="False"
                         ShowDropDownButton="False"
                         Value="09:00:00"/>

Pattern 4: Custom Cell Size and Spacing

模式4：自定义单元格尺寸和间距

xaml

<syncfusion:SfTimePicker SelectorItemWidth="60"
                         SelectorItemHeight="60"
                         SelectorItemSpacing="20"/>

xaml

<syncfusion:SfTimePicker SelectorItemWidth="60"
                         SelectorItemHeight="60"
                         SelectorItemSpacing="20"/>

Key Properties Quick Reference

关键属性速查

Property	Default	Purpose
`Value`	Current system time	Get/set the selected time as TimeSpan
`FormatString`	"h:mm tt"	Display format (12-hr/24-hr)
`SelectorFormatString`	"h:mm tt"	Format for time picker cells
`AllowNull`	false	Enable null value support
`Watermark`	—	Placeholder text when Value is null
`AllowInlineEditing`	true	Allow direct text editing
`ShowDropDownButton`	true	Show dropdown button
`SetValueOnLostFocus`	false	Update value when focus lost
`SelectorItemWidth`	30	Width of selector cells (pixels)
`SelectorItemHeight`	30	Height of selector cells (pixels)
`SelectorItemSpacing`	4	Space between selector items (pixels)
`Foreground`	—	Text color
`Background`	—	Control background color
`AccentBrush`	—	Selected item highlight color
`FlowDirection`	LeftToRight	Support RTL layouts

属性	默认值	用途
`Value`	当前系统时间	以TimeSpan类型获取/设置选中的时间
`FormatString`	"h:mm tt"	显示格式（12小时制/24小时制）
`SelectorFormatString`	"h:mm tt"	时间选择器单元格的格式
`AllowNull`	false	启用空值支持
`Watermark`	—	当Value为空时的占位文本
`AllowInlineEditing`	true	允许直接文本编辑
`ShowDropDownButton`	true	显示下拉按钮
`SetValueOnLostFocus`	false	失去焦点时更新值
`SelectorItemWidth`	30	选择器单元格宽度（像素）
`SelectorItemHeight`	30	选择器单元格高度（像素）
`SelectorItemSpacing`	4	选择器项之间的间距（像素）
`Foreground`	—	文本颜色
`Background`	—	控件背景色
`AccentBrush`	—	选中项高亮颜色
`FlowDirection`	LeftToRight	支持RTL布局