范围日历

范围日历由一个包含一个或多个日期网格（例如月份）的组合元素以及用于在时间轴上导航的上一个和下一个按钮组成。每个日历网格包含包含按钮元素的单元格，这些按钮元素可以被按下并使用箭头键导航以选择日期范围。选择开始日期后，用户可以使用键盘导航到另一个日期，或将鼠标悬停在该日期上，然后单击或按 Enter 键提交所选日期范围。

安装

npx nextui-cli@latest add calendar

以上命令仅用于单个安装。如果@nextui-org/react已全局安装，您可以跳过此步骤。

导入

用法

RangeCalendar 默认没有选择。可以使用 defaultValue 属性为 RangeCalendar 提供初始的、不受控的值。或者，可以使用 value 属性提供受控的值。

日期值使用 @internationalized/date 包中的对象提供。此库处理跨日历、时区和其他本地化问题进行正确的国际日期操作。

禁用

isDisabled 布尔属性使日历禁用。单元格无法聚焦或选择。

只读

The isReadOnly 布尔属性使日历的值不可变。与 isDisabled 不同，日历仍然可以聚焦。

受控

日历默认没有选择。可以使用 defaultValue 属性为日历提供初始的、不受控的值。或者，可以使用 value 属性提供受控的值。

最小日期值

默认情况下，日历允许选择任何日期。可以使用 minValue 来阻止用户选择特定范围之外的日期。

此示例仅接受今天之后的日期。

最大日期值

默认情况下，日历允许选择任何日期。 maxValue 也可以用来阻止用户选择超出某个范围的日期。

此示例仅接受今天之前的日期。

不可用日期

日历支持将某些日期标记为不可用。 这些日期仍然可以通过键盘获得焦点，以确保导航一致，但用户无法选择它们。 在此示例中，它们以红色显示。 isDateUnavailable 属性接受一个回调函数，该函数用于评估每个可见日期是否不可用。

非连续范围

allowsNonContiguousRanges 属性允许选择一个范围，即使中间有不可用的日期。onChange 事件中发出的值仍然是一个具有 start 和 end 属性的单个范围，但不可用的日期不会显示为选中状态。应用程序需要根据业务逻辑将完整的选中范围拆分成多个范围。

此示例阻止选择周末，但允许选择跨越多个星期的范围。

受控焦点值

日历会尽量避免用户选择无效日期。但是，如果根据应用程序逻辑，选择的日期无效，则可以设置 isInvalid 属性。这会提醒辅助技术用户选择无效，并且也可以用于样式化。此外，errorMessage 插槽可用于帮助用户解决问题。

默认情况下，日历首次挂载时，选定的日期会获得焦点。如果没有提供 value 或 defaultValue 属性，则当前日期会获得焦点。但是，日历支持使用 focusedValue 和 onFocusChange 属性来控制哪个日期获得焦点。这也决定了哪个月份可见。 defaultFocusedValue 属性允许在日历首次挂载时设置初始焦点日期，而无需控制它。

无效日期

此示例验证所选日期根据当前区域设置是工作日而不是周末。

国际日历

日历支持选择世界各地使用的多种日历系统中的日期，包括公历、希伯来历、印度历、伊斯兰历、佛教历等等。日期会自动以用户区域设置的适当日历系统显示。可以使用 Unicode 日历区域设置扩展 覆盖日历系统，该扩展传递给 Provider 组件。

可见月份

默认情况下，日历显示单个月份。 visibleMonths 属性允许一次显示最多 3 个月。

页面行为

默认情况下，当按下“下一个”或“上一个”按钮时，分页将根据 visibleMonths 值进行翻页。可以通过将 pageBehavior 设置为 single，将此行为更改为按单个月份翻页。

预设值

以下示例展示了如何自定义 topContent 和 bottomContent 以使用一些预设值。

插槽

• base: 日历包装器，它处理对齐、放置和整体外观。
• prevButton: 日历的上一页按钮。
• nextButton: 日历的下一页按钮。
• headerWrapper: 包裹选择器（月份/年份）。
• header: 标题元素。
• title: 可见日期范围的描述，用于日历标题。
• gridWrapper: 日历网格的包装器。
• grid: 日期网格元素（例如 <table>）。
• gridHeader: 日期网格标题元素（例如 <th>）。
• gridHeaderRow: 日期网格标题行元素（例如 <tr>）。
• gridHeaderCell: 日期网格标题单元格元素（例如 <td>）。
• gridBody: 日期网格主体元素（例如 <tbody>）。
• gridBodyRow: 日期网格主体行元素（例如 <tr>）。
• cell: 日期网格单元格元素（例如 <td>）。
• cellButton: 单元格内的按钮元素。
• pickerWrapper: 选择器的包装器。
• pickerMonthList: 月份列表选择器。
• pickerYearList: 年份列表选择器。
• pickerHighlight: 选择器中突出显示的项目。
• pickerItem: 选择器的项目。
• helperWrapper: 日历的辅助信息。
• errorMessage: 日历的错误信息。

数据属性

Calendar 在 CalendarCell 元素上具有以下属性。

• data-focused: 单元格是否处于焦点状态。
• data-hovered: 单元格是否当前被鼠标悬停。
• data-pressed: 单元格是否当前被按下。
• data-unavailable: 单元格是否不可用，根据日历的 isDateUnavailable 属性。不可用的日期仍然可以获得焦点，但用户无法选择它们。它们应该以视觉效果来表示它们不可用，例如不同的颜色或删除线。
• data-disabled: 单元格是否被禁用，根据日历的 minValue、maxValue 和 isDisabled 属性。
• data-focus-visible: 单元格是否处于键盘焦点状态。
• data-outside-visible-range: 该单元格是否在日历的可视范围内。
• data-outside-month: 该单元格是否在当前月份之外。
• data-selected: 该单元格是否被选中。
• data-selected-start: 该单元格是否为范围选择的第一个日期。
• data-selected-end: 该单元格是否为范围选择的最后一个日期。
• data-invalid: 该单元格是否属于无效选择。

无障碍性

• 一次显示一个或多个月，或自定义时间范围，用于周视图等用例。支持最小值和最大值、不可用日期和非连续选择。
• 支持全球使用的 13 种日历系统，包括公历、佛教历、伊斯兰历、波斯历等。还提供特定于区域设置的格式、数字系统和从右到左的支持。
• 可以使用键盘导航和选择日历单元格，并包含本地化的屏幕阅读器消息以宣布选择和可见日期范围何时更改。

API

RangeCalendar 属性

范围日历事件

支持的日历

/**
 * Supported react-aria i18n calendars.
 */
export type SupportedCalendars =
  | "buddhist"
  | "ethiopic"
  | "ethioaa"
  | "coptic"
  | "hebrew"
  | "indian"
  | "islamic-civil"
  | "islamic-tbla"
  | "islamic-umalqura"
  | "japanese"
  | "persian"
  | "roc"
  | "gregory";