范围日历

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

安装

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

导入

使用方法

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 个月。

页面行为

默认情况下，当按下“下一个”或“上一个”按钮时，分页将按 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 事件

支持的日历