时间工具

Quasar 提供了一组有用的函数，可以在大多数使用情况下轻松地操作 JS 中的 Date，而无需再额外安装像 Momentjs 这种专用的库。

大多数 的 Quasar 时间函数都需要传入一个可以被原生 JS Date 构造函数解析的 Unix 时间戳或者字符串作为参数。例如： 1497159857411, Sun Jun 11 2017 08:44:42 GMT+0300, 2017-06-16.

返回值都是 JS Date 对象。

熟悉 JS 原生 Date 类，它非常强大，请记住，您不需要诸如 Momentjs 之类的解决方案，这些解决方案会使您的构建产物增加数百 KB 的大小。

下面所有的示例都从 Quasar 中导入了 date 对象。然而，如果您只需要其中的一个函数，您可以使用 ES6 的解构来帮助更好的 Tree Shaking (树摇)，使其只留下一个函数，而不是全部的 date。

以 addToDate() 为例：

// 我们先导入所有的 `date`
import { date } from 'quasar'
//  解构只保留一个所需要的函数
const { addToDate } = date

const newDate = addToDate(new Date(), { days: 7, months: 1 })

显示格式化日期

它接受一个格式字符串，并将传入的日期转化成对应的格式：

import { date } from 'quasar'

const timeStamp = Date.now()
const formattedString = date.formatDate(timeStamp, 'YYYY-MM-DDTHH:mm:ss.SSSZ')

当使用 i18n 时，您还可以使用第三个参数：

const formattedString = date.formatDate(timeStamp, 'MMMM - dddd', {
  days: ['Duminica', 'Luni', /* 以及剩下的所有的天，请记住从周日开始 */],
  daysShort: ['Dum', 'Lun', /* 以及剩下的所有的天，请记住从周日开始 */],
  months: ['Ianuarie', 'Februarie', /* 以及剩下的所有的月份 */],
  monthsShort: ['Ian', 'Feb', /* 以及剩下的所有的月份 */]
})

可用的格式：

如果您希望在掩码之中插入一些字符串(包括 [ 和 ] 字符)，请确保使用 [ and ] 包裹它们来转译，否则它们会被解析成格式编码中的一部分。

操作日期

创建

尝试使用原生的 JS Date 类创建日期，例如：

const date = new Date();

下面的方法只是一个封装，可以帮助您构建一个基于当前时间日期，但是可以修改其中的年，月，或者秒等等。

import { date } from 'quasar'

const newDate = date.buildDate({ year: 2010, date: 5, hours: 15, milliseconds: 123 })

您还可以传入第二个参数(一个布尔值)来设置是否使用 UTC 时间 (true) 代替本地时间。

其中的对象可以包含以下字段（都是可选的）：

验证

检查一个日期是否合法：

import { date } from 'quasar'

const dateString = 'Wed, 09 Aug 1995 00:00:00 GMT'

if (date.isValid(dateString)) {
  // Do something with date string
}

加/减

在日期使用中加/减一段时间:

import { date } from 'quasar'

let newDate = new Date(2017, 2, 7)

newDate = date.addToDate(newDate, { days: 7, months: 1 })
// `newDate` 现在为 2017-3-14 00:00:00

newDate = date.subtractFromDate(newDate, { hours: 24, milliseconds: 10000 })
// `newDate` 现在为 2017-3-12 23:59:50

其中的对象可以包含一下字段（都是可选的）：

设置日期/时间

使用指定单位设置日期/时间

import { date } from 'quasar'

const newDate = new Date(2017, 10, 2)
const adjustedDate = date.adjustDate(newDate, { year: 2010, month: 2 })
// `adjustedDate` 变成 2010-2-2

您还可以传入第三个参数(一个布尔值)来设置是否使用 UTC 时间 (true) 代替本地时间。

其中的对象可以包含以下字段（都是可选的）：

查询日期

最大/小值

从一组日期中获取最大/小的日期：

import { date } from 'quasar'

let min = date.getMinDate(new Date(2017, 6, 24), new Date(2017, 5, 20), new Date(2017, 6, 26))
// `min` 为 2017-5-20
let max = date.getMaxDate(new Date(2017, 6, 24), new Date(2017, 5, 20), new Date(2017, 6, 26))
// `max` 为 2017-6-26

// 或者使用一个数组：
const dates = [ new Date(2017, 6, 24), new Date(2017, 5, 20), new Date(2017, 6, 26) ]
let min = date.getMinDate(...dates) // `min` 为 2017-5-20
let max = date.getMaxDate(...dates) // `max` 为 2017-6-26

注意返回值是一个时间戳。

console.log(max) // 1497906000000
console.log(new Date(max)) // Wed Jul 26 2017 00:00:00 GMT+0300 (Eastern European Summer Time)

时间范围

查询日期是否在指定的日期/时间范围内：

import { date } from 'quasar'

const dateTarget = new Date()
const dateFrom = new Date()
const dateTo = new Date()

// **严格地** (即唯一范围)
if (date.isBetweenDates(dateTarget, dateFrom, dateTo)) {
  // Do something with dateTarget
}

// 包含您想要的边界
if (date.isBetweenDates(dateTarget, dateFrom, dateTo, { inclusiveFrom: true, inclusiveTo: true })) {
  // Do something with dateTarget
}

// 如果您在比较时只关心日期中的年月日，不关心时间
// 那么您可以使用 onlyDate: true
if (date.isBetweenDates(dateTarget, dateFrom, dateTo, { onlyDate: true })) {
  // Do something with dateTarget
}

使用指定的日期/时间范围规范化一个日期：

import { date } from 'quasar'

const newDate = new Date()
const dateMin = new Date(2010, 2, 23)
const dateMax = new Date(2012, 4, 12)
const dateNormalized = date.getDateBetween(newDate, dateMin, dateMax)
// 如果 newDate 在 2010-2-23 和 2012-4-12 范围内，则返回 newDate
// 如果 newDate 小于 dateMin，则返回 dateMin
// 如果 newDate 大于 dateMax，则返回 dateMax

判断相等

使用指定单位判断两个日期是否相等：

import { date } from 'quasar'

const date1 = new Date(2017, 2, 5)
const date2 = new Date(2017, 3, 8)
const unit = 'year'

if (date.isSameDate(date1, date2, /* 可选的 */ unit)) {
  // true 因为传入的单位是年，而两个日期的年份相等
}

单位参数可以省略，此时将进行完整的日期/时间比较，否则执行部分比较：

查询时间差

计算两个日期之间的时间差：

import { date } from 'quasar'

const date1 = new Date(2017, 4, 12)
const date2 = new Date(2017, 3, 8)
const unit = 'days'

const diff = date.getDateDiff(date1, date2, unit)
// `diff` 是 34 (days)

单位参数表示计量单位，如果没有指定，则默认为 days:

日历

从指定的日期中获取 ISO 标准下一年中的第几周:

import { date } from 'quasar'

const newDate = new Date(2017, 0, 4)
const week = date.getWeekOfYear(newDate) // `week` 为 1

从给定的日期中获取一年之中的第几天：

import { date } from 'quasar'

const newDate = new Date(2017, 1, 4)
const day = date.getDayOfYear(newDate) // `day` 为 35

从给定的日期中获取一周之中的第几天：

import { date } from 'quasar'

const newDate = new Date(2017, 1, 9)
const day = date.getDayOfWeek(newDate) // `day` 为 4

从给定的日期中获取一月之中的第几天：

import { date } from 'quasar'

const newDate = new Date()
const days = date.daysInMonth(newDate) // e.g. 30

日期的开始/结束

将原始日期设置为某个单位时间的开始/结束：

import { date } from 'quasar'

let newDate = new Date(2000)
// 设置为 2000 年的开始时间  (January 1st, 2000, 00:00:00.000)
newDate = date.startOfDate(newDate, 'year')
// 设置为 2000 年的结束时间 (December 31st, 2000, 23:59:59.999)
newDate = date.endOfDate(newDate, 'year')

第二个参数表示要重置的单位（它的开始/结束）：

其他

获取格式

import { date } from 'quasar'

date.inferDateFormat(new Date()) // 'date'
date.inferDateFormat(35346363) // 'number'
date.inferDateFormat('Mon Feb 05 2018 23:05:29') // string

克隆日期

import { date } from 'quasar'

const newDate = new Date()
const clonedDate = date.clone(newDate)

date.addToDate(newDate, { days: 1 })

console.log(newDate.getDate() === clonedDate.getDate()) // false

提取日期

根据当前 Quasar 语言包设置的语言环境，您可以根据传递的格式将任何字符串解析为日期对象：

import { date } from 'quasar'

// Example 1
const date = date.extractDate('2019-10-29 --- 23:12', 'YYYY-MM-DD --- HH:mm')
// date is a new Date() object

// Example 2
const date = date.extractDate('21/03/1985', 'DD/MM/YYYY')
// date is a new Date() object

使用自定义语言环境：

import { date } from 'quasar'

const obj = date.extractDate('Month: Feb, Day: 11th, Year: 2018', '[Month: ]MMM[, Day: ]Do[, Year: ]YYYY', {
  days: ['Duminica', 'Luni', /* 以及剩下的所有的天，记得从周日开始 */],
  daysShort: ['Dum', 'Lun', /* 以及剩下的所有的天，记得从周日开始 */],
  months: ['Ianuarie', 'Februarie', /* 以及剩下所有的月份 */],
  monthsShort: ['Ian', 'Feb', /* 以及剩下所有的月份 */]
})
// date is a new Date() object