日历
日历由一个分组元素组成,包含一个或多个日期网格(例如月份),以及用于在日期范围之间导航的上一个和下一个按钮。每个日历网格由包含按钮元素的单元格组成,这些按钮元素可以被按下并使用箭头键进行导航以选择日期。
安装
npx nextui-cli@latest add calendar
以上命令仅用于单独安装。如果 @nextui-org/react
已经全局安装,您可以跳过此步骤。
导入
用法
日历默认没有选择。可以使用 defaultValue
属性为日历提供一个初始的、非受控的值。或者,可以使用 value
属性提供一个受控的值。
日期值使用 @internationalized/date 包中的对象提供。该库处理跨日历、时区和其他本地化问题的正确国际日期操作。
禁用
The isDisabled
布尔道具使日历禁用。单元格无法聚焦或选择。
只读
The isReadOnly
布尔道具使日历的值不可变。与 isDisabled
不同,日历仍然可以聚焦。
受控
日历默认没有选择。可以使用 defaultValue
道具为日历提供初始的、不受控制的值。或者,可以使用 value 道具提供受控的值。
最小日期值
默认情况下,日历允许选择任何日期。 minValue
也可以用来阻止用户选择超出特定范围的日期。
此示例仅接受今天之后的日期。
最大日期值
默认情况下,日历允许选择任何日期。 maxValue
也可以用来阻止用户选择超出特定范围的日期。
此示例仅接受今天之前的日期。
不可用日期
日历支持将某些日期标记为不可用。 这些日期仍然可以通过键盘获取焦点,以确保导航的一致性,但用户无法选择它们。 在此示例中,它们以红色显示。 isDateUnavailable
属性接受一个回调函数,该函数用于评估每个可见日期是否不可用。
受控焦点值
日历试图避免用户首先选择无效日期。 但是,如果根据应用程序逻辑,所选日期无效,则可以设置 isInvalid 属性。 这会提醒辅助技术用户所选日期无效,并且也可以用于样式目的。 此外,errorMessage 插槽可用于帮助用户解决问题。
默认情况下,日历首次加载时,选定的日期会获得焦点。如果没有提供 value
或 defaultValue
属性,则当前日期会获得焦点。但是,日历支持使用 focusedValue
和 onFocusChange
属性来控制哪个日期获得焦点。这也决定了哪个月份可见。 defaultFocusedValue
属性允许在日历首次加载时设置初始焦点日期,而无需控制它。
无效日期
此示例验证选定的日期是工作日,而不是根据当前区域设置的周末。
带月份和年份选择器
日历支持月份和年份选择器,以便快速选择。
国际日历
日历支持选择全球范围内使用的多种日历系统中的日期,包括公历、希伯来历、印度历、伊斯兰历、佛教历等等。日期会自动根据用户的区域设置以相应的日历系统显示。日历系统可以通过使用 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: 日历的错误信息。
数据属性
日历
在 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
日历属性
属性 | 类型 | 描述 | 默认值 |
---|---|---|---|
value | DateValue | null | 当前值(受控)。 | - |
defaultValue | DateValue | null | 默认值(不受控)。 | - |
minValue | DateValue | 用户可以选择的最早日期。 | - |
maxValue | DateValue | 用户可以选择的最晚日期。 | - |
color | default | primary | secondary | success | warning | danger | 时间输入的颜色。 | default |
visibleMonths | number | 一次显示的月份数。最多支持 3 个月。传递大于 1 的数字将禁用 showMonthAndYearPickers 属性 | 1 |
focusedValue | DateValue | 控制日历中当前聚焦的日期。 | - |
defaultFocusedValue | DateValue | 日历首次挂载时聚焦的日期(不受控)。 | - |
calendarWidth | number | string | 要应用于日历组件的宽度。此值乘以 visibleMonths 数以确定日历的总宽度。 | 256 |
pageBehavior | single | visible | 控制分页的行为。分页可以通过 visibleDuration(默认)或 visibleDuration 的一个单位来推进可见页面。 | visible |
weekdayStyle | narrow |short | long | undefined | 在日历网格标题中显示的星期几名称的样式,例如单个字母、缩写或完整日期名称。 | narrow |
showMonthAndYearPickers | boolean | 标签是否应该被划掉。 | false |
isDisabled | boolean | 日历是否被禁用。 | false |
isReadOnly | boolean | 日历值是否不可变。 | false |
isInvalid | boolean | 当前选择是否根据应用程序逻辑无效。 | - |
autoFocus | boolean | 日历挂载时是否自动聚焦。 | false |
showHelper | boolean | 是否显示描述或错误消息。 | false |
showShadow | boolean | 是否在选定日期显示阴影。 | false |
isHeaderExpanded | boolean | 是否展开日历标题。这仅在 showMonthAndYearPickers 属性设置为 true 时可用。 | false |
isHeaderDefaultExpanded | boolean | 日历标题是否默认展开。这仅在 showMonthAndYearPickers 属性设置为 true 时可用。 | false |
topContent | ReactNode | 要包含在日历顶部的自定义内容。 | - |
bottomContent | ReactNode | 要包含在日历底部的自定义内容。 | - |
isDateUnavailable | (date: DateValue) => boolean | 为日历的每个日期调用的回调函数。如果它返回 true,则该日期不可用。 | - |
createCalendar | (calendar: SupportedCalendars) => Calendar | null | 此函数通过提供自定义日历系统来帮助减小捆绑包大小。您也可以使用 NextUIProvider 为所有嵌套组件提供 createCalendar 函数。 | 所有 |
errorMessage | ReactNode | (v: ValidationResult) => ReactNode | 字段的错误消息。 | - |
hideDisabledDates | boolean | 是否隐藏禁用或无效日期。 | false |
disableAnimation | boolean | 是否禁用日历的动画。 | false |
classNames | Record<"base"| "prevButton"| "nextButton"| "headerWrapper" | "header" | "title" | "content" | "gridWrapper" | "grid" | "gridHeader" | "gridHeaderRow" | "gridHeaderCell" | "gridBody" | "gridBodyRow" | "cell" | "cellButton" | "pickerWrapper" | "pickerMonthList" | "pickerYearList" | "pickerHighlight" | "pickerItem" | "helperWrapper" | "errorMessage", string> | 允许为日历插槽设置自定义类名。 | - |
日历事件
属性 | 类型 | 描述 |
---|---|---|
onChange | (value: MappedDateValue) => void | 当值发生变化时调用的处理程序。 |
onFocusChange | (date: CalendarDate) => void | 当焦点日期发生变化时调用的处理程序。 |
onHeaderExpandedChange | (isExpanded: boolean) => void | 日历标题展开状态的事件处理程序。这只有在 showMonthAndYearPickers 属性设置为 true 时才可用。 |
类型
支持的日历
/*** Supported react-aria i18n calendars.*/export type SupportedCalendars =| "buddhist"| "ethiopic"| "ethioaa"| "coptic"| "hebrew"| "indian"| "islamic-civil"| "islamic-tbla"| "islamic-umalqura"| "japanese"| "persian"| "roc"| "gregory";