為何捐款
API 瀏覽器
Date Utils

Quasar provides a set of useful functions to manipulate JS Date easily in most use cases, without the high additional cost of integrating dedicated libraries like Momentjs.

Most Quasar date functions take as parameter either a Unix timestamp or a String representing a date which needs to be parsable by the native JS Date constructor. Some examples: 1497159857411, Sun Jun 11 2017 08:44:42 GMT+0300, 2017-06-16.

Returned values are all JS Dates.

Get familiar with JS native Date class, which is very powerful, and remember that you don’t need solutions like Momentjs which add hundreds of minified KB to your bundle.

TIP

Quasar date utils includes tree shaking, except for the UMD version.

You will notice all examples import date Object from Quasar. However, if you need only one method from it, then you can use ES6 destructuring to help Tree Shaking embed only that method and not all of date.

Example with addToDate()

// we import all of `date`
import { date } from 'quasar'
// destructuring to keep only what is needed
const { addToDate } = date

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

TIP

For usage with the UMD build see here.

Format for display

It takes a string of tokens and replaces them with their corresponding date values

import { date } from 'quasar'

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

For i18n, you can use a third parameter

const formattedString = date.formatDate(timeStamp, 'MMMM - dddd', {
  days: ['Duminica', 'Luni', /* and all the rest of days - remember starting with Sunday */],
  daysShort: ['Dum', 'Lun', /* and all the rest of days - remember starting with Sunday */],
  months: ['Ianuarie', 'Februarie', /* and all the rest of months */],
  monthsShort: ['Ian', 'Feb', /* and all the rest of months */]
})

Available format tokens

UnitFormats available
Year
  • YY: 70 71 … 29 30
  • YYYY: 1970 1971 … 2029 2030
Month
  • M: 1 2 … 11 12
  • Mo: 1st 2nd … 11th 12th
  • MM: 01 02 … 11 12
  • MMM: Jan Feb … Nov Dec
  • MMMM: January February … November December
Quarter
  • Q: Quarter number 1 2 3 4
  • Qo: Quarter number 1st 2nd 3rd 4th
Day of Month
  • D: 1 2 … 30 31
  • Do: 1st 2nd … 30th 31st
  • DD: 01 02 … 30 31
Day of Year
  • DDD: 1 2 … 364 365
  • DDDo: 1st 2nd … 364th 365th
  • DDDD: 001 002 … 364 365
Day of Week
  • d: 0 1 … 5 6
  • do: 0th 1st … 5th 6th
  • dd: Su Mo … Fr Sa
  • ddd: Sun Mon … Fri Sat
  • dddd: Sunday Monday … Friday Saturday
Day of Week (ISO)
  • E: 1 2 … 6 7
Week of Year
  • w: 1 2 … 52 53
  • wo: 1st 2nd … 52nd 53rd
  • ww: 01 02 … 52 53
Hour
  • H: 0 1 … 22 23
  • HH: 00 01 … 22 23
  • h: 0 … 11 12
  • hh: 01 02 … 11 12
Minute
  • m: 0 1 … 58 59
  • mm: 00 01 … 58 59
Second
  • s: 0 1 … 58 59
  • ss: 00 01 … 58 59
Fractional Second
  • S: 0 1 … 8 9
  • SS: 00 01 … 98 99
  • SSS: 000 001 … 998 999
Timezone offset
  • Z: -07:00 -06:00 … +06:00 +07:00
  • ZZ: -0700 -0600 … +0600 +0700
AM/PM
  • A: AM, PM
  • a: am, pm
  • aa: a.m, p.m
Unix Timestamp
  • X: 1360013296
  • x (ms): 1360013296123

If you want to insert strings (including [ and ] characters) into your mask, make sure you escape them by surrounding them with [ and ], otherwise the characters might be interpreted as format tokens.

Manipulate dates

Create

Try to create dates with native JS Date class like so

const date = new Date();

以下方法僅為輔助工具,適用於您只需要目前時間,但年份、月份或秒數等不同的情況。

import { date } from 'quasar'

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

您可以傳遞第二個參數(布林值)來設定 UTC 時間 (true) 而非本地時間。

提供的物件字面量可以包含以下鍵(皆為選填)

描述
毫秒 (millisecond(s))日期/時間的毫秒組成部分
秒 (second(s))日期/時間的秒組成部分
分鐘 (minute(s))日期/時間的分鐘組成部分
小時 (hour(s))日期/時間的小時組成部分
日 (day(s)) / 日期 (date)日期/時間的日組成部分
月 (month(s))日期/時間的月組成部分
年 (year(s))日期/時間的年組成部分

驗證 (Validate)

若要檢查日期字串是否有效,請使用

import { date } from 'quasar'

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

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

警告 (WARNING)

isValid 僅驗證日期格式,而非日期的邏輯有效性。

底層實作基於原生 Date.parse(...) API,其缺點也會反映到我們的 API 中。

它不會檢查日期對於月份是否有效(例如 2 月 31 日),或者日期對於年份是否有效(例如非閏年的 2 月 29 日),並且在這些情況下,對於 Firefox 相對於基於 Chromium 的瀏覽器(Chrome、Edge 等)會傳回不同的值。

新增/減少 (Add/Subtract)

若要對日期新增/減少一段持續時間,請使用

import { date } from 'quasar'

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

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

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

提供的物件字面量可以包含以下鍵(皆為選填)

描述
毫秒 (millisecond(s))用於毫秒的持續時間
秒 (second(s))用於秒的持續時間
分鐘 (minute(s))用於分鐘的持續時間
小時 (hour(s))用於小時的持續時間
日 (day(s)) / 日期 (date)用於天的持續時間
月 (month(s))用於月的持續時間
年 (year(s))用於年的持續時間

設定日期/時間 (Set date/time)

若要設定日期/時間的指定單位

import { date } from 'quasar'

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

您可以傳遞第三個參數(布林值)來設定 UTC 時間 (true) 而非本地時間。

提供的物件字面量可以包含以下鍵(皆為選填)

描述
毫秒 (millisecond(s))日期/時間的毫秒組成部分
秒 (second(s))日期/時間的秒組成部分
分鐘 (minute(s))日期/時間的分鐘組成部分
小時 (hour(s))日期/時間的小時組成部分
日 (day(s)) / 日期 (date)日期/時間的日組成部分
月 (month(s))日期/時間的月組成部分
年 (year(s))日期/時間的年組成部分

查詢日期 (Query dates)

最小值/最大值 (Minimum/Maximum)

若要取得日期集合(即陣列)的最小值/最大值日期,請使用

import { date } from 'quasar'

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

// Or use an array:
const dates = [ new Date(2017, 6, 24), new Date(2017, 5, 20), new Date(2017, 6, 26) ]
let min = date.getMinDate(...dates) // `min` is 2017-5-20
let max = date.getMaxDate(...dates) // `max` is 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)

時間範圍 (Time range)

若要檢查日期是否在給定的日期/時間範圍內,請使用

import { date } from 'quasar'

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

// **strictly** (i.e. exclusive range)
if (date.isBetweenDates(dateTarget, dateFrom, dateTo)) {
  // Do something with dateTarget
}

// including which margin you want
if (date.isBetweenDates(dateTarget, dateFrom, dateTo, { inclusiveFrom: true, inclusiveTo: true })) {
  // Do something with dateTarget
}

// if you only care about comparing dates (year/month/day, regardless of time)
// then you could tip isBetweenDates() about it so it can perform best:
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)
// Returns `newDate` if it's between 2010-2-23 and 2012-4-12; `dateMin` if it's lower; `dateMax` if it's greater

相等性 (Equality)

若要檢查兩個日期的單位是否相等,請使用

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, /* optional */ unit)) {
  // true because date1 and date2's year is the same
}

可以省略單位參數,在這種情況下,將會進行完整的日期/時間比較,否則它允許執行部分比較

Unit描述
秒 (second(s))僅測試是否秒相同
分鐘 (minute(s))僅測試是否分鐘相同
小時 (hour(s))僅測試是否小時相同
日 (day(s)) / 日期 (date)僅測試是否日相同
月 (month(s))僅測試是否月相同
年 (year(s))僅測試是否年相同

差異 (Difference)

若要計算兩個日期之間的差異,請使用

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` is 34 (days)

單位參數表示測量單位,如果未指定,則預設為 days

Unit描述
秒 (second(s))以秒為單位的距離(忽略毫秒)
分鐘 (minute(s))以分鐘為單位的距離(忽略秒,...)
小時 (hour(s))以小時為單位的距離(忽略分鐘、秒,...)
日 (day(s)) / 日期 (date)以日曆天為單位的距離
月 (month(s))以日曆月為單位的距離
年 (year(s))以日曆年為單位的距離

日曆 (Calendar)

若要取得給定日期物件的ISO 年週數,請使用

import { date } from 'quasar'

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

若要取得給定日期物件的年中日數,請使用

import { date } from 'quasar'

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

若要取得給定日期物件的週中日數,請使用

import { date } from 'quasar'

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

若要取得指定日期的月份天數

import { date } from 'quasar'

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

時間的開始/結束 (Start/End of time)

若要透過將原始日期物件設定為時間單位的開始來變更它,請使用

import { date } from 'quasar'

let newDate = new Date('2000')
// set to beginning of year 2000 (January 1st, 2000, 00:00:00.000)
newDate = date.startOfDate(newDate, 'year')
// set to end of year 2000 (December 31st, 2000, 23:59:59.999)
newDate = date.endOfDate(newDate, 'year')

第二個參數表示要重設為的單位(其開始或結束)

Unit描述
秒 (second(s))重設秒
分鐘 (minute(s))重設分鐘
小時 (hour(s))重設小時
日 (day(s)) / 日期 (date)重設天
月 (month(s))重設月
年 (year(s))重設年

其他 (Other)

取得格式 (Get Format)

import { date } from 'quasar'

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

複製日期 (Cloning Date)

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

提取日期 (Extract Date)

使用目前 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', /* and all the rest of days - remember starting with Sunday */],
  daysShort: ['Dum', 'Lun', /* and all the rest of days - remember starting with Sunday */],
  months: ['Ianuarie', 'Februarie', /* and all the rest of months */],
  monthsShort: ['Ian', 'Feb', /* and all the rest of months */]
})
// obj is a new Date() object