日期范围选择器

Date Range Picker 结合了两个 DateInput 和一个 RangeCalendar 弹出框，允许用户输入或选择日期和时间范围。

安装

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

导入

用法

禁用状态

只读状态

必填项

如果向输入框传递 isRequired 属性，标签末尾将显示一个 danger 星号，且输入框将成为必填项。

变体

可见月份数

默认情况下，日历弹出框显示单个月份。visibleMonths 属性允许在屏幕空间允许的情况下同时显示最多 3 个月份。

自定义每周起始日

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

翻页行为

默认情况下，按下下一页或上一页按钮时，分页将按照 visibleMonths 的值前进。可以通过将 pageBehavior 设置为 single 来改为按单个月份翻页。

标签位置

可以通过设置 labelPlacement 属性为 inside、outside 或 outside-left 来更改标签的位置。

注意：如果未传递 label，labelPlacement 属性将默认为 outside。

带描述

可以通过传递 description 属性向输入框添加描述。

带错误消息

可以结合使用 isInvalid 和 errorMessage 属性来显示无效的输入。

你也可以传递一个函数作为错误消息。这允许基于 ValidationResult 进行动态错误消息处理。

带月份和年份选择器

可以通过将 showMonthAndYearPickers 属性设置为 true 来在日历弹出框中显示月份和年份选择器。但是，向 visibleMonths 属性传递大于 1 的数字将禁用此功能。

带时间字段

当提供 CalendarDateTime 或 ZonedDateTime 对象作为值时，DateRangePicker 会自动包含时间字段。

选择器图标

可以使用 selectorIcon 在日期范围选择器的开始和结束位置添加内容。

选择器按钮位置

可以通过设置 selectorButtonPlacement 属性为 start 或 end 来更改选择器按钮的位置。

受控模式

可以使用 value 和 onChange 属性来控制输入值。

时区

当提供 ZonedDateTime 对象作为值时，DateRangePicker 会感知时区。在这种情况下，会显示时区缩写，并且在操作值时考虑夏令时等时区问题。

@internationalized/date 包含将多种格式的字符串解析为 ZonedDateTime 对象的函数。

粒度

granularity 属性允许你控制 DateRangePicker 显示的最小单位。默认情况下，值以“天”粒度（年、月、日）显示，而 CalendarDateTime 和 ZonedDateTime 值以“分钟”粒度显示。

@internationalized/date 包含将多种格式的字符串解析为 ZonedDateTime 对象的函数。

最小日期和最大日期

minValue 和 maxValue 属性也可用于确保值在特定范围内。

@internationalized/date 包含将多种格式的字符串解析为 ZonedDateTime 对象的函数。

国际日历

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

@internationalized/date 包含将多种格式的字符串解析为 ZonedDateTime 对象的函数。

不可用日期

DateRangePicker 支持将某些日期标记为不可用。这些日期无法被用户选择，并在日历中以划掉的样式显示。在日期字段中，如果用户输入了不可用的日期，则会显示无效状态。

@internationalized/date 包含将多种格式的字符串解析为 ZonedDateTime 对象的函数。

非连续范围

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

@internationalized/date 包含将多种格式的字符串解析为 ZonedDateTime 对象的函数。

预设

@internationalized/date 包含将多种格式的字符串解析为 ZonedDateTime 对象的函数。

插槽

• base: 基础元素。处理对齐、位置和整体外观。
• label: 日期范围选择器的标签，显示在日期输入的上方、内部或左侧。
• calendar: 日历元素。
• selectorButton: 选择器按钮元素。
• selectorIcon: 选择器图标元素。
• popoverContent: 日历弹出框元素。
• calendarContent: 日历内容元素。
• inputWrapper: 包装 label（当其位于内部时）和 innerWrapper。
• input: 输入元素。
• segment: 分段元素。
• separator: 分隔符元素。
• bottomContent: 底部内容元素。
• timeInputWrapper: 时间输入元素的包装器。
• helperWrapper: 包装 description 和 errorMessage。
• description: 日期输入的描述。
• errorMessage: 日期输入的错误消息。

自定义样式

你可以通过向组件插槽传递自定义的 Tailwind CSS 类来定制 DateRangePicker 组件。

数据属性

DateRangePicker 在 base 元素上具有以下属性：

• data-slot: 所有插槽都有此属性。表示元素所属的插槽（例如 calendar）。
• data-open: 指示日历弹出框是否打开。
• data-invalid: 当日期范围选择器无效时。基于 isInvalid 属性。
• data-required: 当日期范围选择器为必填时。基于 isRequired 属性。
• data-readonly: 当日期范围选择器为只读时。基于 isReadOnly 属性。
• data-disabled: 当日期范围选择器被禁用时。基于 isDisabled 属性。
• data-has-start-content: 当日期范围选择器有起始内容时。基于 startContent 属性。
• data-has-end-content: 当日期范围选择器有结束内容时。基于 endContent 属性。
• data-has-multiple-months: 当日期范围选择器的 visibleMonth 大于 2 时。

无障碍性

• 每个日期和时间单位都显示为可单独聚焦和编辑的分段，这允许用户使用键盘轻松编辑日期，适用于任何日期格式和区域设置。
• 用户还可以打开日历弹出框以在标准月网格中选择日期范围。包含本地化的屏幕阅读器消息，用于宣布选择和可见日期范围的变化。
• 日期分段可使用易于使用的数字键盘进行编辑，日期范围可以通过在触摸屏上拖动日历中的日期来选择，并且所有交互都可以通过基于触摸的屏幕阅读器进行访问。
• 与 HTML 表单集成，支持必填、最小值和最大值、不可用日期、自定义验证函数、实时验证和服务器端验证错误。

API

DateRangePicker 属性

DateRangePicker 事件