Calendar 日历

按月展示日期，常用于"日程 / 任务 / 排班"场景。

何时使用

• 单选某一天作为业务输入。
• 自定义每天的 cell，叠加业务标记（如待办数量、状态徽标）。

基本使用

v-model 默认绑定 YYYY-MM-DD 字符串，点击单元格切换选中日。

监听变化

change 事件返回新选中的日期，类型随 valueFormat（默认 'string'）。

只读模式

read-only 让用户无法点击切换，常用于"展示一份排期表"。

自定义 header

#header 插槽接收作用域对象 { value, currentMonth, setDate, changeMonth }，slot 内可直接调用月份切换 API，无需从外部维护状态。

字段	类型	说明
value	string	当前选中日期（YYYY-MM-DD）
currentMonth	string	当前展示月份（YYYY-MM）
setDate	(date: string) => void	跳转到任意 YYYY-MM-DD
changeMonth	(direction: 'lastMonth' | 'nextMonth') => void	上下月切换

自定义日期 cell

#dateCell 插槽接收 { isSelected, date, day }，可在每一天上叠加业务标记。

选中信息回显

把 dateCell 的 isSelected 拿来显示"已选 / 未选"提示。

valueFormat='string'（默认）

字符串协议，便于 JSON 序列化和路由参数透传。

valueFormat='date'

输出原生 Date，便于与既有日期 API 互操作。

valueFormat='number' timestamp

毫秒级 timestamp，便于直接落库。

自定义 format

format 同时控制输入解析与字符串输出。

Dayjs 实例输入

直接传 dayjs() 实例做初始化，组件内部统一转 dayjs 处理。

空值初始化

null 时回退到当天高亮。

周末高亮

用 dateCell slot + dayjs 算出 dayOfWeek，给周六周日加视觉权重。

双月对照

并列两个 Calendar 浏览跨月范围。

API

Props

参数	类型	默认值	说明
modelValue	string | number | Date | Dayjs | null	--	选中日期（v-model）；null 回退到今天
format	string	'YYYY-MM-DD'	字符串输入解析模板 + valueFormat='string' 时的输出模板（dayjs format token）
valueFormat	'string' | 'date' | 'number'	'string'	v-model 输出协议：字符串 / 原生 Date / 毫秒级 timestamp
readOnly	boolean	false	只读模式
classNames	{ root?, header?, body?, cell? }	--	语义化 DOM className 注入
styles	{ root?, header?, body?, cell? }	--	语义化 DOM style 注入

Events

事件	回调签名	说明
change	(value: string | Date | number | null)	选中日期变化；类型随 valueFormat

Slots

名称	说明
header	自定义日历头部，作用域 { value, currentMonth, setDate, changeMonth }（详见上方 demo）
dateCell	自定义日期 cell，参数 { isSelected, date, day }：是否选中 / 完整日期串 / 单元日号