A-date-picker NPM

a-date-picker

适用于 Vue2 的日期/时间选择组件。

原@wangankeji/vue-datepicker

感谢

特别感谢网安科技vue-datepicker。

在其源码基础上做了部分调整，使其适合定制化需求。

1、部分样式。

2、增小功能，rangeSingle，选择2022年2月，value = '2022-02-01', '2022-02-28'。

安装

NodeJS 环境 (commonjs)

npm i a-date-picker

或者

yarn add a-date-picker

仓库：https://gitee.com/yolanda624/a-date-picker.git

使用

<template>
  <date-picker v-model="date" type="date" :min="min" :max="max"/>
</template>
<script>
import DatePicker from 'a-date-picker'

export default {
  components: {DatePicker},
  data() {
    return {
      date: new Date(),
      min: '2012-12-12',
      max: '2020-12-12'
    }
  }
}
</script>

作为日历使用

<template>
  <picker v-model="date"/>
</template>
<script>
import {Picker} from 'a-date-picker'

export default {
  components: {Picker},
  data() {
    return {
      date: ''
    }
  }
}
</script>

自然周/自然月切换组件
WeekMonthSwitchPicker
在date-picker上的二次封装

<a-week-month-switch-picker v-model="rWeekMonth"></a-week-month-switch-picker>

默认值如下：

v-modal/value Array []
weekStart, Number 1
max, Date new Date()
rangeSingle, Boolean true
colorStyle, String light
placeholder, String

类型定义

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

是否按范围选择。

rangeSingle

type: Boolean
default: false

单个日期选择是否按范围选择/显示。
e.g.若设置为true，选择2022年2月，value = '2022-02-01', '2022-02-28'。若设置为false，选择2022年2月，value = '2022-02'。

split

type: Boolean
default: false

是否将起止日期输入框分开显示。在指定了 range 为 true 时有效。

size

type: String
default: normal

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

mousewheel

type: Boolean
default: true

是否允许鼠标滚轮操作，当设置为 true 时，可以使用滚轮快速切换年/月翻页。

week-start

type: Number
default: 0

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

0 星期天
1 星期一
2 星期二
3 星期三
4 星期四
5 星期五
6 星期六

visible

type: Boolean

控制弹出框是否可见。设置为true以显示。

shortcuts

type: Array

快捷按钮的数据，这是一个对象数组。每一项的结构为:

{
  "text": "按钮文本",
  "value": "按钮的值"
}

其中，value 在指定了 range 时为数组，否则为单个值。text 是按钮显示的文字。一般最多不超过5个中文字符，超过时会自动显示为省略号。

value 也可以是一个函数(异步支持)，函数内的返回值将作为结果。

clearable

type: Boolean

控制清除功能是否可用。可用时会显示清除按钮。

hide-icon

type: Boolean
default: false

是否隐藏左侧的日历图标

placeholder

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

type: Boolean
default: false

是否高亮选中范围。(仅在指定了 range 时有效)

readonly

(未实现)

type: Boolean

组件是否只读。

editable

(未实现)

type: Boolean

输入框是否可编辑。设置为true以手动输入日期/时间。

to-body

type: Boolean
default: true

popper-class

type: String
default: ''

指定附加到弹出框的样式名称(这个名称应该是全局的，而不是局部(scoped)的)。

value-class

type: String
default: ''

指定附加到值显示部分的样式名称(这个名称应该是全局的，而不是局部(scoped)的)。

color-style

type: String
default: 'light'

颜色样式。可选值 dark、light

popper-options

type: Object
default: {}

传递给 popperjs 的初始化选项。详见 popper.js#options

trigger

type: String
default: click

显示日期选择弹框的触发器，可选值为 click, focus。

click 此时仅可通过鼠标点击触发
focus 此时仅可通过获得焦点触发
其它值暂未处理。此时需要通过指定 visible 属性来触发

show-lunar

type: Boolean
default: false

是否显示农历信息。

show-festival

type: Boolean
default: false

是否显示节日信息，前提要先设置显示农历show-lunar为true。

markFunction

type: Function

标记函数，用于在日历上做标记。

此函数接收一个参数 e，其在不同的类型时，结构是不同的。

但是，其始终包含一个 type 属性，其标识了当前的类型: date/month/year

事件

change

参数: ({type, value, src}, oldValue)

type 指定的类型
src 事件源，用以区分事件是从何而来:
- picker 选择面板
- shortcut 快捷键
- init 初始化
- clear 清空按钮

插槽

shortcut

放置自定义的快捷按钮。

注意：在指定了 trigger=blur 时，应该尽量避免在此插槽中使用会获得焦点的元素(e.g. button/input/select)，以防止弹框意外关闭。

value

自定义值的显示。

参数: {value, type, format, visible}

title

设置选择器上方的标题文字

当指定了 range 属性时，插槽需要传入包含两个元素:

<date-picker range>
<template v-slot:title>
  <div>左侧的标题</div>
  <div>右侧的标题</div>
</template>
</date-picker>

footer

设置选择器底部的内容。

工具函数

导出了一点可能会用上的日期工具函数。

引用:

import DatePicker from 'a-date-picker'
// 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}}
   */
  getWeekOfMonth(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;

  /**
   * 获取被修正过的日期对象
   * 其修正依赖 setDate 接口
   * @see setDate
   * @return {Date} 被修正过的日期对象
   */
  getDate(): Date;

  /**
   * 设置当前日期（用于修正当前的错误日期，比如使用服务器时间的情况）
   * @param timestamp 当前的时间戳，其什可以是 秒 或者 毫秒，传入 0 表示使用系统时间
   */
  setDate(timestamp: Number): void;
}

说明：

函数 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其中之一)或同时指定多项，不区分大小写。

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago