跳到主要内容

DatePicker 日期选择器 ​

uni-appH5微信小程序App

跨端日期选择器:触发器 + 内联面板,支持单日 / 日期范围 / 月份 / 年份 / 日期时间五种类型,含农历无关的公历日历网格、范围快捷选项、分钟步长、清空与可选范围限制。

何时使用 ​

需要用户选择某一天、一段日期范围、某月、某年或某个日期时间:预约、筛选日期、出差起止、报表周期、财年统计等。

何时不使用 ​

只需要时间(不带日期)时用 TimePicker;整月视图展示日程/农历用 Calendar。

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
DatePicker 日期选择器 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelValuestring | [string, string] | nullnull绑定值:date 为 'YYYY-MM-DD';daterange 为 [开始, 结束];month 为 'YYYY-MM';year 为 'YYYY';datetime 为 'YYYY-MM-DD HH:mm'
typestring:'date' | 'daterange' | 'month' | 'year' | 'datetime'"date"选择类型:date 单日 / daterange 日期范围 / month 月份 / year 年份 / datetime 日期时间
labelstring"''"表单标签(uni 端常用)
placeholderstring"''"占位文本;默认按 type 给出(请选择日期 / 开始日期 至 结束日期 等)
disabledbooleanfalse禁用
clearablebooleanfalse可清空:有值时触发器显示清空按钮,点击清空并触发 clear
minstring"''"可选最小日期(含),格式 'YYYY-MM-DD'
maxstring"''"可选最大日期(含),格式 'YYYY-MM-DD'
firstDayOfWeeknumber:'0' | '1'1每周起始日:0 周日 / 1 周一
modestring:'auto' | 'mobile' | 'desktop'"auto"弹层呈现方式;uni 端固定为内联展开面板,保留该 prop 与 Web 端 API 对齐
shortcuts{ label: string; value: [string, string] }[]"[]"范围快捷选项(仅 daterange),点击直接选中该范围并关闭面板
minuteStepnumber30分钟步长(仅 datetime)

Events ​

名称载荷说明
update:modelValuestring | [string, string] | null值变化时触发,用于 v-model
changestring | [string, string] | null值变化时触发(选中日期、切换时间、清空)
clearvoid点击清空按钮时触发

示例 ​

基础日期 ​

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 />