跳到主要内容

Calendar 日历Calendar · RangeCalendar

直接摆在页面上的月历：选一天用 Calendar，选一段用 RangeCalendar。空间紧张、希望平时只占一行时，用包了一层浮层的 DatePicker / DateRangePicker。

基本用法

默认显示今天所在的月份，一周从周一开始。上下月的日期也显示出来并且可以点，点了会翻到那个月。示例里用 today 把“今天”固定在 2026-10-13，方便对照。

2026年10月
星期一星期二星期三星期四星期五星期六星期日

限制可选日期

min / max 限定范围（含两端），isDateDisabled 逐天判断。不可选的日期置灰，键盘可以经过但不能选中。

2026年10月
星期一星期二星期三星期四星期五星期六星期日
2026年10月
星期一星期二星期三星期四星期五星期六星期日

周起始日、语言与禁用

weekStartsOn 为 0 时从周日开始。locale 决定月份标题、星期名和读屏文字的语言。

2026年10月
星期日星期一星期二星期三星期四星期五星期六
October 2026
MondayTuesdayWednesdayThursdayFridaySaturdaySunday
2026年10月
星期一星期二星期三星期四星期五星期六星期日

受控用法

选中的日期（value）和正在显示的月份（month）是两份独立的状态，都可以受控。从外部改 value 不会自动翻月，需要时一并设置 month。

2026年10月
星期一星期二星期三星期四星期五星期六星期日
已选：2026-10-20 · 显示月份：2026 年 10 月

范围日历

RangeCalendar 第一次点定起点，第二次点定终点（点在起点之前会自动对调）；只定了起点时，指针划过的日期会预览这一段。已有完整范围时再点，重新开始选。

受控

2026年10月
星期一星期二星期三星期四星期五星期六星期日
2026-10-12 至 2026-10-16 · 共 4 晚

非受控，带限制

2026年10月
星期一星期二星期三星期四星期五星期六星期日

API

Calendar

属性类型默认值说明
valueDate | null—选中的日期（受控）。只按本地时区的“天”计算，不带时间。
defaultValueDate | nullnull初始选中的日期（非受控）。
onChange(date: Date) => void—选了一天时触发。
monthDate—当前显示的月份（受控），取其中任意一天。
defaultMonthDate选中日期或今天所在的月初始显示的月份。
onMonthChange(month: Date) => void—翻月时触发。
min / maxDate—可选的最早 / 最晚日期（含）。
isDateDisabled(date: Date) => boolean—返回 true 的日期不可选。
weekStartsOn0 | 1 | 2 | 3 | 4 | 5 | 61一周从星期几开始：0 = 周日，1 = 周一。
localestring'zh-CN'月份标题、星期名和读屏文字的语言。
todayDate系统日期“今天”是哪天。
autoFocusboolean—挂载时把焦点放到当前日期上。
disabledboolean—整体禁用。

RangeCalendar

属性类型默认值说明
value{ start: Date | null; end: Date | null }—选中的范围（受控）。只定了起点时 end 为 null。
defaultValueDateRange{ start: null, end: null }初始范围（非受控）。
onChange(range: DateRange) => void—每次点选都触发：先是只有起点，再是完整范围。
其余——同 Calendar。

工具函数

属性类型默认值说明
formatISODate(date: Date) => string—格式化成 2026-10-13。
parseISODate(text: string) => Date | null—解析 2026-10-13、2026/10/13、2026.10.13、2026年10月13日；不合法返回 null。

无障碍

  • 日期网格是 role="grid"，名称取月份标题（或 aria-label）；每一天是格子里的按钮，名称是完整日期（“2026年10月13日星期二，今天”），今天带 aria-current="date"。
  • 整个网格只有一个 Tab 停靠点（选中的日期，否则是今天）。← → 前后一天，↑ ↓ 前后一周，Home / End 到本周首尾，PageUp / PageDown 前后一个月，加 Shift 前后一年；跨月时自动翻页。Enter / Space 选中。
  • “上个月 / 下个月”是带名称的图标按钮；月份标题是 aria-live，翻月后会播报。
  • 不可选的日期是 aria-disabled：键盘仍能经过（方便数日子），但不能选中。
  • 今天用一个小圆点标记，选中用实心底色，范围用连续的底色，都不只靠颜色深浅。