Date Range Picker 日期范围选择

选择年、月、日或 ISO 周范围。第二次选择完成后发出 { start, end } 并默认关闭；清空发出 undefined。

命令行安装

npx @loongship-kit/ui add date-range-picker

四种范围

2026-08-10

—

2026-08-13

查看代码

<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'
import { DateRangePicker, type DateRangeValue } from '@/components/loongship/date-range-picker'

const yearRange = shallowRef<DateRangeValue<'year'>>({
  start: { year: 2024 },
  end: { year: 2026 }
})
const monthRange = shallowRef<DateRangeValue<'month'>>({
  start: { year: 2026, month: 6 },
  end: { year: 2026, month: 8 }
})
const dayRange = shallowRef<DateRangeValue<'day'>>({
  start: new CalendarDate(2026, 8, 10),
  end: new CalendarDate(2026, 8, 13)
})
const weekRange = shallowRef<DateRangeValue<'week'>>({
  start: { weekYear: 2026, week: 32 },
  end: { weekYear: 2026, week: 33 }
})
</script>

<template>
  <DateRangePicker v-model="yearRange" granularity="year" aria-label="年份范围" />
  <DateRangePicker v-model="monthRange" granularity="month" aria-label="月份范围" />
  <DateRangePicker v-model="dayRange" granularity="day" aria-label="日期范围" />
  <DateRangePicker v-model="weekRange" granularity="week" aria-label="周范围" />
</template>

范围规则

• minValue 和 maxValue 是包含式单位边界。
• maxRangeLength 按当前粒度包含式计数；同一年、同一月、同一天或同一周的长度均为 1。
• 第一次选择是方向未定的锚点，不会改变外部 v-model 或隐藏表单字段；输入框会显示该草稿与空缺端。
• 第二次选择早于第一次时，组件自动按时间顺序排列 start 和 end。
• 悬浮或键盘聚焦第二个候选单位时，面板会根据候选位于锚点之前或之后动态预览起止方向。
• 按 Escape、点击弹层外部、受控关闭弹层、切换粒度或外部值变化时，未完成草稿会被丢弃并恢复上次完整范围。
• 默认不能跨过 isValueUnavailable 返回 true 的单位；设置 allowNonContiguousRanges 后可以跨过。
• name 对应的隐藏字段格式为 start - end，两端分别使用 DatePicker 的标准序列化格式。

API

值契约

DateRangeValue<G> 为 { start: DatePickerValue<G>; end: DatePickerValue<G> }，只表示完整范围。未选择和清空均为 undefined，不使用空对象，也不会对外暴露仅有 start 的部分范围。

属性	类型	默认值	说明
granularity	'year' | 'month' | 'day' | 'week'	'day'	范围粒度
v-model	DateRangeValue<G> | null	-	当前范围
defaultValue	DateRangeValue<G>	-	非受控初值
defaultPlaceholder	DatePickerValue<G>	当前单位	初始面板位置
v-model:open	boolean	-	受控弹层状态
defaultOpen	boolean	false	非受控初始弹层状态
minValue	DatePickerValue<G>	-	最小包含式单位边界
maxValue	DatePickerValue<G>	-	最大包含式单位边界
maxRangeLength	number	-	最大包含式单位数
allowNonContiguousRanges	boolean	false	是否允许跨越不可用单位
isValueDisabled	(value: DatePickerValue<G>) => boolean	-	禁用单位
isValueUnavailable	(value: DatePickerValue<G>) => boolean	-	标记不可用单位
locale	string	'zh-CN'	本地化语言
weekStartsOn	0...6	1	日模式的周首日
weekdayFormat	'narrow' | 'short' | 'long'	'narrow'	星期标题格式
fixedWeeks	boolean	true	日历是否固定显示六周
numberOfMonths	1 | 2	1	日模式同时显示的月份数
yearsPerPage	number	10	年面板每页数量
clearable	boolean	true	是否显示清空按钮
closeOnSelect	boolean	true	完成选择后是否关闭弹层
disabled	boolean	false	禁用状态
readonly	boolean	false	只读状态
required	boolean	false	必填状态
id	string	-	表单元素 ID
name	string	-	字段名
panelLabel	string	按粒度生成	面板可访问名称
previousLabel	string	按粒度生成	上一页可访问名称
nextLabel	string	按粒度生成	下一页可访问名称
clearLabel	string	按粒度生成	清空按钮可访问名称
class	ClassValue	-	字段类名
contentClass	ClassValue	-	弹层类名

事件

事件	参数	说明
update:modelValue	DateRangeValue<G> | undefined	完成范围或清空时触发
update:open	boolean	弹层状态改变时触发
clear	-	点击清空按钮时触发

插槽

插槽	参数	说明
cell	单值状态及 highlighted、highlightedStart、highlightedEnd、selectionStart、selectionEnd	自定义范围单位内容；selection* 表示已提交端点，highlighted* 表示草稿预览端点
footer	{ modelValue, clear, close }	自定义面板底部