DateRange

DateRange 是一個功能豐富的日期範圍選擇器組件，支援雙日曆顯示、快捷選項、範圍限制和完整的國際化功能。

主要功能

日期範圍選擇與輸入

基本日期範圍選擇

點擊選擇開始和結束日期，支援雙日曆顯示

包含時間範圍

選擇日期後可設定開始和結束時間

必填驗證

即時驗證並顯示錯誤訊息

vue

<template>
  <!-- 基本範圍選擇 -->
  <DateRange v-model="basicRange" />

  <!-- 包含時間範圍 -->
  <DateRange v-model="timeRange" :showTime="true" />

  <!-- 必填驗證 -->
  <DateRange v-model="requiredRange" required />
</template>

輸入框直接輸入

輸入框輸入

可在日曆中直接使用輸入框輸入日期範圍

僅日曆選擇

隱藏輸入框，僅使用日曆進行選擇

vue

<template>
  <!-- 啟用輸入框 -->
  <DateRange v-model="inputRange" :inputEnabled="true" />

  <!-- 僅日曆選擇 -->
  <DateRange v-model="calendarOnlyRange" :inputEnabled="false" />
</template>

WARNING

輸入功能僅限於 monthDisplayMode 為 dual 的情況下

日曆顯示模式

雙月顯示模式

同時顯示兩個連續月份的日曆，方便選擇跨月範圍

單月顯示模式

僅顯示單個月份日曆，節省顯示空間

自動模式（預設）

根據螢幕寬度自動切換：桌面版顯示雙月，行動版顯示單月

vue

<template>
  <!-- 強制雙月顯示 -->
  <DateRange v-model="dualModeRange" monthDisplayMode="dual" />

  <!-- 強制單月顯示 -->
  <DateRange v-model="singleModeRange" monthDisplayMode="single" />

  <!-- 自動適應（預設行為） -->
  <DateRange v-model="autoModeRange" />
</template>

快捷選項

內建快捷選項

提供今天、最近7天、最近30天、本月等快捷選項

vue

<template>
  <!-- 顯示快捷選項 -->
  <DateRange v-model="shortcutRange" :showShortcuts="true" />
</template>

範圍限制

最大範圍限制

最多只能選擇 7 天的範圍

最小範圍限制

至少要選擇 3 天的範圍

日期範圍限制

限制可選日期範圍: 2025-01-01 ~ 2025-12-31

vue

<template>
  <!-- 最大範圍限制 -->
  <DateRange v-model="maxRangeLimit" :maxRange="7" />

  <!-- 最小範圍限制 -->
  <DateRange v-model="minRangeLimit" :minRange="3" />

  <!-- 日期範圍限制 -->
  <DateRange
    v-model="dateConstrainedRange"
    :minDate="minDate"
    :maxDate="maxDate"
  />
</template>

Props 參數

基本屬性

屬性	類型	預設值	說明
`modelValue`	`{ start: DateTimeInput; end: DateTimeInput } \| null`	`null`	綁定的日期範圍值
`disabled`	`boolean`	`false`	是否禁用
`required`	`boolean`	`false`	是否必填
`showClearButton`	`boolean`	`true`	是否顯示清除按鈕
`separator`	`string`	`' ~ '`	開始和結束日期間分隔符

日曆系統

屬性	類型	預設值	說明
`calendar`	`string`	`'gregory'`	日曆系統 ('gregory', 'roc')
`locale`	`string`	`'zh-TW'`	語言環境
`weekStartsOn`	`0-6`	`0`	一週起始日 (0=週日)

日期格式

屬性	類型	預設值	說明
`dateFormat`	`string`	`'YYYY-MM-DD'`	日期格式
`dateSeparator`	`string`	`'-'`	日期分隔符
`outputType`	`OutputType`	`'iso'`	輸出格式類型
`useStrictISO`	`boolean`	`false`	嚴格 ISO 格式

時間選項

屬性	類型	預設值	說明
`showTime`	`boolean`	`false`	是否顯示時間選擇
`timeFormat`	`string`	`undefined`	時間格式(依照 enableSeconds 及 use24Hour 預設)
`enableSeconds`	`boolean`	`true`	是否啟用秒
`use24Hour`	`boolean`	`true`	是否使用 24 小時制

範圍特定選項

屬性	類型	預設值	說明
`monthDisplayMode`	`'single' \| 'dual'`	`undefined`	日曆顯示模式，未設定時依照視窗大小自動切換
`showShortcuts`	`boolean`	`false`	是否顯示快捷選項
`incomplete`	`boolean`	`true`	是否提示不完整的範圍選擇
`maxRange`	`number`	`undefined`	允許選擇的最大天數
`minRange`	`number`	`undefined`	允許選擇的最小天數
`minDate`	`string`	`undefined`	最小可選日期
`maxDate`	`string`	`undefined`	最大可選日期

主題外觀

屬性	類型	預設值	說明
`mode`	`'light' \| 'dark' \| 'auto'`	`'auto'`	主題模式
`theme`	`TailwindColor \| string`	`'violet'`	主題顏色

國際化與錯誤處理

屬性	類型	預設值	說明
`customLocaleMessages`	`LocaleMessages`	`undefined`	自定義語言包
`customErrorMessages`	`Record<string, string>`	`{}`	自定義錯誤訊息
`useI18n`	`boolean`	`true`	是否使用內建國際化
`showErrorMessage`	`boolean`	`true`	是否顯示錯誤訊息

輸入控制

屬性	類型	預設值	說明
`inputEnabled`	`boolean`	`false`	是否允許輸入框輸入
`placeholderOverrides`	`PlaceholderOverrides`	`{}`	自定義佔位符
`autoFocusTimeAfterDate`	`boolean`	`true`	是否自動聚焦到時間輸入框

PlaceholderOverrides 介面：

typescript

interface PlaceholderOverrides {
  start?: string; // 開始日期的提示文字
  end?: string; // 結束日期的提示文字
  year?: string; // 年份輸入框佔位符
  month?: string; // 月份輸入框佔位符
  day?: string; // 日期輸入框佔位符
  hour?: string; // 小時輸入框佔位符
  minute?: string; // 分鐘輸入框佔位符
  second?: string; // 秒數輸入框佔位符
}

Events 事件

事件名稱	參數	說明
`update:modelValue`	`(range: { start: DateTimeInput; end: DateTimeInput } \| null)`	範圍值變化時觸發
`change`	`(range: { start: DateTimeInput; end: DateTimeInput } \| null)`	使用者操作改變值時觸發
`validation`	`(isValid: boolean, errors: Record<string, string>, errorParams?: Record<string, Record<string, any>>)`	驗證狀態變化時觸發

高級功能

多種日曆系統

西元曆 (Gregorian)

民國曆 (ROC)

vue

<template>
  <!-- 西元曆 -->
  <DateRange v-model="gregorianRange" calendar="gregory" />

  <!-- 民國曆 -->
  <DateRange v-model="rocRange" calendar="roc" outputType="custom" />
</template>

TIP

更多日曆系統請參考 calendar

主題模式

淺色模式

深色模式

vue

<template>
  <!-- 不同主題模式 -->
  <DateRange v-model="lightRange" mode="light" theme="blue" />
  <DateRange v-model="darkRange" mode="dark" theme="emerald" />
</template>

TIP

更多主題相關請參考 theme

時間配置

24小時制時間範圍

12小時制時間範圍

無秒數時間範圍

vue

<template>
  <!-- 24小時制 -->
  <DateRange v-model="time24Range" :showTime="true" :use24Hour="true" />

  <!-- 12小時制 -->
  <DateRange v-model="time12Range" :showTime="true" :use24Hour="false" />

  <!-- 不顯示秒數 -->
  <DateRange
    v-model="timeNoSecondsRange"
    :showTime="true"
    :enableSeconds="false"
  />
</template>