日期选择器

DatePicker 是一个用于处理日期的表单组件。

导入 # 


import DatePicker from 'primevue/datepicker';

基本 #

DatePicker 通过 v-model 属性进行双向值绑定。


<DatePicker v-model="date" />

表单 #

DatePicker 与 PrimeVue 表单库无缝集成。


<Form v-slot="$form" :resolver="resolver" :initialValues="initialValues" @submit="onFormSubmit" class="flex flex-col gap-4">
    <div class="flex flex-col gap-1">
        <DatePicker name="date" fluid />
        <Message v-if="$form.date?.invalid" severity="error" size="small" variant="simple">{{ $form.date.error?.message }}</Message>
    </div>
    <Button type="submit" severity="secondary" label="Submit" />
</Form>

格式 #

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

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

<DatePicker v-model="date" dateFormat="dd/mm/yy" />

区域设置 #

不同语言和格式的区域设置是全局定义的，有关详细信息，请参阅 PrimeVue 区域设置配置。

图标 #

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


<DatePicker v-model="buttondisplay" showIcon fluid :showOnFocus="false" />
<DatePicker v-model="icondisplay" showIcon fluid iconDisplay="input" />
<DatePicker v-model="templatedisplay" showIcon fluid iconDisplay="input" timeOnly>
    <template #inputicon="slotProps">
        <i class="pi pi-clock" @click="slotProps.clickCallback" />
    </template>
</DatePicker>

最小/最大 #

允许输入的日期的边界由 minDate 和 maxDate 属性定义。


<DatePicker v-model="date" :minDate="minDate" :maxDate="maxDate" :manualInput="false" />

多个 #

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


<DatePicker v-model="dates" selectionMode="multiple" :manualInput="false" />

范围 #

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


<DatePicker v-model="dates" selectionMode="range" :manualInput="false" />

按钮栏 #

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


<DatePicker v-model="date" showButtonBar />

时间 #

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


<DatePicker id="datepicker-12h" v-model="datetime12h" showTime hourFormat="12" fluid />
<DatePicker id="datepicker-24h" v-model="datetime24h" showTime hourFormat="24" fluid />
<DatePicker id="datepicker-timeonly" v-model="time" timeOnly fluid />

月份选择器 #

除了合适的 dateFormat 之外，通过将 view 指定为 month 来启用仅月份选择器。


<DatePicker v-model="date" view="month" dateFormat="mm/yy" />

年份选择器 #

除了合适的 dateFormat 之外，将 view 指定为 year 可启用年份选择器。


<DatePicker v-model="date" view="year" dateFormat="yy" />

多个月份 #

要显示的月份数通过 numberOfMonths 属性配置。


<DatePicker v-model="date" :numberOfMonths="2" />

日期模板 #

可以使用 date 插槽将自定义内容放置在日期单元格中，该插槽以 Date 作为参数。


<DatePicker v-model="date">
    <template #date="slotProps">
        <strong v-if="slotProps.date.day > 10 && slotProps.date.day < 15" style="text-decoration: line-through">{{ slotProps.date.day }}</strong>
        <template v-else>{{ slotProps.date.day }}</template>
    </template>
</DatePicker>

内联 #

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

周日一二三四五六
481234567
49891011121314
5015161718192021
5122232425262728
522930311234

<DatePicker v-model="date" inline showWeek class="w-full sm:w-[30rem]" />

填充 #

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


<DatePicker v-model="date" variant="filled" />

浮动标签 #

当获得焦点时，浮动标签会出现在输入字段的顶部。有关详细信息，请访问 浮动标签 文档。


<FloatLabel>
    <DatePicker v-model="value1" inputId="over_label" showIcon iconDisplay="input" />
    <label for="over_label">Over Label</label>
</FloatLabel>

<FloatLabel variant="in">
    <DatePicker v-model="value2" inputId="in_label" showIcon iconDisplay="input" variant="filled" />
    <label for="in_label">In Label</label>
</FloatLabel>

<FloatLabel variant="on">
    <DatePicker v-model="value3" inputId="on_label" showIcon iconDisplay="input" />
    <label for="on_label">On Label</label>
</FloatLabel>

Ifta标签 #

IftaLabel 用于创建内联顶部对齐标签。请访问 IftaLabel 文档了解更多信息。


<IftaLabel>
    <DatePicker v-model="value" inputId="date" showIcon iconDisplay="input" variant="filled" />
    <label for="date">Date</label>
</IftaLabel>

尺寸 #

日期选择器提供小和大尺寸作为基本尺寸的替代方案。


<DatePicker v-model="value1" size="small" placeholder="Small" showIcon iconDisplay="input" />
<DatePicker v-model="value2" placeholder="Normal" showIcon iconDisplay="input" />
<DatePicker v-model="value3" size="large" placeholder="Large" showIcon iconDisplay="input" />

无效 #

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


<DatePicker v-model="date1" :invalid="!date1" placeholder="Date" />
<DatePicker v-model="date2" :invalid="!date2" variant="filled" placeholder="Date" />

禁用 #

日期选择器用作具有 v-model 属性的受控输入组件。


<DatePicker v-model="date" disabled />

可访问性 #

屏幕阅读器

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

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

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

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

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

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


<label for="date1">Date</label>
<DatePicker inputId="date1" />

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

<DatePicker aria-label="Date" />

选择日期按钮键盘支持

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

弹出窗口键盘支持

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

标题按钮键盘支持

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

日期网格键盘支持

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

页脚按钮键盘支持

按键功能
回车键触发按钮操作。
空格键触发按钮操作。
PrimeVue 4.2.5 基于 Vue 3，由 PrimeTek 开发