范围日历

Alpha

提供一个专为选择日期范围而定制的日历视图。

View code

Event Date, November 2025

November 2025

S	M	T	W	T	F	S
26	27	28	29	30	31	1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30	1	2	3	4	5	6

功能特性

完整的键盘导航
可受控或非受控
焦点完全受控
本地化支持
高度可组合

前言

该组件依赖于 @internationalized/date 包，该包解决了在 JavaScript 中处理日期和时间时遇到的许多问题。

我们强烈建议阅读该包的文档以深入了解其工作原理，并且您需要在项目中安装它才能使用与日期相关的组件。

安装

安装日期包。

$ npm add @internationalized/date

从命令行安装该组件。

$ npm add reka-ui

结构剖析

导入所有部件并将它们组合在一起。

vue

<script setup>
import {
  RangeCalendarCell,
  RangeCalendarCellTrigger,
  RangeCalendarGrid,
  RangeCalendarGridBody,
  RangeCalendarGridHead,
  RangeCalendarGridRow,
  RangeCalendarHeadCell,
  RangeCalendarHeader,
  RangeCalendarHeading,
  RangeCalendarNext,
  RangeCalendarPrev,
  RangeCalendarRoot,
} from 'reka-ui'
</script>

<template>
  <RangeCalendarRoot>
    <RangeCalendarHeader>
      <RangeCalendarPrev />
      <RangeCalendarHeading />
      <RangeCalendarNext />
    </RangeCalendarHeader>
    <RangeCalendarGrid>
      <RangeCalendarGridHead>
        <RangeCalendarGridRow>
          <RangeCalendarHeadCell />
        </RangeCalendarGridRow>
      </RangeCalendarGridHead>
      <RangeCalendarGridBody>
        <RangeCalendarGridRow>
          <RangeCalendarCell>
            <RangeCalendarCellTrigger />
          </RangeCalendarCell>
        </RangeCalendarGridRow>
      </RangeCalendarGridBody>
    </RangeCalendarGrid>
  </RangeCalendarRoot>
</template>

API 参考

Root (根组件)

包含日历的所有部分。

Prop	Default	Type
`allowNonContiguousRanges`	`false`	`boolean` When combined with `isDateUnavailable`, determines whether non-contiguous ranges, i.e. ranges containing unavailable dates, may be selected.
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`calendarLabel`		`string` The accessible label for the calendar
`defaultPlaceholder`		`DateValue` The default placeholder date
`defaultValue`	`{ start: undefined, end: undefined }`	`DateRange` The default value for the calendar
`dir`		`'ltr' \| 'rtl'` The reading direction of the calendar when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.
`disabled`	`false`	`boolean` Whether or not the calendar is disabled
`disableDaysOutsideCurrentView`	`false`	`boolean` Whether or not to disable days outside the current view.
`fixedDate`		`'start' \| 'end'` Which part of the range should be fixed
`fixedWeeks`	`false`	`boolean` Whether or not to always display 6 weeks in the calendar
`initialFocus`	`false`	`boolean` If true, the calendar will focus the selected day, today, or the first day of the month depending on what is visible when the calendar is mounted
`isDateDisabled`		`Matcher` A function that returns whether or not a date is disabled
`isDateHighlightable`		`Matcher` A function that returns whether or not a date is hightable
`isDateUnavailable`		`Matcher` A function that returns whether or not a date is unavailable
`locale`		`string` The locale to use for formatting dates
`maximumDays`		`number` The maximum number of days that can be selected in a range
`maxValue`		`DateValue` The maximum date that can be selected
`minValue`		`DateValue` The minimum date that can be selected
`modelValue`		`DateRange \| null` The controlled checked state of the calendar. Can be bound as `v-model`.
`nextPage`		`((placeholder: DateValue) => DateValue)` A function that returns the next page of the calendar. It receives the current placeholder as an argument inside the component.
`numberOfMonths`	`1`	`number` The number of months to display at once
`pagedNavigation`	`false`	`boolean` This property causes the previous and next buttons to navigate by the number of months displayed at once, rather than one month
`placeholder`		`DateValue` The placeholder date, which is used to determine what month to display when no date is selected. This updates as the user navigates the calendar and can be used to programmatically control the calendar view
`preventDeselect`	`false`	`boolean` Whether or not to prevent the user from deselecting a date without selecting another date first
`prevPage`		`((placeholder: DateValue) => DateValue)` A function that returns the previous page of the calendar. It receives the current placeholder as an argument inside the component.
`readonly`	`false`	`boolean` Whether or not the calendar is readonly
`weekdayFormat`	`'narrow'`	`'narrow' \| 'short' \| 'long'` The format to use for the weekday strings provided via the weekdays slot prop
`weekStartsOn`	`0`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` The day of the week to start the calendar on

Emit	Payload
`update:modelValue`	`[date: DateRange]` Event handler called whenever the model value changes
`update:placeholder`	`[date: DateValue]` Event handler called whenever the placeholder value changes
`update:startValue`	`[date: DateValue]` Event handler called whenever the start value changes
`update:validModelValue`	`[date: DateRange]` Event handler called whenever there is a new validModel

Slots (default)	Payload
`date`	`DateValue` The current date of the placeholder
`grid`	`Grid<DateValue>[]` The grid of dates
`weekDays`	`string[]` The days of the week
`weekStartsOn`	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` The start of the week
`locale`	`string` The calendar locale
`fixedWeeks`	`boolean` Whether or not to always display 6 weeks in the calendar
`modelValue`	`DateRange` The current date range

Methods	Type
`isDateDisabled`	`Matcher` A function that returns whether or not a date is disabled
`isDateUnavailable`	`Matcher` A function that returns whether or not a date is unavailable
`isDateHighlightable`	`Matcher` A function that returns whether or not a date is hightable

Data Attribute	Value
`[data-readonly]`	只读时存在
`[data-disabled]`	禁用时存在
`[data-invalid]`	无效时存在

包含导航按钮和标题段。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Prev Button (上一个按钮)

日历导航按钮。根据当前日历视图，将日历向前导航一个月/一年/十年。

Data Attribute	Value
`[data-disabled]`	禁用时存在

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`prevPage`		`((placeholder: DateValue) => DateValue)` The function to be used for the prev page. Overwrites the `prevPage` function set on the `RangeCalendarRoot`.

Slots (default)	Payload
`disabled`	`boolean` Current disable state

Next Button (下一个按钮)

日历导航按钮。根据当前日历视图，将日历向后导航一个月/一年/十年。

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`nextPage`		`((placeholder: DateValue) => DateValue)` The function to be used for the next page. Overwrites the `nextPage` function set on the `RangeCalendarRoot`.

Slots (default)	Payload
`disabled`	`boolean` Current disable state

Data Attribute	Value
`[data-disabled]`	禁用时存在

Heading (标题)

用于显示当前月份和年份的标题。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Slots (default)	Payload
`headingValue`	`string` Current month and year

Data Attribute	Value
`[data-disabled]`	禁用时存在

Grid (网格)

用于包裹日历网格的容器。

Prop	Default	Type
`as`	`'table'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Data Attribute	Value
`[data-readonly]`	只读时存在
`[data-disabled]`	禁用时存在

Grid Head (网格头部)

用于包裹网格头部的容器。

Prop	Default	Type
`as`	`'thead'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Grid Body (网格主体)

用于包裹网格主体的容器。

Prop	Default	Type
`as`	`'tbody'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Grid Row (网格行)

用于包裹网格行的容器。

Prop	Default	Type
`as`	`'tr'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Head Cell (头部单元格)

用于包裹头部单元格的容器。用于显示星期几。

Prop	Default	Type
`as`	`'th'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.

Cell (单元格)

用于包裹日历单元格的容器。

Prop	Default	Type
`as`	`'td'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`date*`		`DateValue`

Data Attribute	Value
`[data-disabled]`	禁用时存在

Cell Trigger (单元格触发器)

用于显示单元格日期的可交互容器。单击它即可选择日期。

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`day*`		`DateValue`
`month*`		`DateValue`

Slots (default)	Payload
`dayValue`	`string` Current day
`disabled`	`boolean` Current disable state
`selected`	`boolean` Current selected state
`today`	`boolean` Current today state
`outsideView`	`boolean` Current outside view state
`outsideVisibleView`	`boolean` Current outside visible view state
`unavailable`	`boolean` Current unavailable state
`highlighted`	`boolean` Current highlighted state
`highlightedStart`	`boolean` Current highlighted start state
`highlightedEnd`	`boolean` Current highlighted end state
`selectionStart`	`boolean` Current selection start state
`selectionEnd`	`boolean` Current selection end state

Data Attribute	Value
`[data-selected]`	选中时存在
`[data-value]`	日期的 ISO 字符串值。
`[data-disabled]`	禁用时存在
`[data-unavailable]`	不可用时存在
`[data-today]`	为当天日期时存在
`[data-outside-view]`	当日期位于其显示的当前月份之外时存在。
`[data-outside-visible-view]`	当日期位于日历上可见的月份之外时存在。
`[data-selection-start]`	当日期是选择的开始时存在。
`[data-selection-end]`	当日期是选择的结束时存在。
`[data-highlighted]`	当日期在用户选择范围时被高亮显示时存在。
`[data-highlighted-start]`	当日期是用户高亮显示范围的开始时存在。
`[data-highlighted-end]`	当日期是用户高亮显示范围的结束时存在。
`[data-focused]`	获得焦点时存在

可访问性

键盘交互

Key	Description
`Tab`	当焦点移动到日历上时，聚焦到第一个导航按钮。
`Space`	当焦点位于 `CalendarNext` 或 `CalendarPrev` 上时，它将导航日历。否则，它将选择日期。
`Enter`	当焦点位于 `CalendarNext` 或 `CalendarPrev` 上时，它将导航日历。否则，它将选择日期。
`ArrowLeftArrowRightArrowUpArrowDown`	当焦点位于 `CalendarCellTrigger` 上时，它将导航日期，必要时更改月份/年份/年代。

S	M	T	W	T	F	S
26	27	28	29	30	31	1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30	1	2	3	4	5	6

S	M	T	W	T	F	S
26	27	28	29	30	31	1
2	3	4	5	6	7	8
9	10	11	12	13	14	15
16	17	18	19	20	21	22
23	24	25	26	27	28	29
30	1	2	3	4	5	6

范围日历 ​

功能特性 ​

前言 ​

安装 ​

结构剖析 ​

API 参考 ​

Root (根组件) ​

Header (头部) ​

Prev Button (上一个按钮) ​

Next Button (下一个按钮) ​

Heading (标题) ​

Grid (网格) ​

Grid Head (网格头部) ​

Grid Body (网格主体) ​

Grid Row (网格行) ​

Head Cell (头部单元格) ​

Cell (单元格) ​

Cell Trigger (单元格触发器) ​

可访问性 ​

键盘交互 ​