109k
新建

日历

上一个下一个

一种允许用户选择日期或日期范围的日历组件。

Radix UIBase UI
Radix UI - shadcn/ui 组件库
2026年3月
"use client"

import * as React from "react"

安装

pnpm dlx shadcn@latest add calendar

用法

import { Calendar } from "@/components/ui/calendar"
const [date, setDate] = React.useState<Date | undefined>(new Date())
 
return (
  <Calendar
    mode="single"
    selected={date}
    onSelect={setDate}
    className="rounded-lg border"
  />
)

欲了解更多信息，请参阅 React DayPicker 文档。

关于

Calendar 组件构建于 React DayPicker 之上。

日期选择器

你可以使用 <Calendar> 组件来构建日期选择器。更多信息请参阅 日期选择器 (Date Picker) 页面。

波斯历 / 回历 / Jalali 日历

若要使用波斯历，请编辑 components/ui/calendar.tsx，将 react-day-picker 替换为 react-day-picker/persian。

- import { DayPicker } from "react-day-picker"
+ import { DayPicker } from "react-day-picker/persian"
Khordad 1404
"use client"

import * as React from "react"

所选日期（含时区）

Calendar 组件接受 timeZone 属性，以确保日期在用户的本地时区中显示和选择。

export function CalendarWithTimezone() {
  const [date, setDate] = React.useState<Date | undefined>(undefined)
  const [timeZone, setTimeZone] = React.useState<string | undefined>(undefined)
 
  React.useEffect(() => {
    setTimeZone(Intl.DateTimeFormat().resolvedOptions().timeZone)
  }, [])
 
  return (
    <Calendar
      mode="single"
      selected={date}
      onSelect={setDate}
      timeZone={timeZone}
    />
  )
}

注意： 如果您发现所选日期存在偏移（例如，选择 20 号却高亮了 19 号），请确保 timeZone 属性已设置为用户的本地时区。

为何采用客户端检测？ 时区是通过 Intl.DateTimeFormat().resolvedOptions().timeZone 在 useEffect 中检测到的，以确保与服务端渲染 (SSR) 的兼容性。在渲染期间检测时区会导致水合 (hydration) 不匹配，因为服务器和客户端可能处于不同的时区。

示例

基础用法

一个基础日历组件。我们使用了 className="rounded-lg border" 来设置日历样式。

2026年3月
"use client"

import { Calendar } from "@/components/ui/calendar"

范围日历 (Range Calendar)

使用 mode="range" 属性来启用范围选择。

2026年1月
2026年2月
"use client"

import * as React from "react"

月份和年份选择器

使用 captionLayout="dropdown" 来显示月份和年份的下拉菜单。

2026年3月
"use client"

import { Calendar } from "@/components/ui/calendar"

预设

2026年3月
"use client"

import * as React from "react"

日期与时间选择器

2026年3月
"use client"

import * as React from "react"

已预订日期

2026年2月
"use client"

import * as React from "react"

自定义单元格大小

2026年12月
"use client"

import * as React from "react"

您可以使用 --cell-size CSS 变量自定义日历单元格的大小。您也可以通过使用针对断点的值使其具备响应式特性。

<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  className="rounded-lg border [--cell-size:--spacing(11)] md:[--cell-size:--spacing(12)]"
/>

或者使用固定值

<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  className="rounded-lg border [--cell-size:2.75rem] md:[--cell-size:3rem]"
/>

周数

使用 showWeekNumber 来显示周数。

2026年2月
06
07
08
09
"use client"

import * as React from "react"

RTL (从右至左)

要在 shadcn/ui 中启用 RTL 支持，请参阅 RTL 配置指南。

另请参阅 回历指南 以了解如何启用波斯历/回历/Jalali 日历。

2026年3月
"use client"

import * as React from "react"

当使用 RTL（从右向左）布局时，请从 react-day-picker/locale 导入 locale，并将 locale 和 dir 属性传递给 Calendar 组件。

import { arSA } from "react-day-picker/locale"
 
;<Calendar
  mode="single"
  selected={date}
  onSelect={setDate}
  locale={arSA}
  dir="rtl"
/>

API 参考

请参阅 React DayPicker 文档，获取关于 Calendar 组件的更多信息。

更新日志

RTL 支持

如果您是从 Calendar 组件的旧版本升级而来，您需要执行以下更新以支持区域设置 (locale)：

导入 Locale 类型。

将 Locale 添加到您从 react-day-picker 的导入中。

  import {
    DayPicker,
    getDefaultClassNames,
    type DayButton,
+   type Locale,
  } from "react-day-picker"

为 Calendar 组件添加 locale 属性。

将 locale 属性添加到组件的 props 中。

  function Calendar({
    className,
    classNames,
    showOutsideDays = true,
    captionLayout = "label",
    buttonVariant = "ghost",
+   locale,
    formatters,
    components,
    ...props
  }: React.ComponentProps<typeof DayPicker> & {
    buttonVariant?: React.ComponentProps<typeof Button>["variant"]
  }) {

将 locale 传递给 DayPicker。

将 locale 属性传递给 DayPicker 组件。

    <DayPicker
      showOutsideDays={showOutsideDays}
      className={cn(...)}
      captionLayout={captionLayout}
+     locale={locale}
      formatters={{
        formatMonthDropdown: (date) =>
-         date.toLocaleString("default", { month: "short" }),
+         date.toLocaleString(locale?.code, { month: "short" }),
        ...formatters,
      }}

更新 CalendarDayButton 以接受 locale。

更新 CalendarDayButton 组件签名并传递 locale。

  function CalendarDayButton({
    className,
    day,
    modifiers,
+   locale,
    ...props
- }: React.ComponentProps<typeof DayButton>) {
+ }: React.ComponentProps<typeof DayButton> & { locale?: Partial<Locale> }) {

更新 CalendarDayButton 中的日期格式化方式。

在日期格式化中使用 locale?.code。

    <Button
      variant="ghost"
      size="icon"
-     data-day={day.date.toLocaleDateString()}
+     data-day={day.date.toLocaleDateString(locale?.code)}
      ...
    />

将 locale 传递给 DayButton 组件。

更新 DayButton 组件的调用，以传递 locale 属性。

      components={{
        ...
-       DayButton: CalendarDayButton,
+       DayButton: ({ ...props }) => (
+         <CalendarDayButton locale={locale} {...props} />
+       ),
        ...
      }}

更新 RTL 感知 CSS 类。

用逻辑属性替换方向性 CSS 类，以获得更好的 RTL 支持。

  // In the day classNames:
- [&:last-child[data-selected=true]_button]:rounded-r-(--cell-radius)
+ [&:last-child[data-selected=true]_button]:rounded-e-(--cell-radius)
- [&:nth-child(2)[data-selected=true]_button]:rounded-l-(--cell-radius)
+ [&:nth-child(2)[data-selected=true]_button]:rounded-s-(--cell-radius)
- [&:first-child[data-selected=true]_button]:rounded-l-(--cell-radius)
+ [&:first-child[data-selected=true]_button]:rounded-s-(--cell-radius)
 
  // In range_start classNames:
- rounded-l-(--cell-radius) ... after:right-0
+ rounded-s-(--cell-radius) ... after:end-0
 
  // In range_end classNames:
- rounded-r-(--cell-radius) ... after:left-0
+ rounded-e-(--cell-radius) ... after:start-0
 
  // In CalendarDayButton className:
- data-[range-end=true]:rounded-r-(--cell-radius)
+ data-[range-end=true]:rounded-e-(--cell-radius)
- data-[range-start=true]:rounded-l-(--cell-radius)
+ data-[range-start=true]:rounded-s-(--cell-radius)

应用这些更改后，您可以使用 locale 属性来提供特定于区域设置的格式。

import { enUS } from "react-day-picker/locale"
 
;<Calendar mode="single" selected={date} onSelect={setDate} locale={enUS} />