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月日历丢失的问题