DatePicker 日期选择器
uni-appH5微信小程序App
跨端日期选择器:触发器 + 内联面板,支持单日 / 日期范围 / 月份 / 年份 / 日期时间五种类型,含农历无关的公历日历网格、范围快捷选项、分钟步长、清空与可选范围限制。
何时使用
需要用户选择某一天、一段日期范围、某月、某年或某个日期时间:预约、筛选日期、出差起止、报表周期、财年统计等。
何时不使用
只需要时间(不带日期)时用 TimePicker;整月视图展示日程/农历用 Calendar。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | string | [string, string] | null | null | 绑定值:date 为 'YYYY-MM-DD';daterange 为 [开始, 结束];month 为 'YYYY-MM';year 为 'YYYY';datetime 为 'YYYY-MM-DD HH:mm' |
type | string:'date' | 'daterange' | 'month' | 'year' | 'datetime' | "date" | 选择类型:date 单日 / daterange 日期范围 / month 月份 / year 年份 / datetime 日期时间 |
label | string | "''" | 表单标签(uni 端常用) |
placeholder | string | "''" | 占位文本;默认按 type 给出(请选择日期 / 开始日期 至 结束日期 等) |
disabled | boolean | false | 禁用 |
clearable | boolean | false | 可清空:有值时触发器显示清空按钮,点击清空并触发 clear |
min | string | "''" | 可选最小日期(含),格式 'YYYY-MM-DD' |
max | string | "''" | 可选最大日期(含),格式 'YYYY-MM-DD' |
firstDayOfWeek | number:'0' | '1' | 1 | 每周起始日:0 周日 / 1 周一 |
mode | string:'auto' | 'mobile' | 'desktop' | "auto" | 弹层呈现方式;uni 端固定为内联展开面板,保留该 prop 与 Web 端 API 对齐 |
shortcuts | { label: string; value: [string, string] }[] | "[]" | 范围快捷选项(仅 daterange),点击直接选中该范围并关闭面板 |
minuteStep | number | 30 | 分钟步长(仅 datetime) |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
update:modelValue | string | [string, string] | null | 值变化时触发,用于 v-model |
change | string | [string, string] | null | 值变化时触发(选中日期、切换时间、清空) |
clear | void | 点击清空按钮时触发 |
示例
基础日期
vue
<DatePicker v-model="d1" label="日期" />日期时间(分钟步长 15)
vue
<DatePicker v-model="d2" type="datetime" label="会议时间" :minute-step="15" />日期范围 + 快捷选项
vue
<DatePicker v-model="dr1" type="daterange" label="入住时段" :shortcuts="dateShortcuts" />月份选择
vue
<DatePicker v-model="d3" type="month" label="月份" />年份选择
vue
<DatePicker v-model="d4" type="year" label="年份" />可清空与可选范围
vue
<DatePicker v-model="d5" label="限制范围" clearable min="2026-08-10" max="2026-09-10" />禁用
vue
<DatePicker v-model="d6" label="禁用" disabled />