syncfusion-wpf-datetimepicker

实现 DateTimeEdit（WPF）

增强型日期时间输入控件，支持掩码编辑、日历/时钟下拉菜单、日期范围限制、格式设置和 MVVM 绑定。

何时使用此技能

当用户需要以下功能时，请使用此技能：

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

---

组件概览

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

XAML 命名空间：

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

NuGet：

Install-Package Syncfusion.Shared.WPF

---

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 程序集设置和 XAML 命名空间
• 通过设计器、XAML 或 C# 添加
• 设置 DateTime 值
• 使用 DateTimeChanged 事件进行 MVVM 双向绑定
• 预定义 Pattern 快速参考
• MinDateTime / MaxDateTime 基础知识
• SfSkinManager 主题设置

日期时间编辑

📄 阅读： references/datetime-editing.md

• 掩码编辑（默认）——按字段输入并自动验证
• 在日期/时间字段之间进行键盘导航
• 自由文本编辑（CanEdit="True"）
• 鼠标滚轮更改值（EnableMouseWheelEdit）
• 上/下重复按钮（IsVisibleRepeatButton、IsEnabledRepeatButton）
• 自定义重复按钮 UI 模板
• 字母键月份导航（EnableAlphaKeyNavigation）
• BackSpace/Delete 键编辑
• OnFocusBehavior 和 AutoForwarding 焦点控制

格式和区域设置

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

• 全部 11 个预定义 Pattern 值
• 配合 Pattern="CustomPattern" 使用 CustomPattern
• 使用 DateTimeFormatInfo 设置 DateTimeFormat
• 使用 CultureInfo 设置特定区域的格式
• PatternChanged / CustomPatternChanged 事件

下拉弹出窗口

📄 阅读： references/dropdown-popup.md

• DropDownView：日历 / 时钟 / 组合
• 键盘快捷键（Alt+Down、F4）
• TodayButtonAction（Date 或 DateTime）
• IsEmptyDateEnabled —— None 按钮 / 重置为空值
• AbbreviatedMonthNames / ShortestDayNames
• PopupDelay、IsButtonPopUpEnabled
• DropDownButtonTemplate 自定义 UI
• 自定义日历和时钟（SfDateSelector / SfTimeSelector）
• 时钟的 TimeStepInterval

日期限制和空值

📄 阅读： references/date-restrictions.md

• MinDateTime / MaxDateTime —— 防止选择超出范围的日期
• BlackoutDates —— 禁用特定日期范围
• DisableDateSelection —— 仅允许选择月份/年份
• IsReadOnly —— 禁止所有用户编辑
• NullValue / IsEmptyDateEnabled / ShowMaskOnNullValue
• NoneDateText 水印

外观

📄 阅读： references/appearance.md

• Foreground、Background、SelectionBrush
• FocusedBorderBrush
• FlowDirection RTL
• 重复按钮背景和边距
• SfSkinManager 主题列表

本地化

📄 阅读： references/localization.md

• CurrentUICulture 设置
• 资源文件命名：Syncfusion.Shared.Wpf.{culture}.resx
• Today/None 按钮标签的名称/值对
• 法语区域设置示例

---

快速入门示例

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

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

---

常见模式

场景	属性 / 方法
双向日期绑定	DateTime="{Binding SelectedDate, Mode=TwoWay}"
显示日历和时钟	DropDownView="Combined" Pattern="FullDateTime"
自由文本编辑	CanEdit="True"
限制日期范围	MinDateTime="..." MaxDateTime="..."
允许空值 / 清除值	IsEmptyDateEnabled="True" NullValue="{x:Null}" ShowMaskOnNullValue="False"
空值时显示水印	在空值属性旁添加 NoneDateText="Select a date"
自定义日期显示	Pattern="CustomPattern" CustomPattern="dd-MMM-yyyy"
根据区域设置格式化	CultureInfo="fr-FR" Pattern="FullDateTime"
只读输入	IsReadOnly="True"
从右到左布局	FlowDirection="RightToLeft"
应用主题	SfSkinManager.SetVisualStyle(dte, VisualStyles.FluentLight)

---

关键属性

属性	类型	默认值	描述
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	允许使用鼠标滚轮更改值