日历

日历由一个分组元素组成，该元素包含一个或多个日期网格（例如月份），以及用于在日期范围之间导航的上一个和下一个按钮。每个日历网格由包含按钮元素的单元格组成，可以按下这些按钮元素并使用箭头键导航以选择日期。

安装

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

导入

用法

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

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

禁用

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

只读

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

受控

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

最小日期值

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

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

最大日期值

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

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

不可用日期

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

受控的聚焦值

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

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

无效日期

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

带月份和年份选择器

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

国际日历

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

可见月份

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

页面行为

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

预设

以下示例演示如何自定义 topContent 和 bottomContent 以具有一些预设值。

插槽

• base: Calendar 包装器，它处理对齐、放置和整体外观。
• 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

Calendar 属性

Calendar 事件

类型

支持的日历