日历

"use client"

import * as React from "react"

安装

🌐 Installation

pnpmnpmyarnbun
pnpm dlx shadcn@latest add calendar
Copy

用法

🌐 Usage

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

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

有关更多信息，请参阅 React DayPicker 文档。

🌐 See the React DayPicker documentation for more information.

关于

🌐 About

Calendar 组件是建立在 React DayPicker 之上的。

🌐 The Calendar component is built on top of React DayPicker.

日期选择器

🌐 Date Picker

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

🌐 You can use the <Calendar> component to build a date picker. See the Date Picker page for more information.

波斯历 / 伊斯兰历 / 贾拉里历

🌐 Persian / Hijri / Jalali Calendar

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

🌐 To use the Persian calendar, edit components/ui/calendar.tsx and replace react-day-picker with react-day-picker/persian.

Copy- import { DayPicker } from "react-day-picker"
+ import { DayPicker } from "react-day-picker/persian"

"use client"

import * as React from "react"

所选日期（含时区）

🌐 Selected Date (With TimeZone)

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

🌐 The Calendar component accepts a timeZone prop to ensure dates are displayed and selected in the user's local timezone.

Copyexport 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 内检测的，以确保与服务器端渲染兼容。在渲染期间检测时区会导致水合不匹配，因为服务器和客户端可能在不同的时区。

示例

🌐 Examples

基础

🌐 Basic

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

🌐 A basic calendar component. We used className="rounded-lg border" to style the calendar.

"use client"

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

射程日历

🌐 Range Calendar

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

🌐 Use the mode="range" prop to enable range selection.

"use client"

import * as React from "react"

月份和年份选择器

🌐 Month and Year Selector

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

🌐 Use captionLayout="dropdown" to show month and year dropdowns.

"use client"

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

预设

🌐 Presets

"use client"

import * as React from "react"

日期和时间选择器

🌐 Date and Time Picker

"use client"

import * as React from "react"

预订日期

🌐 Booked dates

"use client"

import * as React from "react"

自定义单元格大小

🌐 Custom Cell Size

"use client"

import * as React from "react"

你可以使用 --cell-size CSS 变量自定义日历单元格的大小。你还可以通过使用特定断点的值使其具有响应性：

🌐 You can customize the size of calendar cells using the --cell-size CSS variable. You can also make it responsive by using breakpoint-specific values:

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

或者使用固定值：

🌐 Or use fixed values:

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

周数

🌐 Week Numbers

使用 showWeekNumber 显示周数。

🌐 Use showWeekNumber to show week numbers.

"use client"

import * as React from "react"

从右到左

🌐 RTL

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

🌐 To enable RTL support in shadcn/ui, see the RTL configuration guide.

另请参阅 Hijri 指南 以启用波斯 / 希吉尔 / 贾拉利日历。

🌐 See also the Hijri Guide for enabling the Persian / Hijri / Jalali calendar.

"use client"

import * as React from "react"

使用 RTL 时，从 react-day-picker/locale 导入区域设置，并将 locale 和 dir 属性都传递给 Calendar 组件：

🌐 When using RTL, import the locale from react-day-picker/locale and pass both the locale and dir props to the Calendar component:

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

API参考

🌐 API Reference

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

🌐 See the React DayPicker documentation for more information on the Calendar component.

更新日志

🌐 Changelog

右到左支持

🌐 RTL Support

如果你正在从之前版本的 Calendar 组件升级，你需要应用以下更新以添加本地化支持：

🌐 If you're upgrading from a previous version of the Calendar component, you'll need to apply the following updates to add locale support:

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

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

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

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

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

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

Copy  // 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 属性来提供特定于语言环境的格式化：

🌐 After applying these changes, you can use the locale prop to provide locale-specific formatting:

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