vue-datepicker

基于 Vue 的日期/時間選擇組件。

安裝

NodeJS 環境 (commonjs)

npm i @hyjiacan/vue-datepicker

或者

yarn add @hyjiacan/vue-datepicker

可以通過以下方式獲取最新的代碼

git clone https://github.com/hyjiacan/vue-datepicker.git

源碼倉庫

瀏覽器環境 (umd)

Since 2.4.0

與 NodeJS 環境不同的是，會暴露一個小寫的全局 datepicker。

最新版本

指定版本

/dist/datepicker.umd.min.js">

unpkg 也是可用的: 替換 cdn.jsdelivr.net 為 unpkg.com

你也可以替換 datepicker.umd.min.js 為 datepicker.umd.js 以使用未壓縮的版本進行開發調試。

注意：在瀏覽器環境直接引入時，需要顯示引入依賴

popper.js

vue-popperjs

window['vue-popperjs'] = VuePopper

其中， window['vue-popperjs'] = VuePopper 必須在 datepicker 前引入。

使用

import DatePicker from '@hyjiacan/vue-datepicker'

import '@hyjiacan/vue-datepicker/dist/datepicker.css'

export default {

components: {DatePicker},

data() {

return {

date: new Date(),

min: '2012-12-12',

max: '2020-12-12'

}

}

}

更多示例參見

類型定義

year 日期選擇，選擇 年 為結果

month 日期選擇，選擇 月 為結果

quarter 日期選擇，選擇 季度 為結果

date 日期選擇，選擇 天 為結果

week 日期選擇，選擇 周 為結果

datetime 日期時間選擇，選擇 天和時間 為結果

time 時間選擇，選擇 時間 為結果

內置格式定義

{

"year":"yyyy",

"month":"yyyy-MM-dd",

"quarter":"yyyy-MM-dd",

"date":"yyyy-MM-dd",

"time":"HH:mm:ss",

"datetime":"yyyy-MM-dd HH:mm:ss",

"week":"yyyy-MM-dd"

}

格式定義是不可配置的。

props

v-model

type: Array, String, Number, Date

required: true

日期/時間值。

在按范圍選擇時 (指定 range)，需要傳入數組。 例外的是，按星期和季度選擇時，可以僅傳入一個值。 此時會自動根據傳入日期所在范圍設置值。

若要使用空值時，請傳入空字符串 ''。

type

type: String

default: 'date'

選擇器顯示的類型。可選值見#類型定義。

format

type: String

選擇器顯示的日期/時間的格式。格式參考#內置格式定義。

此處設置的格式會應用到 v-model, min, max 上。

min

type: Number, String, Date

設置允許的日期/時間最小值。

max

type: Number, String, Date

設置允許的日期/時間最大值。

range

type: Boolean

default: false

是否按范圍選擇。

split

type: Boolean

default: false

是否將起止日期輸入框分開顯示。在指定了 range 為 true 時有效。

size

type: String

default: normal

控制日期值框的尺寸，可選值: mini, small, normal, large

mousewheel

type: Boolean

default: true

是否允許鼠標滾輪操作，當設置為 true 時，可以使用滾輪快速切換年/月翻頁。

week-start

Since 0.2.0

type: Number

default: 0

用于設置一周的第一天是哪一天。

0 星期天

1 星期一

2 星期二

3 星期三

4 星期四

5 星期五

6 星期六

visible

type: Boolean

控制彈出框是否可見。設置為true以顯示。

shortcuts

Since 0.3.0

type: Array

快捷按鈕的數據，這是一個對象數組。每一項的結構為:

{

"text":"按鈕文本",

"value":"按鈕的值"

}

其中，value 在指定了 range 時為數組，否則為單個值。text 是按鈕顯示的文字。 一般最多不超過5個中文字符，超過時會自動顯示為省略號。

value 也可以是一個函數(異步支持)，函數內的返回值將作為結果。

clearable

type: Boolean

控制清除功能是否可用。可用時會顯示清除按鈕。

hide-icon

Since 0.4.0

type: Boolean

default: false

是否隱藏左側的日歷圖標

placeholder

Since 0.4.0

type: String, Array

default: 見下方

指定 placeholder 文本。 當未指定 range 屬性，或 type 為 week/quarter時，應該指定為單個字符串； 否則，應該指定為包含兩個字符串的數組。

默認值如下:

const placeholders = {

year: '選擇年',

month: '選擇月',

week: '選擇周',

quarter: '選擇季度',

date: '選擇日期',

time: '選擇時間',

datetime: '選擇時間',

yearRange: ['起始年份', '結束年份'],

monthRange: ['起始月份', '結束月份'],

dateRange: ['起始日期', '結束日期'],

timeRange: ['起始時間', '結束時間'],

datetimeRange: ['起始時間', '結束時間']

}

highlight-range

Since 1.1.0

type: Boolean

default: false

是否高亮選中范圍。(僅在指定了 range 時有效)

readonly

(未實現)

type: Boolean

組件是否只讀。

editable

(未實現)

type: Boolean

輸入框是否可編輯。設置為true以手動輸入日期/時間。

to-body

since 2.0.3

type: Boolean

default: true

事件

change

參數: ({type, value, src}, oldValue)

type 指定的類型

src 事件源，用以區分事件是從何而來:

Since 1.1.0

picker 選擇面板

shortcut 快捷鍵

init 初始化

clear 清空按鈕

插槽

shortcut

放置自定義的快捷按鈕。

注意：由于在設計上通過 blur 事件關閉彈框，所以應該盡量避免在此插槽中使用會獲得焦點的元素(e.g. button/input/select)，以防止彈框意外關閉。

value

since 0.5.0

自定義值的顯示。

參數: {value, type, format, visible}

title

since 0.6.0

設置選擇器上方的標題文字

當指定了 range 屬性時，插槽需要傳入包含兩個元素:

工具函數

導出了一點可能會用上的日期工具函數。

引用:

import DatePicker from '@hyjiacan/vue-datepicker'

// DatePicker.$util.format

導出的工具函數，在屬性 $util 上，如: DatePicker.$util.format

所有的格式化串，請參照 內置格式定義 的寫法。

export interface WeekRangeOption {

/**

* 周起始量，0-6分別表示星期天到星期六

*/

start: Number;

/**

* 周偏移量，可以是任意整數

*/

offset: Number;

/**

* 是否附帶時間串

*/

time: Boolean;

/**

* 格式化串，不指定時返回 Date 類型

*/

format: String;

}

export interface MonthRangeOption {

/**

* 月偏移量，可以是任意整數

*/

offset: Number;

/**

* 是否附帶時間串

*/

time: Boolean;

/**

* 格式化串，不指定時返回 Date 類型

*/

format: String;

}

export interface QuarterRangeOption {

/**

* 季度偏移量，可以是任意整數

*/

offset: Number;

/**

* 是否附帶時間串

*/

time: Boolean;

/**

* 格式化串，不指定時返回 Date 類型

*/

format: String;

}

export interface WeekOfOption {

/**

* 周的偏移值

*/

start: Number;

/**

* 是否格式化

*/

format: boolean;

/**

* 遇到跨年的情況時，周應該放置在前一年(prev)還是當年(留空)或者下一年(next)

*/

boundary: string;

}

export interface DateRangeOption {

/**

* 是否格式化

*/

format: boolean;

/**

* 是否附帶時間串

*/

time: Boolean;

}

export interface DateOffset {

year: number;

month: number;

date: number;

}

export interface $util {

/**

* 將任意格式的日期格式化成指定的格式

* @param {Date|String|Number} date

* @param {String} format 輸出格式

* @param {String} [inputFormat] 當 date 是字符串時，通過此參數指定格式，不指定時使用 format 的值

* @return {string}

*/

format(date: [Date, String, Number], format: String, inputFormat?: string): string;

/**

* 將任意類型的日期格式轉換成 Date 類型

* @param {Date|String|Number} date

* @param {String} [format] 當 date 是字符串時，通過此參數指定格式

* @return {Date}

*/

parse(date: [Date, String, Number], format?: string): Date;

/**

* 根據一個日期，謀算出其所在周的起止日期

* @param {Date} date

* @param {WeekRangeOption} [option]

* @param {number} [option.start=0] 周起始量，0-6分別表示星期天到星期六

* @param {number} [option.offset=0] 周偏移量，可以是任意整數

* @param {boolean} [option.time=false] 是否附帶時間串

* @param {string} [option.format] 格式化串，不指定時返回 Date 類型

* @return {Date[]|String[]}

*/

getWeekRange(date: Date, option?: WeekRangeOption): Date[] | String[];

/**

* 根據一個日期，謀算出其所在月的起止日期 (月的第一天和最后一天)

* @param {Date} date

* @param {MonthRangeOption} [option]

* @param {number} [option.offset=0] 月偏移量，可以是任意整數

* @param {boolean} [option.time=false] 是否附帶時間串

* @param {string} [option.format] 格式化串，不指定時返回 Date 類型

* @return {Date[]|String[]}

*/

getMonthRange(date: Date, option?: MonthRangeOption): Date[] | String[];

/**

* 根據一個日期，謀算出其所在季度的起止日期

* @param {Date} date

* @param {QuarterRangeOption} [option]

* @param {number} [option.offset=0] 季度偏移量，可以是任意整數

* @param {boolean} [option.time=false] 是否附帶時間串

* @param {string} [option.format] 格式化串，不指定時返回 Date 類型

* @return {Date[]|String[]}

*/

getQuarterRange(date: Date, option?: QuarterRangeOption): Date[] | String[];

/**

* 獲取傳入日期處于一年中的第多少周

* @param {Date|Date[]} date

* @param {WeekOfOption} [option]

* @param {number} [option.start=0] 周的偏移值

* @return {{year: Number, week: Number}}

*/

getWeekOfYear(date: Date | Date[], option?: WeekOfOption): { year: Number, week: Number };

/**

* 獲取傳入日期處于一月中的第多少周

* @param {Date|Date[]} date

* @param {WeekOfOption} [option]

* @param {number} [option.start=0] 周的偏移值

* @return {{year: Number, month: Number, week: Number}}

*/

getWeekOfYear(date: Date | Date[], option?: WeekOfOption): { year: Number, month: Number, week: Number };

/**

* 根據一個日期以及偏移參數獲取日期范圍

* @param {Date} date

* @param {DateOffset|string} beginOffset 開始日期的偏移量

* @param {DateOffset|string} endOffset 結束日期的偏移量

* @param {DateRangeOption} [option]

* @param {string} [option.format] 格式化串，不指定時返回 Date 類型

* @param {boolean} [option.time=false] 是否附帶時間串

* @return {Date[]|String[]}

*/

getDateRange(date: Date, beginOffset: DateOffset | string, endOffset: DateOffset | string, option?: DateRangeOption): Date[] | string[];

/**

* 按指定規則對日期進行偏移

* @param {Date} date

* @param {DateOffset|string} offset 日期的偏移量

* @return {Date} 偏移后的日期對象(新對象)

*/

offsetDate(date: Date, offset: DateOffset | string): Date;

}

說明：

函數 getDateRange 和 offsetDate 的偏移參數為字符串時，取值格式為 1y-2m3d:

1y 表示年偏移量為 1

-2m 表示月偏移量為 -2

3d 表示天偏移量為 3

這個串的偏移結果相當于：

const date = new Date()

date.setFullYear(date.getFullYear() + 1)

date.setMonth(date.getMonth() - 2)

date.setDate(date.getDate() + 3)

可以僅指定一項(y/m/d其中之一)或同時指定多項，不區分大小寫。

支持

感謝 iconfont 提供的圖標平臺，以及開源圖標的設計者們

更新日志

2.0.0

修復 season 詞義錯誤，使用 quarter 作為季度名稱

1.1.2

修復 在僅改變了開始日期時，未觸發 change 事件的問題

1.1.1

修復 選擇彈框布局錯亂

1.1.0

添加 highlight-range 屬性，以高亮選中范圍的背景

優化 給 change 事件添加 src 參數，以輔助開發

1.0.0

優化 將樣式文件生成到獨立CSS文件中，不再混入JS代碼

修復 outline 樣式

0.6.14

修復 outline 樣式范圍超出容器寬度的問題

0.6.13

修復 選中值后焦點仍然存在導致無法打開彈框的問題

修復 點擊清除按鈕會打開彈框的問題

修復 點擊快捷按鈕可能會關閉彈框的問題

修復 其它問題

優化 高亮當前日期

0.6.12

修復 點擊快捷按鈕時，會導致彈框關閉的問題

0.6.10

優化 支持通過焦點顯示/隱藏彈框

0.6.9

修復 type=week 初始化時，傳入值不是有正確的星期范圍時可能不會觸發值更新的問題

0.6.8

修復 getDateRange 在未傳入 option 參數時報錯的問題

0.6.7

修復 getWeekRange 計算錯誤

0.6.6

添加工具函數 getDateRange 與 offsetDate

0.6.5

優化 快捷鍵配置的json格式中，支持將 value 設置成函數

0.6.0

添加 title 插槽支持

0.5.2

修復 getWeekRange 計算錯誤

0.5.0

暴露出工具函數 getWeekOfYear

添加 值渲染插槽

0.4.0

修改 geWeek(Month/Quarter)Range 參數

添加 日歷圖標

優化 樣式

移除 split 屬性

添加 placeholder 支持

0.3.0

優化 日歷上對年的限制 1900 到 2999

優化 范圍選擇樣式

優化 函數功能

優化 統一樣式類命名規則

添加 清除值功能

添加 空值支持

添加 shortcuts屬性以及slots=shortcut，用于放置快捷按鈕

0.2.6

優化 range 屬性，當設置 type 為 week或quarter時， range 自動變更為 true

優化 v-model 屬性，當設置的值為空(即未設置)時，使用當前日期

0.2.5

修復 計算周范圍的錯誤

添加 工具函數 DatePicker.$util

添加 types 聲明

0.2.1

修復 按范圍選擇時，背景透明的問題

修復 選擇1月28號以后，導致1月日歷丟失的問題