syncfusion-wpf-datetimepicker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing DateTimeEdit (WPF)

实现DateTimeEdit（WPF）

An enhanced date-time input control with mask editing, calendar/clock dropdown, date range restriction, formatting, and MVVM binding support.

一款增强型日期时间输入控件，支持掩码编辑、日历/时钟下拉、日期范围限制、格式化以及MVVM绑定。

When to Use This Skill

何时使用本技能

Use this skill when the user needs to:

Add a date/time picker input field to a WPF application
Bind a selected date to a ViewModel property (
```
DateTime
```
two-way binding)
Format the displayed date/time (predefined patterns or custom patterns)
Restrict selectable dates with min/max range or blackout dates
Enable inline editing (mask mode or free-form text editing)
Show a calendar, clock, or combined dropdown picker
Display watermark text when no date is selected
Handle null date values
Apply locale-specific date formats via
```
CultureInfo
```
Localize dropdown button labels (Today/None)

当用户需要以下功能时使用本技能：

为WPF应用添加日期/时间选择器输入字段
将选中的日期绑定到ViewModel属性（DateTime双向绑定）
格式化显示的日期/时间（预定义模式或自定义模式）
通过最小/最大范围或禁用日期限制可选日期
启用内联编辑（掩码模式或自由文本编辑）
显示日历、时钟或组合式下拉选择器
未选择日期时显示水印文本
处理空日期值
通过
```
CultureInfo
```
应用特定地区的日期格式
本地化下拉按钮标签（今日/无）

Component Overview

组件概述

Class	Namespace	Assembly
`DateTimeEdit`	`Syncfusion.Windows.Shared`	`Syncfusion.Shared.WPF`

XAML Namespace:

xml

xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

NuGet:

Install-Package Syncfusion.Shared.WPF

类	命名空间	程序集
`DateTimeEdit`	`Syncfusion.Windows.Shared`	`Syncfusion.Shared.WPF`

XAML命名空间：

xml

xmlns:syncfusion="http://schemas.syncfusion.com/wpf"

NuGet：

Install-Package Syncfusion.Shared.WPF

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly setup and XAML namespace
Add via designer, XAML, or C#
Setting
```
DateTime
```
value
Two-way MVVM binding with
```
DateTimeChanged
```
event
Predefined
```
Pattern
```
quick reference
```
MinDateTime
```
/
```
MaxDateTime
```
basics
SfSkinManager theme setup

📄 阅读： references/getting-started.md

程序集设置与XAML命名空间
通过设计器、XAML或C#添加控件
设置
```
DateTime
```
值
带
```
DateTimeChanged
```
事件的双向MVVM绑定
预定义
```
Pattern
```
快速参考
```
MinDateTime
```
/
```
MaxDateTime
```
基础用法
SfSkinManager主题设置

DateTime Editing

DateTime编辑

📄 Read: references/datetime-editing.md

Mask editing (default) — field-by-field input with auto-validation
Keyboard navigation between date/time fields
Free-form text editing (
```
CanEdit="True"
```
)
Mouse wheel value change (
```
EnableMouseWheelEdit
```
)

Up/down repeat buttons (

IsVisibleRepeatButton

IsEnabledRepeatButton

)

Custom repeat button UI templates
Alpha key month navigation (
```
EnableAlphaKeyNavigation
```
)
BackSpace/Delete key editing
```
OnFocusBehavior
```
and
```
AutoForwarding
```
focus control

📄 阅读： references/datetime-editing.md

掩码编辑（默认）——逐字段输入并自动验证
日期/时间字段间的键盘导航
自由格式文本编辑（
```
CanEdit="True"
```
）
鼠标滚轮更改值（
```
EnableMouseWheelEdit
```
）

上下重复按钮（

IsVisibleRepeatButton

IsEnabledRepeatButton

）

自定义重复按钮UI模板
字母键月份导航（
```
EnableAlphaKeyNavigation
```
）
退格/删除键编辑
```
OnFocusBehavior
```
与
```
AutoForwarding
```
焦点控制

Formatting & Culture

格式化与地区设置

📄 Read: references/formatting-and-culture.md

All 11 predefined
```
Pattern
```
values
```
CustomPattern
```
with
```
Pattern="CustomPattern"
```
```
DateTimeFormat
```
with
```
DateTimeFormatInfo
```
```
CultureInfo
```
for locale-specific formatting
```
PatternChanged
```
/
```
CustomPatternChanged
```
events

📄 阅读： references/formatting-and-culture.md

全部11种预定义
```
Pattern
```
值
结合
```
Pattern="CustomPattern"
```
使用
```
CustomPattern
```
结合
```
DateTimeFormatInfo
```
使用
```
DateTimeFormat
```
用于特定地区格式化的
```
CultureInfo
```
```
PatternChanged
```
/
```
CustomPatternChanged
```
事件

Dropdown Popup

下拉弹出框

📄 Read: references/dropdown-popup.md

```
DropDownView
```
: Calendar / Clock / Combined
Keyboard shortcuts (Alt+Down, F4)
```
TodayButtonAction
```
(Date vs DateTime)
```
IsEmptyDateEnabled
```
— None button / reset to null
```
AbbreviatedMonthNames
```
/
```
ShortestDayNames
```
```
PopupDelay
```
,
```
IsButtonPopUpEnabled
```
```
DropDownButtonTemplate
```
custom UI
Custom calendar and clock (SfDateSelector / SfTimeSelector)
```
TimeStepInterval
```
for clock

📄 阅读： references/dropdown-popup.md

```
DropDownView
```
：日历 / 时钟 / 组合视图
键盘快捷键（Alt+Down, F4）
```
TodayButtonAction
```
（日期 vs 日期时间）
```
IsEmptyDateEnabled
```
——无按钮 / 重置为空
```
AbbreviatedMonthNames
```
/
```
ShortestDayNames
```
```
PopupDelay
```
,
```
IsButtonPopUpEnabled
```
```
DropDownButtonTemplate
```
自定义UI
自定义日历和时钟（SfDateSelector / SfTimeSelector）
时钟的
```
TimeStepInterval
```

Date Restrictions & Null Values

日期限制与空值

📄 Read: references/date-restrictions.md

```
MinDateTime
```
/
```
MaxDateTime
```
— prevent out-of-range selection
```
BlackoutDates
```
— block specific date ranges
```
DisableDateSelection
```
— month/year only
```
IsReadOnly
```
— prevent all user edits

NullValue

IsEmptyDateEnabled

ShowMaskOnNullValue

```
NoneDateText
```
watermark

📄 阅读： references/date-restrictions.md

```
MinDateTime
```
/
```
MaxDateTime
```
——防止选择超出范围的日期
```
BlackoutDates
```
——阻止特定日期范围
```
DisableDateSelection
```
——仅选择月份/年份
```
IsReadOnly
```
——禁止所有用户编辑

NullValue

IsEmptyDateEnabled

ShowMaskOnNullValue

```
NoneDateText
```
水印

Appearance

外观

📄 Read: references/appearance.md

```
Foreground
```
,
```
Background
```
,
```
SelectionBrush
```
```
FocusedBorderBrush
```
```
FlowDirection
```
RTL
Repeat button background and margins
SfSkinManager themes list

📄 阅读： references/appearance.md

```
Foreground
```
,
```
Background
```
,
```
SelectionBrush
```
```
FocusedBorderBrush
```
```
FlowDirection
```
RTL（从右到左）
重复按钮背景与边距
SfSkinManager主题列表

Localization

本地化

📄 Read: references/localization.md

```
CurrentUICulture
```
setup
Resource file naming:
```
Syncfusion.Shared.Wpf.{culture}.resx
```
Name/Value pairs for Today/None button labels
French culture example

📄 阅读： references/localization.md

```
CurrentUICulture
```
设置
资源文件命名：
```
Syncfusion.Shared.Wpf.{culture}.resx
```
今日/无按钮标签的键值对
法语地区示例

Quick Start Example

快速入门示例

xml

<!-- MainWindow.xaml -->
<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Window.DataContext>
        <local:ViewModel/>
    </Window.DataContext>
    <StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
        <syncfusion:DateTimeEdit DateTime="{Binding SelectedDate, Mode=TwoWay}"
                                 Pattern="ShortDate"
                                 MinDateTime="01/01/2020"
                                 MaxDateTime="12/31/2030"
                                 Height="25" Width="200"
                                 Name="dateTimeEdit"/>
    </StackPanel>
</Window>

csharp

// ViewModel.cs
public class ViewModel : NotificationObject
{
    private DateTime _selectedDate = DateTime.Now;
    public DateTime SelectedDate
    {
        get => _selectedDate;
        set { _selectedDate = value; RaisePropertyChanged(nameof(SelectedDate)); }
    }
}

xml

<!-- MainWindow.xaml -->
<Window xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    <Window.DataContext>
        <local:ViewModel/>
    </Window.DataContext>
    <StackPanel HorizontalAlignment="Center" VerticalAlignment="Center">
        <syncfusion:DateTimeEdit DateTime="{Binding SelectedDate, Mode=TwoWay}"
                                 Pattern="ShortDate"
                                 MinDateTime="01/01/2020"
                                 MaxDateTime="12/31/2030"
                                 Height="25" Width="200"
                                 Name="dateTimeEdit"/>
    </StackPanel>
</Window>

csharp

// ViewModel.cs
public class ViewModel : NotificationObject
{
    private DateTime _selectedDate = DateTime.Now;
    public DateTime SelectedDate
    {
        get => _selectedDate;
        set { _selectedDate = value; RaisePropertyChanged(nameof(SelectedDate)); }
    }
}

Common Patterns

常见场景

Scenario	Properties / Approach
Two-way date binding	`DateTime="{Binding SelectedDate, Mode=TwoWay}"`
Show calendar + clock	`DropDownView="Combined" Pattern="FullDateTime"`
Free-form text editing	`CanEdit="True"`
Date-only range restriction	`MinDateTime="..." MaxDateTime="..."`
Allow null / clear value	`IsEmptyDateEnabled="True" NullValue="{x:Null}" ShowMaskOnNullValue="False"`
Watermark when null	Add `NoneDateText="Select a date"` alongside null value properties
Custom date display	`Pattern="CustomPattern" CustomPattern="dd-MMM-yyyy"`
Culture-aware formatting	`CultureInfo="fr-FR" Pattern="FullDateTime"`
Read-only input	`IsReadOnly="True"`
RTL layout	`FlowDirection="RightToLeft"`
Apply theme	`SfSkinManager.SetVisualStyle(dte, VisualStyles.FluentLight)`

场景	属性 / 实现方式
双向日期绑定	`DateTime="{Binding SelectedDate, Mode=TwoWay}"`
显示日历+时钟	`DropDownView="Combined" Pattern="FullDateTime"`
自由格式文本编辑	`CanEdit="True"`
仅日期范围限制	`MinDateTime="..." MaxDateTime="..."`
允许空值/清除值	`IsEmptyDateEnabled="True" NullValue="{x:Null}" ShowMaskOnNullValue="False"`
空值时显示水印	结合空值属性添加 `NoneDateText="选择日期"`
自定义日期显示	`Pattern="CustomPattern" CustomPattern="dd-MMM-yyyy"`
地区感知格式化	`CultureInfo="fr-FR" Pattern="FullDateTime"`
只读输入	`IsReadOnly="True"`
RTL布局	`FlowDirection="RightToLeft"`
应用主题	`SfSkinManager.SetVisualStyle(dte, VisualStyles.FluentLight)`

Key Properties

关键属性

Property	Type	Default	Description
`DateTime`	`DateTime`	`DateTime.Now`	Selected date/time value
`Pattern`	`DateTimePattern`	`ShortDate`	Display format pattern
`CustomPattern`	`string`	`null`	Custom format string (requires `Pattern="CustomPattern"` )
`CultureInfo`	`CultureInfo`	System culture	Locale for date formatting
`CanEdit`	`bool`	`false`	Enable free-form text editing
`MinDateTime`	`DateTime`	`DateTime.MinValue`	Minimum selectable date
`MaxDateTime`	`DateTime`	`DateTime.MaxValue`	Maximum selectable date
`DropDownView`	`DropDownViews`	`Calendar`	Popup content: Calendar/Clock/Combined
`IsEmptyDateEnabled`	`bool`	`false`	Allow null date value
`NullValue`	`DateTime?`	`null`	Value when date is cleared
`NoneDateText`	`string`	`""`	Watermark text when value is null
`ShowMaskOnNullValue`	`bool`	`true`	Show mask vs watermark when null
`IsReadOnly`	`bool`	`false`	Prevent user edits
`IsVisibleRepeatButton`	`bool`	`false`	Show up/down spinner buttons
`EnableMouseWheelEdit`	`bool`	`true`	Allow mouse wheel to change value

属性	类型	默认值	描述
`DateTime`	`DateTime`	`DateTime.Now`	选中的日期/时间值
`Pattern`	`DateTimePattern`	`ShortDate`	显示格式模式
`CustomPattern`	`string`	`null`	自定义格式字符串（需设置 `Pattern="CustomPattern"` ）
`CultureInfo`	`CultureInfo`	系统地区	日期格式化的地区设置
`CanEdit`	`bool`	`false`	启用自由格式文本编辑
`MinDateTime`	`DateTime`	`DateTime.MinValue`	最小可选日期
`MaxDateTime`	`DateTime`	`DateTime.MaxValue`	最大可选日期
`DropDownView`	`DropDownViews`	`Calendar`	弹出内容：日历/时钟/组合视图
`IsEmptyDateEnabled`	`bool`	`false`	允许空日期值
`NullValue`	`DateTime?`	`null`	日期清除后的值
`NoneDateText`	`string`	`""`	值为空时的水印文本
`ShowMaskOnNullValue`	`bool`	`true`	为空时显示掩码还是水印
`IsReadOnly`	`bool`	`false`	禁止用户编辑
`IsVisibleRepeatButton`	`bool`	`false`	显示上下微调按钮
`EnableMouseWheelEdit`	`bool`	`true`	允许通过鼠标滚轮更改值