Range Calendar

范围日历由一个包含一个或多个日期网格（例如月份）的分组元素，以及用于时间导航的上一个和下一个按钮组成。每个日历网格由包含按钮元素的单元格组成，可以通过按下按钮或使用箭头键导航来选择日期范围。一旦选择了开始日期，用户可以使用键盘导航到另一个日期，或者通过悬停并点击它或按 Enter 键来提交选定的日期范围。

安装

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

导入

用法

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

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

禁用

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

只读

isReadOnly 布尔属性使日历的值不可变。与 isDisabled 不同，日历保持可聚焦。

受控

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

最小日期值

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

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

最大日期值

默认情况下，日历允许选择任何日期。maxValue 也可用于防止用户选择特定范围之外的日期。

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

不可用日期

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

非连续范围

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

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

受控聚焦值

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

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

无效日期

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

带月份和年份选择器

日历支持月份和年份选择器以进行快速选择。您可以通过将 showMonthAndYearPickers 设置为 true 来启用此功能。但是，如果 visibleMonths 设置为大于 1 的数字，此功能将被禁用。

国际日历

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

可见月份

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

自定义周起始日

默认情况下，一周的第一天根据当前区域设置自动设置。可以通过将 firstDayOfWeek 属性设置为 'sun'、'mon'、'tue'、'wed'、'thu'、'fri' 或 'sat' 来更改。

翻页行为

默认情况下，按下下一个或上一个按钮时，分页将按 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 属性

RangeCalendar 事件

支持的日历