---
url: /components/date-picker.md
---
# DatePicker 日期选择器

dayjs 驱动的日期选择器，`type` 覆盖日期、日期时间、月份、年份及对应区间共 7 种类型，支持快捷选项、禁用日期、value-format 与时间默认值。点击输入框打开面板，选中即回填；含时间的类型（datetime / datetimerange）面板底部有确定按钮，需确认后关闭。值变更与清空会自动触发所属表单项的 change 校验。

## 基础用法

默认 `type="date"`，`placeholder` 自定义占位；选择后悬停输入框出现清空按钮（`clearable`）。

## 选择器类型

单值类型 date / datetime / month / year，区间类型 daterange / datetimerange / monthrange；展示格式缺省按 type 取默认（如 year 为 YYYY、datetime 为 YYYY-MM-DD HH:mm:ss）。

## 区间选择

区间类型为双输入框 + 双面板，`range-separator` 自定义分隔符，`unlink-panels` 让左右面板独立切换年月，`start-placeholder` / `end-placeholder` 分别设置两个输入框的占位。

## 快捷选项与禁用日期

`shortcuts` 为 `{ text, value }` 数组（value 可为 Date 或返回 Date 的函数），显示在面板左侧；`disabled-date` 返回 true 的日期置灰不可选。

## 格式化与默认时间

`value-format` 指定对外值格式（v-model 得到字符串，缺省输出 Date 对象）；`format` 只改输入框展示格式；`default-time` 让 datetime 选中日期后时间部分取默认值，区间类型传数组分别作用于起止。

## 手动输入与空值定位

`editable` 允许在输入框按展示格式直接键入日期（无效输入自动回滚）；`default-value` 指定空值时面板默认定位到的日期，常用于"默认定位到业务月份"。

## 尺寸与禁用

`size` 控制输入框高度（large / default / small），`disabled` 禁用后点击与输入均无响应；两者均可由所属 Form 的 size / disabled 注入。

## 键盘操作

输入框聚焦后 Enter 或 ↓ 打开面板并把焦点送入日历网格；网格内：

| 按键 | 行为 |
| --- | --- |
| ← → ↑ ↓ | 移动一天 / 一周（禁用日自动跳过） |
| Home / End | 本周首日 / 末日 |
| PageUp / PageDown | 上 / 下一个月 |
| Shift + PageUp / PageDown | 上 / 下一年 |
| Enter / Space | 选中当前日期（区间为定起点 / 终点） |
| Esc | 关闭面板，焦点回到输入框 |

## API

## 移动端适配

容器环境为 mobile 时（ConfigProvider `platform` / 全局 `setPlatform()` / 自动探测），日期面板改为**底部弹出**呈现（全宽日历 + 安全区适配），确认选择即关闭；桌面环境保持浮层形态。下方演示强制移动形态：