Reka UI logoReka UI 中文文档
backdrop
Examples
组件

日历

Alpha
显示日期和星期，便于进行与日期相关的交互操作。
October 2024
29
30
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
31
1
2
3
4
5
6
7
8
9
Event Date, October 2024

功能特性

  • 完整的键盘导航
  • 支持受控与非受控模式
  • 焦点管理完善
  • 本地化支持
  • 高度可组合

前言

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

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

安装

安装日期包。

sh
$ npm add @internationalized/date

从命令行安装该组件。

sh
$ npm add reka-ui

结构剖析

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

vue
<script setup>
import {
  CalendarCell,
  CalendarCellTrigger,
  CalendarGrid,
  CalendarGridBody,
  CalendarGridHead,
  CalendarGridRow,
  CalendarHeadCell,
  CalendarHeader,
  CalendarHeading,
  CalendarNext,
  CalendarPrev,
  CalendarRoot,
} from 'reka-ui'
</script>

<template>
  <CalendarRoot>
    <CalendarHeader>
      <CalendarPrev />
      <CalendarHeading />
      <CalendarNext />
    </CalendarHeader>
    <CalendarGrid>
      <CalendarGridHead>
        <CalendarGridRow>
          <CalendarHeadCell />
        </CalendarGridRow>
      </CalendarGridHead>
      <CalendarGridBody>
        <CalendarGridRow>
          <CalendarCell>
            <CalendarCellTrigger />
          </CalendarCell>
        </CalendarGridRow>
      </CalendarGridBody>
    </CalendarGrid>
  </CalendarRoot>
</template>

API 参考

Root

包含日历的所有部分

PropDefaultType
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
DateValue

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 the calendar is disabled

disableDaysOutsideCurrentView
false
boolean

Whether or not to disable days outside the current view.

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

isDateUnavailable
Matcher

A function that returns whether or not a date is unavailable

locale
string

The locale to use for formatting dates

maxValue
DateValue

The maximum date that can be selected

minValue
DateValue

The minimum date that can be selected

modelValue
DateValue | DateValue[]

The controlled checked state of the calendar

multiple
false
boolean

Whether multiple dates can be selected

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

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 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

EmitPayload
update:modelValue
[date: DateValue]

Event handler called whenever the model value changes

update:placeholder
[date: DateValue]

Event handler called whenever the placeholder value changes

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
DateValue | DateValue[] | undefined

The current date of the calendar

MethodsType
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

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

包含导航按钮和标题部分。

PropDefaultType
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

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

PropDefaultType
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 CalendarRoot.

Slots (default)Payload
disabled
boolean

Current disable state

Data AttributeValue
[data-disabled]禁用时存在

Next Button

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

PropDefaultType
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 CalendarRoot.

Slots (default)Payload
disabled
boolean

Current disable state

Data AttributeValue
[data-disabled]禁用时存在

Heading

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

PropDefaultType
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 AttributeValue
[data-disabled]禁用时存在

Grid

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

PropDefaultType
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 AttributeValue
[data-readonly]只读时存在
[data-disabled]禁用时存在

Grid Head

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

PropDefaultType
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

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

PropDefaultType
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

用于包裹网格行的容器。

PropDefaultType
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

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

PropDefaultType
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

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

PropDefaultType
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

The date value for the cell

Data AttributeValue
[data-disabled]禁用时存在

Cell Trigger

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

PropDefaultType
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

The date value provided to the cell trigger

month*
DateValue

The month in which the cell is rendered

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

Data AttributeValue
[data-selected]选中时存在
[data-value]日期的 ISO 字符串值。
[data-disabled]禁用时存在
[data-unavailable]不可用时存在
[data-today]为今天日期时存在
[data-outside-view]当日期位于其显示的当前月份之外时存在。
[data-outside-visible-view]当日期位于日历上可见的月份之外时存在。
[data-focused]获得焦点时存在

示例

支持年份递增的日历

此示例展示了一个允许递增年份的日历。

November 2025
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
Event Date, November 2025

支持区域设置和日历系统选择的日历

此示例展示了一些可用的区域设置以及日历系统的显示方式。

November 2025
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
Event Date, November 2025

支持滑动手势导航的日历

此组件演示了使用基于触摸的滑动手势进行直观的日历导航，提供了一种用户友好的方式来浏览月份。

January 2023
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
31
1
2
3
4
5
6
7
8
9
10
11
Event Date, January 2023

显示周数的日历

此示例展示了用于显示周数的 CalendarWeek 组件的用法。

November 2025
43
44
45
46
47
48
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
Event Date, November 2025

无障碍访问

键盘交互

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