日历

日历，也称为日期选择器，是一个用于处理日期的表单组件。

导入#


import { Calendar } from 'primereact/calendar';
         

基本用法#

日历用作具有 value 和 onChange 属性的受控输入组件。


<Calendar value={date} onChange={(e) => setDate(e.value)} />
         

格式化#

默认日期格式为 mm/dd/yy，可以使用 dateFormat 属性进行自定义。以下选项可以作为格式的一部分。

  • d - 月中的某天（无前导零）
  • dd - 月中的某天（两位数字）
  • o - 年中的某天（无前导零）
  • oo - 年中的某天（三位数字）
  • D - 星期几的简称
  • DD - 星期几的全称
  • m - 月份（无前导零）
  • mm - 月份（两位数字）
  • M - 月份名称简称
  • MM - 月份名称全称
  • y - 年份（两位数字）
  • yy - 年份（四位数字）
  • @ - Unix 时间戳（自 1970/01/01 以来的毫秒数）
  • ! - Windows 时间刻度（自 0001/01/01 以来的 100 纳秒）
  • '...' - 文字文本
  • '' - 单引号
  • 其他任何内容 - 文字文本

<Calendar value={date} onChange={(e) => setDate(e.value)} dateFormat="dd/mm/yy" />
         

区域设置#

基于区域设置的设置（例如标签、dateFormat 和 firstDayOfWeek）源自全局区域设置配置。如果需要自定义某个日历，可以使用 locale 属性覆盖全局设置。


<Calendar value={date} onChange={(e) => setDate(e.value)} locale="es" />
         

图标#

当存在 showIcon 时，输入字段旁边会显示一个额外的图标。


<Calendar value={date} onChange={(e) => setDate(e.value)} showIcon />
         

最小/最大#

可以使用 minDate 和 maxDate 属性定义允许输入的日期的边界。


<Calendar id="minmax" value={date} onChange={(e) => setDate(e.value)} minDate={minDate} maxDate={maxDate} readOnlyInput />
         

多选#

要选择多个日期，请将 selectionMode 设置为 multiple。在这种模式下，值绑定应为数组。


<Calendar value={dates} onChange={(e) => setDates(e.value)} selectionMode="multiple" readOnlyInput />
         

范围#

可以通过将 selectionMode 定义为 range 来选择日期范围，在这种情况下，绑定值将是一个包含两个值的数组，其中第一个日期是范围的开始，第二个日期是范围的结束。


<Calendar value={dates} onChange={(e) => setDates(e.value)} selectionMode="range" readOnlyInput hideOnRangeSelection />
         

按钮栏#

当存在 showButtonBar 时，今天和清除按钮会显示在页脚中。


<Calendar value={date} onChange={(e) => setDate(e.value)} showButtonBar />
         

时间#

当启用 showTime 时，会显示一个时间选择器，其中使用 hourFormat 属性配置 12/24 小时格式。如果只需要选择时间，请添加 timeOnly 以隐藏日期部分。


<Calendar value={datetime12h} onChange={(e) => setDateTime12h(e.value)} showTime hourFormat="12" />
<Calendar value={datetime24h} onChange={(e) => setDateTime24h(e.value)} showTime hourFormat="24" />
<Calendar value={time} onChange={(e) => setTime(e.value)} timeOnly />
         

月份选择器#

通过将 view 指定为 month 以及合适的 dateFormat 来启用仅限月份的选择器。


<Calendar value={date} onChange={(e) => setDate(e.value)} view="month" dateFormat="mm/yy" />
         

年份选择器#

通过将 view 指定为 year 以及合适的 dateFormat 来启用年份选择器。


<Calendar value={date} onChange={(e) => setDate(e.value)} view="year" dateFormat="yy" />
         

多个月份#

要显示的月份数使用 numberOfMonths 属性配置。


<Calendar value={date} onChange={(e) => setDate(e.value)} numberOfMonths={3} />
         

日期模板#

可以使用 dateTemplate 属性将自定义内容放置在日期单元格内，该属性将 Date 作为参数。


<Calendar value={date} onChange={(e) => setDate(e.value)} dateTemplate={dateTemplate} />
         

触摸 UI#

当启用 touchUI 时，覆盖层会显示为针对触摸设备进行了优化。


<Calendar value={date} onChange={(e) => setDate(e.value)} touchUI />
         

内联#

日历默认显示为弹出窗口，添加 inline 属性以自定义此行为。

周日一二三四五六
522930311234
1567891011
212131415161718
319202122232425
42627282930311

<Calendar value={date} onChange={(e) => setDate(e.value)} inline showWeek />

         

填充#

将 variant 属性指定为 filled 以显示具有比默认 outlined 样式更高的视觉强调的组件。


<Calendar variant="filled" value={date} onChange={(e) => setDate(e.value)} />
         

浮动标签#

当输入字段获得焦点时，浮动标签会显示在输入字段的顶部。有关更多信息，请访问浮动标签文档。


<FloatLabel>
    <Calendar inputId="birth_date" value={date} onChange={(e) => setDate(e.value)} />
    <label htmlFor="birth_date">Birth Date</label>
</FloatLabel>
         

无效#

使用 invalid prop 显示无效状态，以指示验证失败。在与表单验证库集成时，可以使用此样式。


<Calendar invalid/>
         

禁用#

当存在 disabled 时，元素无法编辑和获得焦点。


<Calendar disabled />
         

辅助功能#

屏幕阅读器

用于描述组件的值可以通过与 inputId prop 组合的 label 标签提供，也可以使用 aria-labelledby、aria-label props 提供。输入元素除了具有 aria-autocomplete 作为 "none"，aria-haspopup 作为 "dialog" 和 aria-expanded 属性外，还具有 combobox 角色。输入和弹出窗口之间的关系是通过引用弹出窗口 id 的 aria-controls 属性创建的。

可选的日历按钮需要包含 aria-haspopup、aria-expanded 状态以及 aria-controls 以定义弹出窗口和按钮之间的关系。读取的值是从 区域设置 API 的 aria 属性的 chooseDate 键检索的。此标签也用于弹出窗口的 aria-label。当有选定的值时，它会被格式化并附加到标签中，以便能够通知用户当前值。

弹出窗口具有 dialog 角色以及 aria-modal 和 aria-label。标头上的导航按钮具有从区域设置 aria API 的 prevYear、nextYear、prevMonth、nextMonth、prevDecade 和 nextDecade 键检索的 aria-label。类似地，月份选择器按钮使用 chooseMonth 键，年份选择器按钮使用 chooseYear 键。

主日期表格使用 grid 角色，其中包含以 col 作为范围的 th 元素以及解析为月份全名的 abbr 标签。每个日期单元格都有一个引用完整日期值的 aria-label。页脚中的按钮也将其可读标签用作 aria-label。选定的日期也会收到 aria-selected 属性。

时间选择器微调器按钮从使用 prevHour、nextHour、prevMinute、nextMinute、prevSecond、nextSecond、am 和 pm 的 aria 区域设置 API 获取其 aria-label 的标签。键。

日历还包含一个隐藏部分，该部分仅对将 aria-live 设置为“polite”的屏幕阅读器可用。当选定的日期更改时，此元素会更新，以指示用户当前选择的日期。


<label htmlFor="date1">Date</label>
<Calendar inputId="date1" />

<span id="date2">Date</span>
<Calendar aria-labelledby="date2" />

<Calendar aria-label="Date" />
     

“选择日期”按钮的键盘支持

按键功能
空格键打开弹出窗口并将焦点移动到选定的日期，如果没有选定的日期，则焦点移动到今天。
回车键打开弹出窗口并将焦点移动到选定的日期，如果没有选定的日期，则焦点移动到今天。

弹出窗口的键盘支持

按键功能
Esc键关闭弹出窗口并将焦点移动到输入元素。
Tab键将焦点移动到弹出窗口内的下一个可聚焦元素。
Shift + Tab键将焦点移动到弹出窗口内的下一个可聚焦元素。

标题按钮的键盘支持

按键功能
回车键触发按钮操作。
空格键触发按钮操作。

日期网格的键盘支持

按键功能
回车键选择日期，关闭弹出窗口并将焦点移动到输入元素。
空格键选择日期，关闭弹出窗口并将焦点移动到输入元素。
向上箭头将焦点移动到上一周的同一天。
向下箭头将焦点移动到下一周的同一天。
向右箭头将焦点移动到下一天。
向左箭头将焦点移动到前一天。
Home键将焦点移动到当前周的第一天。
End键将焦点移动到当前周的最后一天。
Page Up键在日期选择器模式下，将日期更改为上个月。在月份选择器模式下，移动到上一年；在年份选择器模式下，移动到上一个十年。
Shift + Page Up键在日期选择器模式下，将日期更改为上一年。在月份或年份选择器中无效。
Page Down键在日期选择器模式下，将日期更改为下个月。在月份选择器模式下，移动到下一年；在年份选择器模式下，移动到下一个十年。
Shift + Page Down键在日期选择器模式下，将日期更改为下一年。在月份或年份选择器中无效。

页脚按钮的键盘支持

按键功能
回车键触发按钮操作。
空格键触发按钮操作。
                                            PrimeReact 10.9.1，由 PrimeTek 提供