Eiya

一个日期常用处理方法的集合，包括格式化，解析，加减，比较等方法

install

$ yarn add eiya

or

$ npm install eiya

usage

import Eiya from 'eiya'; //或者安装后直接通过script脚本引用dist目录下编译后的文件

// 实例链式调用
const date = new Eiya();
date.add(1, 'year').subtract('1', 'month').startOf('date');

// 静态方法使用
const now = new Date();
Eiya.startOf(now, 'date');

api

静态方法

Eiya.format(date, fmt, locale)

• 概述

  格式化日期到指定格式字符串形式

• 参数

  @param {Date} date 被格式化的日期对象

  @param {String} fmt 格式化字符串, 支持的格式请参考格式说明

  @param {LocaleSymbol} locale 当次格式化使用的格式定义

• 示例

  Eiya.format(new Date(2020, 10, 10, 12, 14, 45, 453), 'yyyy/MM/dd HH:mm:ss SSS');
  // 2020/11/10 12:14:45 453
  Eiya.format(new Date(2020, 10, 10, 12, 14, 45, 453), 'EEE', {EEE: ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']});
  // Tu

Eiya.parse(str, fmt, locale)

• 概述

  将指定格式的日期字符串解析成日期对象

• 参数

  @param {String} str 表示日期的字符串

  @param {String} fmt 日期字符串的格式

  @param {LocaleSymbol} locale 当次解析使用的格式定义

• 示例

  Eiya.parse('2020/11/10 12:14:45 453', 'yyyy/MM/dd HH:mm:ss SSS')
  // 2020-11-10T04:14:45.453Z  这是0时区表示时间，所以小时差了8小时

Eiya.isLeapYear(year)

• 概述

  判断指定年份是否是闰年

• 参数

  @param {Number} year 需要判断的年份

• 示例

  Eiya.isLeapYear(2020) // true

Eiya.daysInMonth(year, month)

• 概述

  判断指定月份有多少天

• 参数

  @param {Number} year 年份，用于判断是否是闰年

  @param {Number} month 月份，1月份为0

• 示例

  Eiya.daysInMonth(2020, 1) // 29

Eiya.isValidDate(year, month, date, hour, minute, second, millisecond)

• 概述

  判断指定的年月日时分秒毫秒是否是一个真实合法的时间

• 参数

  依次是年，月(从0开始)，日，时，分，秒，毫秒

• 示例

  Eiya.isValidDate(2020, 3, 32, 12, 12, 23, 345) // false

Eiya.isSame(date1, date2, option)

• 概述

  判断两个日期是否相同

• 参数

  @param {Date} date1, date2 待比较Date对象

  @option {String, Object} 比较选项设置

  • option.precision 比较精度，支持year, month, date, hour, minute, second, millisecond, week。默认为millisecond
  • option.easy 是否只比较设置的精度，不考虑前置时间，如只比较月份而不用考虑年份
  • option 也可以传字符串，代表option.precision

• 示例

  const date1 = new Date(2020, 10, 15);
  const date2 = new Date(2020, 8, 15);
  Eiya.isSame(date1, date2, 'date') // false
  Eiya.isSame(date1, date2, {precision: 'date', easy: true}) // true

Eiya.isBetween(date, start, end, option)

• 概述

  判断date是否处于start，end之间

• 参数

  @param {Date} date, start, end 分别是被判断时间，区间起始时间，区间结束时间

  @option {String,Object} 比较选项设置

  • option.precision 同 Eiya.isSame 中的设置
  • option.easy 同 Eiya.isSame 中的设置
  • option.boundary 是否包含左右边界，默认 [] 请参考数学区间定义

• 示例

  const date = new Date(2020, 10, 15);
  const start = new Date(2020, 10, 15);
  const end = new Date(2020, 11, 15);
  Eiya.isBetween(date, start, end, 'date') // true
  Eiya.isBetween(date, start, end, {precision: 'date', boundary: '(]'}) // false

Eiya.isAfter(date, target, option)

• 概述

  判断date日期是否在target日期以后

• 参数

  @param {Date} date, target 比较的日期对象

  @param option 参数同 Eiya.isSame 支持 precision, easy, self

  • option.self 表示是否包含target日期

Eiya.isBefore(date, target, option)

• 概述

  判断date日期是否在target日期以前。其余同 Eiya.isAfter

Eiya.add(date, addend, option)

• 概述

  对date日期进行加法运算

• 参数

  @param {Date} date 被运算的日期对象

  @param {Number} addend 增量

  @param {String, Object} option 运算选项设置

  • option.precision 需要在哪个单位上进行加运算，支持 year, month, date, hour, minute, second, millisecond, week
  • option.end 是否月末对齐
  • option.overstep 超过月份最大日期，是否跨到下一月

• 示例

  const date = new Date(2020, 1, 29, 12, 23, 24, 456);
  Eiya.add(date, 1, 'year') // 2021-02-28T04:23:24.456Z
  Eiya.add(date, 1, {precision: 'year', end: false, overstep: true}) //2021-03-01T04:23:24.456Z
  Eiya.add(date, 1, 'month') //2020-03-31T04:23:24.456Z

Eiya.subtract(date, subtrahend, option)

• 概述

  相当于 Eiya.add 方法参数 addend 为负数。其它一致

Eiya.startOf(date, precision)

• 概述

  返回日期指定精度的起始时间

• 参数

  @param {Date} date 参考日期对象

  @param {String} precision 支持year, month, date, hour, minute, second, week

• 示例

  const date = new Date(2020, 1, 12, 12, 24, 45, 235);
  Eiya.startOf(date, 'year') // 2019-12-31T16:00:00.000Z 转化为当前东八时间，就是2020/01/01 00:00:00 000

Eiya.endOf(date, precision)

• 概述

  返回日期指定精度的最后时刻，其它和 Eiya.startOf 相同

• 示例

  const date = new Date(2020, 1, 12, 12, 24, 45, 235);
  Eiya.endOf(date, 'year') // 2020-12-31T15:59:59.999Z 转化为当前东八时间，就是2020/12/31 23:59:59.999

Eiya.clone(date)

• 概述

  返回一个和参数日期对象表示相同时间的新日期对象

Eiya.compare(date1, date2, option)

• 概述

  在指定精度下，date1如果在date2之前，返回-1， date1和date2相同返回0, date1在date2之后，返回1

• 参数

  option和 Eiya.isAfter 有相同的意义

Eiya.max(option, ...args)

• 概述

  返回参数日期列表中最大的日期，第一个参数可以是精度设置，支持 precision 和 easy

Eiya.min(option, ...args)

• 概述

  返回参数日期列表中最小的日期，第一个参数可以是精度设置，支持 precision 和 easy

实例方法

实例方法和方法基本一致，没有，parse, max, min 等方法，实例方法接收的日期参数不仅可以是Date实例对象，还可以是Eiya实例对象。并且操作型的方法，add, subtract, startOf, endOf, clone 支持链式调用

格式说明

| 符号 | 说明 | | ---- | ------------------------------------------- | | yyyy | 完整年份 | | yy | 19**年的时候返回后两位数字 | | M | 月份 | | d | 日期 | | H | 24小时制的小时 | | h | 12小时制的小时, 需要配制am/pm来标记上午下午 | | m | 分钟 | | s | 秒 | | S | 毫秒 | | E | 一周中的天数，从0开始，周日为第一天 | | a | am/pm | | A | AM/PM |

1~2位的基本是数字格式的，1位不补前置0，2位补前置0。默认非数字的格式定义如下

| 格式 | 定义 | | ----- | ------------------------------------------------------------ | | MMM | Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec | | MMMM | January, February, March, April, May, June, July, August, September, October, November, December | | MMMMM | 一, 二, 三, 四, 五, 六, 七, 八, 九, 十, 十一, 十二 | | EEE | Sun, Mon, Tue, Wed, Thu, Fri, Sat | | EEEE | Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday | | EEEEE | 日, 一, 二, 三, 四, 五, 六 | | a | am, pm | | A | AM, PM |