日期范围选择器 (Range Calendar)

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

安装 (Installation)

上面的命令仅用于单独安装。如果已全局安装 (The above command is for individual installation only. You may skip this step if) @heroui/react，则可以跳过此步骤 (is already installed globally)。

导入 (Import)

用法 (Usage)

默认情况下，日期范围选择器 (A RangeCalendar) 没有选择任何日期。可以使用 defaultValue 属性为日期范围选择器提供初始的非受控值。或者，可以使用 value 属性提供受控值。(A RangeCalendar has no selection by default. An initial, uncontrolled value can be provided to the RangeCalendar using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.)

日期值 (Date values) 使用 @internationalized/date 包中的对象提供。(are provided using objects in the @internationalized/date package.) 该库处理跨日历、时区和其他本地化问题的正确的国际日期操作。(This library handles correct international date manipulation across calendars, time zones, and other localization concerns.)

禁用 (Disabled)

isDisabled 布尔属性使日历 (Calendar) 处于禁用状态。(boolean prop makes the Calendar disabled.) 单元格 (Cells) 无法聚焦或选择。(cannot be focused or selected.)

只读 (Read Only)

isReadOnly 布尔属性使日历 (Calendar) 的值不可变。(boolean prop makes the Calendar's value immutable.) 与 isDisabled 不同，日历 (Calendar) 仍然可以聚焦。(Unlike isDisabled, the Calendar remains focusable.)

受控 (Controlled)

默认情况下，日历 (A Calendar) 没有选择任何日期。可以使用 defaultValue 属性为日历 (Calendar) 提供初始的非受控值。或者，可以使用 value 属性提供受控值。(A Calendar has no selection by default. An initial, uncontrolled value can be provided to the Calendar using the defaultValue prop. Alternatively, a controlled value can be provided using the value prop.)

最小日期值 (Min Date Value)

默认情况下，日历 (By default, Calendar) 允许选择任何日期。minValue 也可用于阻止用户选择特定范围之外的日期。(allows selecting any date. The minValue can also be used to prevent the user from selecting dates outside a certain range.)

此示例仅接受今天的日期之后的日期。(This example only accepts dates after today.)

最大日期值 (Max Date Value)

默认情况下，日历 (By default, Calendar) 允许选择任何日期。maxValue 也可用于阻止用户选择特定范围之外的日期。(allows selecting any date. The maxValue can also be used to prevent the user from selecting dates outside a certain range.)

此示例仅接受今天的日期之前的日期。(This example only accepts dates before today.)

不可用日期 (Unavailable Dates)

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

非连续范围

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

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

受控的焦点值

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

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

无效日期

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

带有月份和年份选择器

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

国际日历

日历支持选择世界各地使用的多种日历系统中的日期，包括公历、希伯来历、印度历、伊斯兰历、佛教历等等。日期会自动以用户区域设置的相应日历系统显示。可以使用 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 属性

RangeCalendar 事件

支持的日历