CUI

Appearance

cuixingjian
886
4.1m

DateRangePicker 日期范围选择器 ​

同时选择开始和结束日期，支持日期与日期时间范围。

基础用法 ​

使用 v-model 绑定 [开始, 结束] 数组，默认格式为 YYYY-MM-DD。

日期+时间范围（showTime） ​

在日期范围下开启 showTime，开始时间默认为 00:00:00，结束时间默认为 23:59:59。

尺寸 ​

通过 size 控制输入框尺寸：small、default、large。

vue
<c-date-range-picker v-model="range1" size="small" />
<c-date-range-picker v-model="range1" />
<c-date-range-picker v-model="range1" size="large" />

自定义显示格式（format） ​

可通过 format 自定义显示格式。在 showTime 下，常用为 YYYY-MM-DD HH:mm 或仅日期 YYYY/MM/DD 等。

vue
<c-date-range-picker v-model="range2" :show-time="true" format="YYYY-MM-DD HH:mm" />
<c-date-range-picker v-model="range1" format="YYYY/MM/DD" />

值类型与分隔符 ​

  • v-model 接收并返回 [string | Date | null, string | Date | null]。
  • 默认输出为字符串形式；若你传入 Date，组件会内部格式化用于展示。
  • 输入框显示时，使用 valueSeparator 作为中间分隔，默认 至。
vue
<c-date-range-picker v-model="range1" value-separator=" ~ " />

禁用规则与范围约束 ​

  • 你可以通过 disabledDate(date) 禁用统一的不可选日期（如过去日期或非工作日）。
  • 组件本身内置范围约束：
    • 选择开始日期时，不允许晚于已选结束日期。
    • 选择结束日期时，不允许早于已选开始日期。

示例：仅允许今天及之后的日期

vue
<script setup lang="ts">
const disablePast = (d: Date) => {
  const today = new Date()
  today.setHours(0, 0, 0, 0)
  return d.getTime() < today.getTime()
}
</script>
<template>
  <c-date-range-picker v-model="range1" :disabled-date="disablePast" />
</template>

交互说明（showTime） ​

  • 开启 showTime 后，每侧显示三列时分秒，并提供“此刻”。
  • 只有在右侧点击“确定”后，才会提交整个范围。
  • 若只选一侧或时间未完整选择（时/分/秒缺失），“确定”会禁用。

事件示例 ​

vue
<script setup lang="ts">
function onChange(v: [string | Date | null, string | Date | null]) {
  console.log('range changed:', v)
}
</script>
<template>
  <c-date-range-picker v-model="range1" @change="onChange" @openChange="(o)=>console.log('open:', o)" />
</template>

Props ​

属性名说明类型默认值
modelValue绑定值（[开始, 结束]，字符串或 Date）[DateLike, DateLike][null, null]
format显示格式（默认随 showTime 自动匹配）stringYYYY-MM-DD / + HH:mm:ss
showTime开启时间列（分别选择开始/结束时间）booleanfalse
placeholder输入框占位文本string选择日期范围
startPlaceholder开始占位文本string开始日期
endPlaceholder结束占位文本string结束日期
disabled是否禁用booleanfalse
clearable是否可清除booleantrue
size尺寸'small' | 'default' | 'large'default
disabledDate禁用某些日期的函数(date: Date) => booleanundefined
popperMatchWidth弹层是否与输入框同宽booleantrue
valueSeparator输入框范围分隔符string至

事件 ​

事件名说明参数类型
update:modelValue选中值变化（v-model）[DateLike, DateLike]
change选中值变化（同上）[DateLike, DateLike]
openChange面板展开/收起变化boolean