Date Picker 日期选择

选择年、月、日或 ISO 周。granularity 约束 v-model、边界和 matcher 的类型；日模式使用分段输入，年、月、周通过弹层选择。

命令行安装

npx @loongship-kit/ui add date-picker

四种粒度

2026-08-12

年：2026月：2026-08日：2026-08-12周：2026-W33

查看代码

<script setup lang="ts">
import { CalendarDate } from '@internationalized/date'
import { shallowRef } from 'vue'
import {
  DatePicker,
  type MonthValue,
  type WeekValue,
  type YearValue
} from '@/components/loongship/date-picker'

const year = shallowRef<YearValue>({ year: 2026 })
const month = shallowRef<MonthValue>({ year: 2026, month: 8 })
const day = shallowRef<CalendarDate>(new CalendarDate(2026, 8, 12))
const week = shallowRef<WeekValue>({ weekYear: 2026, week: 33 })
</script>

<template>
  <DatePicker v-model="year" granularity="year" aria-label="选择年份" />
  <DatePicker v-model="month" granularity="month" aria-label="选择月份" />
  <DatePicker v-model="day" granularity="day" aria-label="选择日期" />
  <DatePicker v-model="week" granularity="week" aria-label="选择周" />
</template>

值、约束和接口边界

粒度	值类型	表单序列化
year	{ year: number }	2026
month	{ year: number; month: number }	2026-08
day	CalendarDate	2026-08-13
week	{ weekYear: number; week: number }	2026-W33

ISO 周规则

周固定采用 ISO 8601：周一至周日，第 1 周是包含 1 月 4 日的周。weekStartsOn 只影响日模式。

接口边界转换

minValue、maxValue、isValueDisabled 和 isValueUnavailable 使用当前粒度的值类型。需要传给日期接口时，使用导出的边界工具：

const id = week.value ? serializeDatePickerValue('week', week.value) : undefined
const bounds = week.value ? getDatePickerValueBounds('week', week.value) : undefined
// bounds.start / bounds.end 均为 CalendarDate

API

属性	类型	默认值	说明
granularity	'year' | 'month' | 'day' | 'week'	'day'	选择粒度并约束其他值类型
v-model	DatePickerValue<G> | null	-	当前值；清空发出 undefined
defaultValue	DatePickerValue<G>	-	非受控初值
defaultPlaceholder	DatePickerValue<G>	当前单位	初始面板位置
v-model:open	boolean	-	受控弹层状态
defaultOpen	boolean	false	非受控初始弹层状态
minValue	DatePickerValue<G>	-	最小包含式单位边界
maxValue	DatePickerValue<G>	-	最大包含式单位边界
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	DatePickerValue<G> | undefined	选择或清空时触发
update:open	boolean	弹层状态改变时触发
clear	-	点击清空按钮时触发

插槽

插槽	参数	说明
cell	{ value, label, disabled, selected, today, unavailable, outsideView?, outsideVisibleView? }	自定义单位内容