syncfusion-winforms-datetimepicker

Windows Forms 日期时间编辑器（SfDateTimeEdit）

Syncfusion Windows Forms SfDateTimeEdit 控件支持用户以文本或掩码格式编辑 DateTime 值，并提供最小值和最大值验证、水印、自定义模式及全球化支持。

何时使用此技能

在需要以下功能时使用此技能：

• 编辑日期和时间值，支持格式化输入和验证
• 实现日期选择器，用于表单、约会或日程安排应用程序
• 限制日期范围，设置最小和最大日期约束
• 以各种格式显示日期（长日期、短日期、时间、自定义模式）
• 支持掩码模式编辑，实现逐字段导航和上下按钮操作
• 处理可空日期，并显示水印文本
• 验证日期输入，并使用自定义错误消息
• 支持多种区域性和全球化需求
• **实现 RTL（从右到左）**日期编辑，适用于国际化应用程序
• 创建约会日程安排器或基于日期的筛选界面

组件概述

主要功能：

• **编辑模式：**默认（文本）和掩码（格式化字段导航）
• **日期范围验证：**MinDateTime 和 MaxDateTime 属性
• **显示模式：**LongDate、ShortDate、LongTime、ShortTime、FullDateTime、MonthDay、YearMonth、Custom
• **可空日期：**AllowNull，并支持水印文本
• **验证：**内置验证和错误消息
• **全球化：**基于区域性的格式和模式
• **导航：**使用 Tab、方向键和上下按钮进行字段导航
• **外观：**主题、字体、颜色、边框、日历下拉菜单

文档和导航指南

入门

📄 阅读：references/getting-started.md

在需要以下内容时阅读此参考文档：

• 通过 NuGet 或设计器安装 SfDateTimeEdit
• 将控件添加到 Windows Forms 项目
• 以编程方式创建 SfDateTimeEdit 实例
• 设置基本的 Value 属性
• 配置初始日期时间选择器
• 了解程序集要求

日期范围和值

📄 阅读：references/date-range-value.md

在需要以下内容时阅读此参考文档：

• 设置和获取 Value 属性
• 实现 MinDateTime 和 MaxDateTime 约束
• 使用 AllowNull 启用可空日期
• 使用 DateTimeText 属性设置基于文本的值
• 处理值更改事件
• 验证日期范围限制

显示模式

📄 阅读：references/display-patterns.md

在需要以下内容时阅读此参考文档：

• 设置 DateTimePattern（LongDate、ShortDate、LongTime 等）
• 使用 Format 属性创建自定义显示格式
• 以不同格式显示日期
• 设置特定区域性的日期格式
• 仅显示月份/年份
• 仅显示时间

编辑模式

📄 阅读：references/editing-modes.md

在需要以下内容时阅读此参考文档：

• 在 Default 和 Mask 编辑模式之间切换
• 启用逐字段导航
• 配置 ShowUpDown 按钮
• 实现键盘快捷键
• 处理 Tab 和方向键导航
• 增加/减少日期字段

外观和样式

📄 阅读：references/appearance-styling.md

在需要以下内容时阅读此参考文档：

• 使用 Style 和 ThemeName 应用主题
• 自定义字体、颜色和边框
• 配置日历下拉菜单的外观
• 显示/隐藏下拉按钮
• 设置控件大小和布局
• 添加工具提示

验证和功能

📄 阅读：references/validation-features.md

在需要以下内容时阅读此参考文档：

• 配置验证模式
• 处理 ValidationCompleted 事件
• 显示验证错误消息
• 为 null 值设置水印文本
• 实现全球化和区域性支持
• 启用 RTL（从右到左）模式
• 设置 ReadOnly 模式

快速入门

基本日期时间选择器

using Syncfusion.WinForms.Input;

// Create datetime editor
SfDateTimeEdit dateTimeEdit = new SfDateTimeEdit();
dateTimeEdit.Location = new Point(20, 20);
dateTimeEdit.Size = new Size(200, 30);
dateTimeEdit.Value = DateTime.Now;

// Add to form
this.Controls.Add(dateTimeEdit);

VB.NET：

Imports Syncfusion.WinForms.Input

' Create datetime editor
Dim dateTimeEdit As New SfDateTimeEdit()
dateTimeEdit.Location = New Point(20, 20)
dateTimeEdit.Size = New Size(200, 30)
dateTimeEdit.Value = DateTime.Now

' Add to form
Me.Controls.Add(dateTimeEdit)

常见模式

模式 1：限制日期范围的日期选择器

// Appointment date picker (next 30 days only)
SfDateTimeEdit appointmentDate = new SfDateTimeEdit();
appointmentDate.Value = DateTime.Now;
appointmentDate.MinDateTime = DateTime.Now;
appointmentDate.MaxDateTime = DateTime.Now.AddDays(30);
appointmentDate.DateTimePattern = DateTimePattern.LongDate;

this.Controls.Add(appointmentDate);

模式 2：仅时间选择器

// Time selection control
SfDateTimeEdit timePicker = new SfDateTimeEdit();
timePicker.Value = DateTime.Now;
timePicker.DateTimePattern = DateTimePattern.LongTime;
timePicker.DateTimeEditingMode = DateTimeEditingMode.Mask;
timePicker.ShowUpDown = true;

this.Controls.Add(timePicker);

模式 3：自定义格式日期编辑器

// Custom format: "DD-MMM-YYYY" (e.g., "25-Dec-2024")
SfDateTimeEdit customDate = new SfDateTimeEdit();
customDate.Value = DateTime.Now;
customDate.DateTimePattern = DateTimePattern.Custom;
customDate.Format = "dd-MMM-yyyy";

this.Controls.Add(customDate);

模式 4：带水印的可空日期

// Optional date field with watermark
SfDateTimeEdit optionalDate = new SfDateTimeEdit();
optionalDate.DateTimeEditingMode = DateTimeEditingMode.Mask;
optionalDate.AllowNull = true;
optionalDate.Value = null;
optionalDate.Watermark = "Select a date...";

this.Controls.Add(optionalDate);

模式 5：带上下按钮的掩码模式

// Field-by-field editing with increment/decrement
SfDateTimeEdit maskEditor = new SfDateTimeEdit();
maskEditor.Value = DateTime.Now;
maskEditor.DateTimeEditingMode = DateTimeEditingMode.Mask;
maskEditor.ShowUpDown = true;
maskEditor.DateTimePattern = DateTimePattern.ShortDate;

this.Controls.Add(maskEditor);

模式 6：日期范围筛选器

// Date range for filtering (From/To dates)
SfDateTimeEdit fromDate = new SfDateTimeEdit();
fromDate.Value = DateTime.Now.AddDays(-30);
fromDate.DateTimePattern = DateTimePattern.ShortDate;

SfDateTimeEdit toDate = new SfDateTimeEdit();
toDate.Value = DateTime.Now;
toDate.DateTimePattern = DateTimePattern.ShortDate;
toDate.MinDateTime = fromDate.Value.Value;

// Update toDate minimum when fromDate changes
fromDate.ValueChanged += (s, e) => {
    if (fromDate.Value.HasValue)
        toDate.MinDateTime = fromDate.Value.Value;
};

this.Controls.Add(fromDate);
this.Controls.Add(toDate);

模式 7：经过验证的日期输入

// Date entry with validation
SfDateTimeEdit validatedDate = new SfDateTimeEdit();
validatedDate.Value = DateTime.Now;
validatedDate.MinDateTime = new DateTime(2020, 1, 1);
validatedDate.MaxDateTime = new DateTime(2030, 12, 31);

validatedDate.ValidationCompleted += (s, e) => {
    if (!e.IsValid)
    {
        MessageBox.Show($"Invalid date: {e.ErrorMessage}");
    }
};

this.Controls.Add(validatedDate);

主要属性

属性	类型	说明
Value	DateTime?	当前日期时间值（可为空）
MinDateTime	DateTime	允许的最小日期时间
MaxDateTime	DateTime	允许的最大日期时间
DateTimePattern	DateTimePattern	显示格式（LongDate、ShortDate、LongTime 等）
Format	string	自定义日期时间格式字符串
DateTimeEditingMode	DateTimeEditingMode	编辑模式（Default 或 Mask）
AllowNull	bool	启用空值支持
Watermark	string	值为空时显示的文本
ShowUpDown	bool	在掩码模式下显示上下按钮
DateTimeText	string	日期时间文本字符串
ValidationErrorMessage	string	自定义验证错误消息
Style	SfDateTimeEditStyle	视觉样式／主题
ReadOnly	bool	启用只读模式
ToolTipText	string	控件的工具提示文本

主要事件

事件	说明
ValueChanged	Value 属性发生更改时触发
ValidationCompleted	验证完成后触发
DateTimeTextChanged	DateTimeText 发生更改时触发

常见用例

用例 1：预约安排

在营业时间限制内选择预约日期和时间。

用例 2：日期范围筛选

为报表或数据查询实现“开始日期”到“结束日期”筛选器。

用例 3：出生日期输入

录入出生日期，并限制为过去的日期及使用自定义格式。

用例 4：时间输入

用于排班或时间跟踪的纯时间输入。

用例 5：可选日期字段

表单中的日期字段可为空，字段为空时显示水印。

用例 6：国际化日期输入

采用特定区域设置的日期格式，并支持阿拉伯语、希伯来语等语言的 RTL 布局。

最佳实践

1. 设置适当的日期范围：使用 MinDateTime 和 MaxDateTime，防止选择无效日期
2. 选择正确的模式：在空间受限的 UI 中使用 ShortDate；为提高可读性使用 LongDate
3. 启用掩码模式以实现精准编辑：使用 DateTimeEditingMode.Mask 按字段编辑
4. 为可选日期显示水印：设置 AllowNull=true，并提供清晰的水印文本
5. 在 ValueChanged 时进行验证：在 ValueChanged 事件处理程序中实现验证逻辑
6. 谨慎使用自定义格式：坚持使用标准模式，让用户更熟悉
7. 考虑区域设置：如果支持国际用户，请使用不同的区域设置进行测试
8. 处理空值：使用 Value.Value 前，务必检查 Value.HasValue
9. 提供工具提示：使用 ToolTipText 指导用户了解日期格式或限制
10. 测试键盘导航：确保在掩码模式下 Tab 键和方向键可流畅使用

与 DateTimePickerAdv 的比较

在以下情况下使用 SfDateTimeEdit：

• 需要采用主题的现代 UI
• 需要支持字段导航的掩码模式
• 需要水印支持
• 需要更完善的验证功能
• 需要特定区域设置的模式

在以下情况下使用 DateTimePickerAdv：

• 需要自定义上下按钮／下拉按钮的外观
• 需要兼容旧版应用程序
• 需要 SfDateTimeEdit 未提供的特定高级自定义功能