日期選擇器

日期選擇器是一個用於處理日期的表單元件。

導入 # 


import DatePicker from 'primevue/datepicker';

基本 #

日期選擇器使用 v-model 屬性進行雙向數值綁定。


<DatePicker v-model="date" />

表單 #

日期選擇器與 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/01/01 以來的毫秒數）
  • ! - Windows 刻度（自 0001/01/01 以來的 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 時，會顯示時間選擇器，其中可以使用 hourFormat 屬性配置 12/24 小時格式。如果只需要選擇時間，請新增 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>

內嵌 #

日期選擇器預設顯示為彈出視窗，新增 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 提供小和大尺寸作為基本尺寸的替代方案。


<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" />

已停用 #

DatePicker 作為具有 v-model 屬性的受控輸入元件使用。


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

無障礙 #

螢幕閱讀器

描述元件的值可以透過結合 inputId 屬性的 label 標籤，或使用 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 的標籤。

DatePicker 也包含一個隱藏區段，該區段僅供螢幕閱讀器使用，其 aria-live 為「polite」。當選取的日期變更時，此元素會更新，以告知使用者目前選取的日期。


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

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

<DatePicker aria-label="Date" />

選擇日期按鈕鍵盤支援

按鍵功能
空白鍵開啟彈出視窗並將焦點移至選取的日期，如果沒有，則將焦點放在今天。
Enter 鍵開啟彈出視窗並將焦點移至選取的日期，如果沒有，則將焦點放在今天。

彈出視窗鍵盤支援

按鍵功能
Esc 鍵關閉彈出視窗並將焦點移至輸入元素。
Tab 鍵將焦點移至彈出視窗內的下一個可聚焦元素。
Shift + Tab 鍵將焦點移至彈出視窗內的下一個可聚焦元素。

標頭按鈕鍵盤支援

按鍵功能
Enter 鍵觸發按鈕動作。
空白鍵觸發按鈕動作。

日期網格鍵盤支援

按鍵功能
Enter 鍵選取日期、關閉彈出視窗並將焦點移至輸入元素。
空白鍵關閉彈出視窗並將焦點移至輸入元素。
向上箭頭將焦點移至前一週的同一天。
Alt + 向上箭頭關閉彈出視窗並將焦點移至輸入元素。
向下箭頭將焦點移至下一週的同一天。
向右箭頭將焦點移至下一天。
向左箭頭將焦點移至前一天。
Home 鍵將焦點移至當週的第一天。
End 鍵將焦點移至當週的最後一天。
Page Up 鍵在日期選擇器模式下將日期變更為上個月。在月份選擇器模式下移至上一年，在年份選擇器模式下移至上個十年。
Shift + Page Up 鍵在日期選擇器模式下將日期變更為上一年。在月份或年份選擇器中沒有效果。
Page Down 鍵在日期選擇器模式下將日期變更為下個月。在月份選擇器模式下移至下一年，在年份選擇器模式下移至下一個十年。
Shift + Page Down 鍵在日期選擇器模式下將日期變更為下一年。在月份或年份選擇器中沒有效果。

頁尾按鈕鍵盤支援

按鍵功能
Enter 鍵觸發按鈕動作。
空白鍵觸發按鈕動作。
PrimeVue 4.2.5 on Vue 3 by PrimeTek