Calendar

Calendar 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 Calendar 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，Calendar 是一个完全通过 props 配置的单一组件：

1import { Calendar } from "@lenso/ui";2
3export default function App() {4  return <Calendar aria-label="Date" />;5}

在 v3 中，Calendar 改用带显式子组件的复合组件模式：

1import { Calendar } from "@lenso/ui";2
3export default function App() {4  return (5    <Calendar aria-label="Date">6      <Calendar.Header>7        <Calendar.Heading />8        <Calendar.NavButton slot="previous" />9        <Calendar.NavButton slot="next" />10      </Calendar.Header>11      <Calendar.Grid>12        <Calendar.GridHeader>13          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}14        </Calendar.GridHeader>15        <Calendar.GridBody>16          {(date) => <Calendar.Cell date={date} />}17        </Calendar.GridBody>18      </Calendar.Grid>19    </Calendar>20  );21}

主要变化

1. 组件结构

v2： 单一 Calendar 组件，所有布局都在内部处理
v3： 复合组件：Calendar.Header、Calendar.Heading、Calendar.NavButton、Calendar.Grid、Calendar.GridHeader、Calendar.GridBody、Calendar.HeaderCell、Calendar.Cell、Calendar.CellIndicator

2. 年份选择器

v2： 通过 showMonthAndYearPickers prop 提供内置月份 / 年份选择器
v3： 使用专用复合组件：Calendar.YearPickerTrigger、Calendar.YearPickerGrid、Calendar.YearPickerGridBody、Calendar.YearPickerCell

3. Prop 变更

v2 prop	v3 等效项	说明
`value`	`value`	保持一致
`defaultValue`	`defaultValue`	保持一致
`onChange`	`onChange`	保持一致
`focusedValue`	`focusedValue`	保持一致
`onFocusChange`	`onFocusChange`	保持一致
`minValue`	`minValue`	保持一致
`maxValue`	`maxValue`	保持一致
`isDateUnavailable`	`isDateUnavailable`	保持一致
`isDisabled`	`isDisabled`	保持一致
`isReadOnly`	`isReadOnly`	保持一致
`isInvalid`	`isInvalid`	保持一致
`visibleMonths`	`visibleDuration`	改为 `{months: number}` 对象
`showMonthAndYearPickers`	-	使用 `Calendar.YearPickerTrigger` 和 `Calendar.YearPickerGrid`
`onHeaderExpandedChange`	`onYearPickerOpenChange`	已重命名
`color`	-	已移除（请改用 Tailwind CSS）
`calendarWidth`	-	已移除（请改用 `className` 或 Tailwind CSS）
`weekdayStyle`	-	已移除
`pageBehavior`	`pageBehavior`	保持一致
`firstDayOfWeek`	-	改用 `I18nProvider` 的 locale
`hideDisabledDates`	-	已移除
`disableAnimation`	-	已移除
`topContent`	-	将自定义内容作为 `Calendar` children 放在 `Calendar.Grid` 之前
`bottomContent`	-	将自定义内容作为 `Calendar` children 放在 `Calendar.Grid` 之后
`classNames`	-	在各个复合组件上使用 `className`
`errorMessage`	-	已移除（请在外部处理校验）

4. color prop 已移除

v2： color prop 支持 default、primary、secondary、success、warning、danger
v3： 不再提供 color prop，请使用 Tailwind CSS 类设置单元格样式，或通过自定义 calendar.css 覆盖

迁移示例

基本日历

1import { Calendar } from "@lenso/ui";2import { today, getLocalTimeZone } from "@internationalized/date";3
4<Calendar5  aria-label="Date"6  defaultValue={today(getLocalTimeZone())}7/>

受控状态

1import { useState } from "react";2import { Calendar } from "@lenso/ui";3import { parseDate } from "@internationalized/date";4
5const [value, setValue] = useState(parseDate("2024-03-07"));6
7<Calendar8  aria-label="Date"9  value={value}10  onChange={setValue}11/>

月份和年份选择器

1<Calendar2  aria-label="Date"3  showMonthAndYearPickers4/>

多个月份

1<Calendar2  aria-label="Date"3  visibleMonths={2}4/>

不可用日期

1import { isWeekend } from "@internationalized/date";2import { useLocale } from "@react-aria/i18n";3
4const { locale } = useLocale();5
6<Calendar7  aria-label="Date"8  isDateUnavailable={(date) => isWeekend(date, locale)}9/>

顶部与底部内容

1<Calendar2  aria-label="Date"3  topContent={<p>Select a date</p>}4  bottomContent={5    <button onClick={() => setValue(today(getLocalTimeZone()))}>6      Today7    </button>8  }9/>

单元格指示器

1{/* v2 did not have a built-in cell indicator API */}

样式变化

v2：`classNames` prop

1<Calendar2  classNames={{3    base: "custom-base",4    prevButton: "custom-prev",5    nextButton: "custom-next",6    title: "custom-title",7    cell: "custom-cell",8    cellButton: "custom-cell-button",9  }}10/>

v3：直接使用 `className` prop

1<Calendar className="custom-base">2  <Calendar.Header>3    <Calendar.Heading className="custom-title" />4    <Calendar.NavButton slot="previous" className="custom-prev" />5    <Calendar.NavButton slot="next" className="custom-next" />6  </Calendar.Header>7  <Calendar.Grid>8    <Calendar.GridHeader>9      {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}10    </Calendar.GridHeader>11    <Calendar.GridBody>12      {(date) => <Calendar.Cell date={date} className="custom-cell" />}13    </Calendar.GridBody>14  </Calendar.Grid>15</Calendar>

组件结构

v3 Calendar 遵循以下结构：

1Calendar (Root)2  ├── [Custom top content]3  ├── Calendar.Header4  │   ├── Calendar.Heading (or Calendar.YearPickerTrigger)5  │   ├── Calendar.NavButton slot="previous"6  │   └── Calendar.NavButton slot="next"7  ├── Calendar.Grid (one per visible month)8  │   ├── Calendar.GridHeader9  │   │   └── Calendar.HeaderCell (render prop)10  │   └── Calendar.GridBody11  │       └── Calendar.Cell (render prop)12  │           └── Calendar.CellIndicator (optional)13  ├── Calendar.YearPickerGrid (optional)14  │   └── Calendar.YearPickerGridBody15  │       └── Calendar.YearPickerCell16  └── [Custom bottom content]

总结

组件结构：单一组件 → 带显式布局控制的复合组件
年份选择器：showMonthAndYearPickers prop → 专用的 Calendar.YearPickerTrigger 和 Calendar.YearPickerGrid 组件
多个月份：visibleMonths={n} → visibleDuration={{months: n}}，并使用多个带 offset 的 Calendar.Grid 组件
color 已移除：请改用 Tailwind CSS 类
顶部 / 底部内容：prop 已移除 → 直接将内容作为 children 放在 Calendar 内
单元格自定义：新增 Calendar.CellIndicator，且 Calendar.Cell 支持渲染 prop
样式：classNames prop → 各个复合组件上的 className
已移除 prop：calendarWidth、weekdayStyle、hideDisabledDates、disableAnimation —— 请使用 Tailwind CSS 或省略