Back to Details

syncfusion-winforms-datetimepicker

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Windows Forms DateTime Editor (SfDateTimeEdit)

Windows Forms DateTime 编辑器 (SfDateTimeEdit)

The Syncfusion Windows Forms SfDateTimeEdit control allows users to edit DateTime values in text or mask format with support for minimum and maximum value validation, watermark, custom patterns, and globalization.
Syncfusion Windows Forms SfDateTimeEdit控件支持用户以文本或掩码格式编辑DateTime值，同时提供最值校验、水印、自定义格式和全球化能力支持。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Edit date and time values with formatted input and validation
  • Implement date pickers for forms, appointments, or scheduling applications
  • Restrict date ranges with minimum and maximum date constraints
  • Display dates in various formats (long date, short date, time, custom patterns)
  • Support mask mode editing with field-by-field navigation and up-down buttons
  • Handle nullable dates with watermark text display
  • Validate date input with custom error messages
  • Support multiple cultures and globalization requirements
  • Implement RTL (Right-to-Left) date editing for international applications
  • Create appointment schedulers or date-based filtering interfaces
当你需要满足以下需求时可使用本技能：
  • 带格式化输入与校验的日期时间值编辑
  • 为表单、预约或日程类应用实现日期选择器
  • 通过最小/最大日期约束限制可选日期范围
  • 以多种格式展示日期（长日期、短日期、时间、自定义格式等）
  • 支持带逐字段导航和上下按钮的掩码模式编辑
  • 通过水印文本展示能力处理可空日期
  • 带自定义错误提示的日期输入校验
  • 支持多语言和全球化需求
  • 为国际化应用实现**RTL（从右到左）**日期编辑能力
  • 构建预约日程表或基于日期的筛选界面

Component Overview

组件概览

Key Features:
  • Editing modes: Default (text) and Mask (formatted field navigation)
  • Date range validation: MinDateTime and MaxDateTime properties
  • Display patterns: LongDate, ShortDate, LongTime, ShortTime, FullDateTime, MonthDay, YearMonth, Custom
  • Nullable dates: AllowNull with watermark text support
  • Validation: Built-in validation with error messages
  • Globalization: Culture-based formatting and patterns
  • Navigation: Tab, arrow keys, up-down buttons for field navigation
  • Appearance: Themes, fonts, colors, borders, calendar dropdown
核心特性：
  • 编辑模式： 默认（文本）和掩码（格式化字段导航）两种模式
  • 日期范围校验： 支持MinDateTime和MaxDateTime属性配置
  • 展示格式： 长日期、短日期、长时间、短时间、完整日期时间、月日、年月、自定义格式
  • 可空日期： 支持AllowNull配置与水印文本展示
  • 校验能力： 内置校验能力与错误提示
  • 全球化： 基于区域文化的格式化与展示规则
  • 导航能力： 支持Tab键、方向键、上下按钮进行字段导航
  • 外观配置： 支持主题、字体、颜色、边框、日历下拉面板配置

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
Read this reference when you need to:
  • Install SfDateTimeEdit via NuGet or designer
  • Add the control to a Windows Forms project
  • Create SfDateTimeEdit instance programmatically
  • Set basic Value property
  • Configure initial datetime picker setup
  • Understand assembly requirements
📄 阅读： references/getting-started.md
当你需要实现以下需求时阅读该参考文档：
  • 通过NuGet或设计器安装SfDateTimeEdit
  • 将控件添加到Windows Forms项目中
  • 通过代码创建SfDateTimeEdit实例
  • 设置基础的Value属性
  • 配置日期选择器的基础初始化参数
  • 了解程序集依赖要求

Date Range and Value

日期范围与值配置

📄 Read: references/date-range-value.md
Read this reference when you need to:
  • Set and get Value property
  • Implement MinDateTime and MaxDateTime constraints
  • Enable nullable dates with AllowNull
  • Use DateTimeText property for text-based values
  • Handle value change events
  • Validate date range restrictions
📄 阅读： references/date-range-value.md
当你需要实现以下需求时阅读该参考文档：
  • 设置与获取Value属性
  • 配置MinDateTime和MaxDateTime约束
  • 通过AllowNull启用可空日期能力
  • 使用DateTimeText属性处理文本格式的日期值
  • 处理值变更事件
  • 校验日期范围限制

Display Patterns

展示格式配置

📄 Read: references/display-patterns.md
Read this reference when you need to:
  • Set DateTimePattern (LongDate, ShortDate, LongTime, etc.)
  • Create custom display formats with Format property
  • Display dates in different formats
  • Culture-specific date formatting
  • Month/year only displays
  • Time-only displays
📄 阅读： references/display-patterns.md
当你需要实现以下需求时阅读该参考文档：
  • 设置DateTimePattern（长日期、短日期、长时间等）
  • 通过Format属性创建自定义展示格式
  • 以不同格式展示日期
  • 配置区域文化专属的日期格式化规则
  • 仅展示年月/仅展示时间

Editing Modes

编辑模式配置

📄 Read: references/editing-modes.md
Read this reference when you need to:
  • Switch between Default and Mask editing modes
  • Enable field-by-field navigation
  • Configure ShowUpDown buttons
  • Implement keyboard shortcuts
  • Handle Tab and arrow key navigation
  • Increment/decrement date fields
📄 阅读： references/editing-modes.md
当你需要实现以下需求时阅读该参考文档：
  • 切换默认编辑模式与掩码编辑模式
  • 启用逐字段导航能力
  • 配置ShowUpDown上下按钮展示
  • 实现快捷键支持
  • 处理Tab键与方向键导航逻辑
  • 增减日期字段值

Appearance and Styling

外观与样式配置

📄 Read: references/appearance-styling.md
Read this reference when you need to:
  • Apply themes with Style and ThemeName
  • Customize fonts, colors, and borders
  • Configure calendar dropdown appearance
  • Show/hide dropdown button
  • Set control size and layout
  • Add tooltips
📄 阅读： references/appearance-styling.md
当你需要实现以下需求时阅读该参考文档：
  • 通过Style和ThemeName应用主题
  • 自定义字体、颜色和边框
  • 配置日历下拉面板外观
  • 展示/隐藏下拉按钮
  • 设置控件尺寸与布局
  • 添加提示框

Validation and Features

校验与特性配置

📄 Read: references/validation-features.md
Read this reference when you need to:
  • Configure validation modes
  • Handle ValidationCompleted event
  • Display validation error messages
  • Set watermark text for null values
  • Implement globalization and culture support
  • Enable RTL (Right-to-Left) mode
  • Set ReadOnly mode
📄 阅读： references/validation-features.md
当你需要实现以下需求时阅读该参考文档：
  • 配置校验模式
  • 处理ValidationCompleted事件
  • 展示校验错误提示
  • 为空值设置水印文本
  • 实现全球化与区域文化支持
  • 启用RTL（从右到左）模式
  • 设置只读模式

Quick Start

快速入门

Basic DateTime Picker

基础日期时间选择器

csharp
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:
vb
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)
csharp
using Syncfusion.WinForms.Input;

// 创建日期时间编辑器
SfDateTimeEdit dateTimeEdit = new SfDateTimeEdit();
dateTimeEdit.Location = new Point(20, 20);
dateTimeEdit.Size = new Size(200, 30);
dateTimeEdit.Value = DateTime.Now;

// 添加到表单
this.Controls.Add(dateTimeEdit);
VB.NET:
vb
Imports Syncfusion.WinForms.Input

' 创建日期时间编辑器
Dim dateTimeEdit As New SfDateTimeEdit()
dateTimeEdit.Location = New Point(20, 20)
dateTimeEdit.Size = New Size(200, 30)
dateTimeEdit.Value = DateTime.Now

' 添加到表单
Me.Controls.Add(dateTimeEdit)

Common Patterns

常用实现模式

Pattern 1: Date Picker with Range Restriction

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

csharp
// 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);
csharp
// 预约日期选择器（仅可选择未来30天）
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);

Pattern 2: Time Picker Only

模式2：仅时间选择器

csharp
// 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);
csharp
// 时间选择控件
SfDateTimeEdit timePicker = new SfDateTimeEdit();
timePicker.Value = DateTime.Now;
timePicker.DateTimePattern = DateTimePattern.LongTime;
timePicker.DateTimeEditingMode = DateTimeEditingMode.Mask;
timePicker.ShowUpDown = true;

this.Controls.Add(timePicker);

Pattern 3: Custom Format Date Editor

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

csharp
// 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);
csharp
// 自定义格式："DD-MMM-YYYY"（示例："25-Dec-2024"）
SfDateTimeEdit customDate = new SfDateTimeEdit();
customDate.Value = DateTime.Now;
customDate.DateTimePattern = DateTimePattern.Custom;
customDate.Format = "dd-MMM-yyyy";

this.Controls.Add(customDate);

Pattern 4: Nullable Date with Watermark

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

csharp
// 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);
csharp
// 带水印的可选日期字段
SfDateTimeEdit optionalDate = new SfDateTimeEdit();
optionalDate.DateTimeEditingMode = DateTimeEditingMode.Mask;
optionalDate.AllowNull = true;
optionalDate.Value = null;
optionalDate.Watermark = "Select a date...";

this.Controls.Add(optionalDate);

Pattern 5: Mask Mode with Up-Down Buttons

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

csharp
// 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);
csharp
// 支持值增减的逐字段编辑
SfDateTimeEdit maskEditor = new SfDateTimeEdit();
maskEditor.Value = DateTime.Now;
maskEditor.DateTimeEditingMode = DateTimeEditingMode.Mask;
maskEditor.ShowUpDown = true;
maskEditor.DateTimePattern = DateTimePattern.ShortDate;

this.Controls.Add(maskEditor);

Pattern 6: Date Range Filter

模式6：日期范围筛选器

csharp
// 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);
csharp
// 筛选用日期范围（开始/结束日期）
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;

// 开始日期变更时更新结束日期的最小值
fromDate.ValueChanged += (s, e) => {
    if (fromDate.Value.HasValue)
        toDate.MinDateTime = fromDate.Value.Value;
};

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

Pattern 7: Validated Date Entry

模式7：带校验的日期输入框

csharp
// 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);
csharp
// 带校验的日期输入
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);

Key Properties

核心属性

PropertyTypeDescription
Value
DateTime?Current date-time value (nullable)
MinDateTime
DateTimeMinimum allowed date-time
MaxDateTime
DateTimeMaximum allowed date-time
DateTimePattern
DateTimePatternDisplay format (LongDate, ShortDate, LongTime, etc.)
Format
stringCustom date-time format string
DateTimeEditingMode
DateTimeEditingModeEditing mode (Default or Mask)
AllowNull
boolEnable null value support
Watermark
stringText displayed when value is null
ShowUpDown
boolShow up-down buttons for mask mode
DateTimeText
stringDate-time as text string
ValidationErrorMessage
stringCustom validation error message
Style
SfDateTimeEditStyleVisual style/theme
ReadOnly
boolEnable read-only mode
ToolTipText
stringTooltip text for control
属性类型描述
Value
DateTime?当前日期时间值（可空）
MinDateTime
DateTime允许的最小日期时间值
MaxDateTime
DateTime允许的最大日期时间值
DateTimePattern
DateTimePattern展示格式（长日期、短日期、长时间等）
Format
string自定义日期时间格式字符串
DateTimeEditingMode
DateTimeEditingMode编辑模式（默认或掩码）
AllowNull
bool启用空值支持
Watermark
string值为空时展示的水印文本
ShowUpDown
bool掩码模式下展示上下调整按钮
DateTimeText
string字符串格式的日期时间值
ValidationErrorMessage
string自定义校验错误提示信息
Style
SfDateTimeEditStyle视觉样式/主题
ReadOnly
bool启用只读模式
ToolTipText
string控件的提示框文本

Key Events

核心事件

EventDescription
ValueChanged
Occurs when Value property changes
ValidationCompleted
Occurs after validation is completed
DateTimeTextChanged
Occurs when DateTimeText changes
事件描述
ValueChanged
Value属性变更时触发
ValidationCompleted
校验完成后触发
DateTimeTextChanged
DateTimeText变更时触发

Common Use Cases

常见用例

Use Case 1: Appointment Scheduling

用例1：预约日程安排

Select appointment date and time with business hours constraints.
选择预约日期与时间，支持营业时间范围限制

Use Case 2: Date Range Filtering

用例2：日期范围筛选

Implement "From Date" to "To Date" filters for reports or data queries.
为报表或数据查询实现「开始日期」到「结束日期」的筛选能力

Use Case 3: Birth Date Entry

用例3：出生日期输入

Capture birth dates with past date restrictions and custom format.
采集出生日期，支持过往日期限制与自定义格式

Use Case 4: Time Entry

用例4：时间录入

Time-only input for shift scheduling or time tracking.
为排班或工时跟踪场景实现仅时间输入能力

Use Case 5: Optional Date Fields

用例5：可选日期字段

Forms with nullable date fields showing watermark when empty.
表单中可空的日期字段，为空时展示水印提示

Use Case 6: International Date Input

用例6：国际化日期输入

Culture-specific date formatting with RTL support for Arabic, Hebrew, etc.
支持阿拉伯语、希伯来语等区域文化的RTL格式与专属日期格式化规则

Best Practices

最佳实践

  1. Set appropriate date ranges: Use MinDateTime and MaxDateTime to prevent invalid date selection
  2. Choose correct pattern: Use ShortDate for space-constrained UIs, LongDate for clarity
  3. Enable mask mode for precision: Use DateTimeEditingMode.Mask for field-by-field editing
  4. Show watermark for optional dates: Set AllowNull=true and provide clear watermark text
  5. Validate on ValueChanged: Implement validation logic in ValueChanged event handler
  6. Use custom formats sparingly: Stick to standard patterns for better user familiarity
  7. Consider culture settings: Test with different cultures if supporting international users
  8. Handle null values: Always check Value.HasValue before using Value.Value
  9. Provide tooltips: Use ToolTipText to guide users on date format or constraints
  10. Test keyboard navigation: Ensure Tab and arrow keys work smoothly in mask mode
  1. 设置合理的日期范围： 使用MinDateTime和MaxDateTime避免无效日期选择
  2. 选择合适的展示格式： 空间受限的UI使用短日期格式，需要高可读性时使用长日期格式
  3. 高精度场景启用掩码模式： 使用DateTimeEditingMode.Mask实现逐字段编辑
  4. 可选日期展示水印： 配置AllowNull=true并提供清晰的水印提示文本
  5. 在ValueChanged事件中校验： 在ValueChanged事件处理函数中实现校验逻辑
  6. 谨慎使用自定义格式： 优先使用标准格式提升用户熟悉度
  7. 考虑区域文化设置： 如果需要支持国际化用户，需测试不同区域文化下的展示效果
  8. 处理空值： 使用Value.Value前务必先校验Value.HasValue
  9. 提供提示框： 使用ToolTipText引导用户了解日期格式或约束规则
  10. 测试键盘导航： 确保掩码模式下Tab键和方向键可正常流畅使用

Comparison with DateTimePickerAdv

与DateTimePickerAdv的对比

Use SfDateTimeEdit when you need:
  • Modern UI with themes
  • Mask mode with field navigation
  • Watermark support
  • Better validation features
  • Culture-specific patterns
Use DateTimePickerAdv when you need:
  • Custom up-down/dropdown button appearance
  • Legacy application compatibility
  • Specific advanced customization not in SfDateTimeEdit
当你需要以下能力时选择SfDateTimeEdit：
  • 带主题的现代化UI
  • 支持字段导航的掩码模式
  • 水印支持
  • 更完善的校验能力
  • 区域文化专属格式
当你需要以下能力时选择DateTimePickerAdv：
  • 自定义上下/下拉按钮外观
  • 老旧应用兼容性
  • SfDateTimeEdit不支持的特定高级定制能力

Related Components

相关组件

  • DateTimePickerAdv: Legacy DateTime picker with advanced button customization
  • SfCalendar: Standalone calendar control for date selection
  • DateTimePicker: Standard Windows Forms DateTime picker
  • DateTimePickerAdv：支持高级按钮自定义的老旧版本日期选择器
  • SfCalendar：独立的日历控件，用于日期选择
  • DateTimePicker：Windows Forms官方标准日期时间选择器