日历

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

安装

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

导入

用法

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

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

禁用

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

只读

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

受控

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

最小日期值

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

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

最大日期值

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

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

不可用日期

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

受控焦点值

日历会尝试首先避免让用户选择无效日期。但是，如果根据应用程序逻辑，选定的日期无效，则可以设置 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

日历属性

日历事件

类型

支持的日历