WinForm之DateTimePicker 控件

原创于 2025-08-05 09:54:16 发布 · 1.4k 阅读

CC 4.0 BY-SA版权

文章标签：

在 WinForm（Windows Forms）中，DateTimePicker 是一个用于选择日期和时间的交互式控件，它提供了直观的日历界面和时间输入功能，常用于需要用户输入日期（如生日、预约时间）或时间（如下单时间、提醒时间）的场景。相比手动输入文本框，DateTimePicker 能有效减少格式错误，提升用户体验。

一、核心属性与功能

DateTimePicker 的核心属性决定了其显示格式、可选范围和交互方式，常用属性如下：

1. Format（显示格式）

控制日期 / 时间的显示格式，类型为 DateTimePickerFormat 枚举，可选值：

Long：长日期格式（如 “2024 年 7 月 31 日”，受系统区域设置影响）。
Short：短日期格式（如 “2024/7/31”）。
Time：仅显示时间（如 “15:30:45”）。
Custom：自定义格式（需配合 CustomFormat 属性）。

示例：

// 设置为短日期格式
dateTimePicker1.Format = DateTimePickerFormat.Short;

// 设置为自定义格式（显示“年-月-日 时:分”）
dateTimePicker1.Format = DateTimePickerFormat.Custom;
dateTimePicker1.CustomFormat = "yyyy-MM-dd HH:mm";

2. Value（当前选中值）

获取或设置控件当前选中的日期时间，类型为 DateTime。默认值为系统当前时间。

示例：

// 获取选中的日期时间
DateTime selectedDate = dateTimePicker1.Value;

// 代码中设置默认值（如设置为2024年1月1日）
dateTimePicker1.Value = new DateTime(2024, 1, 1);

3. ShowUpDown（上下箭头调整）

类型：bool，默认 false。

设为 true 时，控件不显示日历弹窗，改为通过上下箭头按钮调整日期 / 时间（适合精确调整小时、分钟）。
设为 false 时，点击控件右侧下拉按钮会显示日历弹窗（默认行为）。

4. MinDate/MaxDate（限制选择范围）

MinDate：设置可选择的最小日期（默认：1/1/1753）。
MaxDate：设置可选择的最大日期（默认：12/31/9998）。

用于限制用户只能选择特定范围内的日期（如只能选择今天及以后的日期）。

示例：

// 只能选择今天及之后的日期
dateTimePicker1.MinDate = DateTime.Today;
// 最大可选择30天后的日期
dateTimePicker1.MaxDate = DateTime.Today.AddDays(30);

5. ShowCheckBox（允许 “未选择” 状态）

类型：bool，默认 false。

设为 true 时，控件左侧会显示一个复选框。
复选框勾选时，Value 有效；未勾选时，可视为 “未选择” 状态（需通过 Checked 属性判断）。

示例：

// 允许未选择状态
dateTimePicker1.ShowCheckBox = true;

// 判断是否选择了日期
if (dateTimePicker1.Checked)
{
    DateTime selected = dateTimePicker1.Value;
}
else
{
    MessageBox.Show("未选择日期");
}

二、核心事件：ValueChanged

当用户修改选中的日期 / 时间（或通过代码修改 Value）时，会触发 ValueChanged 事件。常用于实时响应用户的选择操作。

核心属性与事件（表格整理）

类别	名称	类型 / 枚举值	说明
核心属性	`Format`	`DateTimePickerFormat`	控制显示格式：`Long`（长日期）、`Short`（短日期）、`Time`（时间）、`Custom`（自定义，需配合`CustomFormat`）
	`CustomFormat`	`string`	自定义格式字符串（如`"yyyy-MM-dd HH:mm:ss"`），仅`Format=Custom`时生效
	`Value`	`DateTime`	获取 / 设置当前选中的日期时间（默认值为系统当前时间）
	`MinDate`	`DateTime`	可选择的最小日期（默认`1/1/1753`）
	`MaxDate`	`DateTime`	可选择的最大日期（默认`12/31/9998`）
	`ShowUpDown`	`bool`	`true`时隐藏日历弹窗，用上下箭头调整日期 / 时间；`false`显示日历弹窗（默认）
	`ShowCheckBox`	`bool`	`true`时显示复选框，未勾选时视为 “未选择” 状态（通过`Checked`属性判断）
	`Checked`	`bool`	配合`ShowCheckBox`使用，指示是否选择了日期（勾选为`true`）
	`Text`	`string`	控件显示的文本（格式由`Format`决定，优先用`Value`获取实际值）
核心事件	`ValueChanged`	事件	选中的日期 / 时间发生变化时触发（用户操作或代码修改`Value`时）
	`DropDown`	事件	日历弹窗展开时触发
	`CloseUp`	事件	日历弹窗关闭时触发
	`Validating`	事件	控件失去焦点时触发，可用于校验输入格式

三、基本用法示例（选择日期并显示）

以下示例演示如何使用 DateTimePicker 让用户选择日期，并在标签中实时显示所选结果：

1. 界面设计

在窗体中添加：

一个 DateTimePicker 控件（命名为 dateTimePicker1）。
一个 Label 控件（命名为 lblResult，用于显示结果）。

2. 代码实现

using System;
using System.Windows.Forms;

namespace DateTimePickerDemo
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
            
            // 初始化控件：设置为短日期格式，最小日期为今天
            dateTimePicker1.Format = DateTimePickerFormat.Short;
            dateTimePicker1.MinDate = DateTime.Today;
            dateTimePicker1.Value = DateTime.Today; // 默认选中今天
        }

        // ValueChanged事件：用户选择变化时触发
        private void dateTimePicker1_ValueChanged(object sender, EventArgs e)
        {
            // 显示选中的日期
            lblResult.Text = $"您选择的日期是：{dateTimePicker1.Value:yyyy年MM月dd日}";
        }
    }
}

四、进阶用法与技巧

1. 仅显示日期或仅显示时间

仅显示日期：默认 Format 为 Short 或 Long 即可（不包含时间）。
仅显示时间：设置 Format = DateTimePickerFormat.Time，此时控件默认显示时间，且 ShowUpDown 自动生效（方便调整小时 / 分钟）。

2. 自定义格式（CustomFormat）

通过 CustomFormat 可定义任意日期时间格式，常用格式符：

yyyy：四位年份（如 2024）；yy：两位年份（如 24）。
MM：两位月份（01-12）；M：一位或两位月份（1-12）。
dd：两位日期（01-31）；d：一位或两位日期（1-31）。
HH：24 小时制小时（00-23）；hh：12 小时制小时（01-12）。
mm：分钟（00-59）；ss：秒（00-59）。
tt：上午 / 下午（如 “AM”“PM”，仅 12 小时制有效）。

示例：

// 显示“2024-07-31 15:30 周三”
dateTimePicker1.Format = DateTimePickerFormat.Custom;
dateTimePicker1.CustomFormat = "yyyy-MM-dd HH:mm ddd";

3. 隐藏日历弹窗，仅允许手动输入

设置 ShowUpDown = true 并结合 ReadOnly = true，可禁止用户通过弹窗选择，仅允许通过上下箭头或手动输入（需确保输入格式正确）。

4. 本地化显示

DateTimePicker 会默认跟随系统区域设置显示日期格式（如中文系统显示 “年 / 月 / 日”，英文系统显示 “MM/dd/yyyy”）。若需强制固定格式，需手动设置 CustomFormat。

五、常见问题与解决方案

1. 如何获取 “未选择” 状态？

默认情况下，DateTimePicker 必须有一个选中值（Value 不为空）。若需支持 “未选择”，需设置 ShowCheckBox = true，通过 Checked 属性判断：

if (dateTimePicker1.Checked)
{
    // 有选择
}
else
{
    // 未选择
}

2. 输入格式错误的处理

若允许用户手动输入日期（ShowUpDown = false 时），输入不符合格式的内容会自动恢复为上一次有效值。若需自定义校验，可在 Validating 事件中处理：

private void dateTimePicker1_Validating(object sender, System.ComponentModel.CancelEventArgs e)
{
    // 尝试解析输入的文本（Text属性）
    if (!DateTime.TryParse(dateTimePicker1.Text, out _))
    {
        e.Cancel = true; // 阻止焦点离开
        MessageBox.Show("请输入有效的日期！");
    }
}