Date

Об'єкт JavaScript Date відображає єдиний момент у часі у  незалежному від платформи форматі. Об'єкти Date містять число, яке відображає кількість мілісекунд від 1 січня 1970 року за UTC.

TC39 працює над об'єктом Temporal, новим API для дати та часу.
Читайте більше щодо нього у блозі Igalia та заповнюйте опитування. Він потребує відгуків реальних веб-розробників, але поки що не готовий для повноцінного використання!

Опис

Час ECMAScript та часові мітки

Дата JavaScript вказується як кількість мілісекунд, що пройшли від 1 січня 1970 року за UTC. Ця дата та час не є тим самим, що й час UNIX (кількість секунд, що пройшли від опівночі 1 січня 1790 року за UTC), який є базовим значенням для дати та часу, що записуються комп'ютером.

Заувага: Важливо пам'ятати, що, тоді як значення часу в серці об'єкта Date є значенням UTC, базові методи з отримання дати та часу, або їхніх елементів, усі працюють у локальному (тобто, системному) часовому поясі та зсуві.

Варто зауважити, що максимальне значення Date не співпадає з максимальним безпечним цілим числом (Number.MAX_SAFE_INTEGER дорівнює 9,007,199,254,740,991). Натомість, ECMA-262 визначає, що максимум ±100,000,000 (сто мільйонів) днів відносно 1 січня 1970 року за UTC (тобто, 20 квітня 271821 до н.е. ~ 13 вересня 275760 н.е.) можуть бути представлені стандартним об'єктом Date (що дорівнює ±8,640,000,000,000,000 мілісекундам).

Формат дати та перетворення часових поясів

Існує велика кількість методів для отримання дати у різних форматах, а також для виконання перетворень часових поясів. Особливо корисні функції, які виводять дату та час у всесвітньому координованому часі (Coordinated Universal Time, UTC), глобальному стандартному часі, визначеному Всесвітнім часовим стандартом (World Time Standard). (Цей час історично відомий як середній час за Гринвічем, бо UTC пролякає вздовж меридіану, що включає Лондон — та сусідній Гринвіч — у Великій Британії.) Пристрій користувача надає місцевий час.

Над додачу до методів для читання та зміни окремих компонентів місцевої дати та часу (таких, як getDay() та setHours()), також існують версії тих самих методів, які читають та змінюють дату та час, використовуючи час UTC (такі, як getUTCDay() та setUTCHours()).

Конструктор

Date()
Створює новий об'єкт Date.

Статичні методи

Date.now()
Вертає ціле число, що позначає поточний час — кількість мілісекунд від 1 січня 1970 року 00:00:00 за UTC без врахування високосних секунд.
Date.parse()
Розбирає рядкове представлення дати та повертає кількість мілісекунд між 00:00:00 за UTC 1 січня 1970 та зазначеною миттю у часі, ігноруючи високосні секунди.

Заувага: Розбір рядків з датою (часом) за допомогою метода Date.parse є рішуче небажаним через наявні розбіжності поміж переглядачами.

Date.UTC()
Приймає ті самі параметри, що й найдовша форма конструктора (тобто, від 2 до 7), та вертає кількість мілісекунд від 1 січня 1970 року 00:00:00 за UTC, ігноруючи високосні секунди.

Методи екземплярів

Date.prototype.getDate()
Повертає день місяця (131) для вказаної дати згідно з місцевим часом.
Date.prototype.getDay()
Повертає день тижня (06) для вказаної дати згідно з місцевим часом.
Date.prototype.getFullYear()
Повертає рік (4 цифри для 4-значних років) вказаної дати згідно з місцевим часом.
Date.prototype.getHours()
Повертає годину (023) у вказаній даті згідно з місцевим часом.
Date.prototype.getMilliseconds()
Повертає мілісекунди (0999) у вказаній даті згідно з місцевим часом.
Date.prototype.getMinutes()
Повертає хвилини (059) у вказаній даті згідно з місцевим часом.
Date.prototype.getMonth()
Повертає місяць (011) у вказаній даті згідно з місцевм часом.
Date.prototype.getSeconds()
Повертає секунди (059) у вказаній даті згідно з місцевим часом.
Date.prototype.getTime()
Повертає числове значення вказаної дати у вигляді кількості мілісекунд від 1 січня 1970 року 00:00:00 за UTC. (Для більш ранніх дат повертаються від'ємні значення.)
Date.prototype.getTimezoneOffset()
Повертає зсув часового поясу у хвилинах для місцевих налаштувань.
Date.prototype.getUTCDate()
Повертає день місяця (131) у вказаній даті згідно зі всесвітнім часом.
Date.prototype.getUTCDay()
Повертає день тижня (06) у вказаній даті згідно зі всесвітнім часом.
Date.prototype.getUTCFullYear()
Повертає рік (4 цифри для 4-значних років) у вказаній даті згідно зі всесвітнім часом.
Date.prototype.getUTCHours()
Повертає години (023) у вказаній даті згідно зі всесвітнім часом.
Date.prototype.getUTCMilliseconds()
Повертає мілісекунди (0999) у вказаній даті згідно зі всесвітнім часом.
Date.prototype.getUTCMinutes()
Повертає хвилини (059) у вказаній даті згідно зі всесвітнім часом.
Date.prototype.getUTCMonth()
Повертає місяць (011) у вказаній даті згідно зі всесвітнім часом.
Date.prototype.getUTCSeconds()
Повертає секунди (059) у вказаній даті згідно зі всесвітнім часом.
Date.prototype.getYear()
Повертає рік (зазвичай, 2–3 цифри) у вказаній даті згідно з місцевим часом. Використовуйте замість нього getFullYear().
Date.prototype.setDate()
Встановлює день місяця для вказаної дати згідно з місцевим часом.
Date.prototype.setFullYear()
Встановлює повне значення року (наприклад, 4 цифри для 4-значних років) для вказаної дати згідно з місцевим часом.
Date.prototype.setHours()
Встановлює години для вказаної дати згідно з місцевим часом.
Date.prototype.setMilliseconds()
Встановлює мілісекунди для вказаної дати згідно з місцевим часом.
Date.prototype.setMinutes()
Встановлює хвилини для вказаної дати згідно з місцевим часом.
Date.prototype.setMonth()
Встановлює місяць для вказаної дати згідно з місцевим часом.
Date.prototype.setSeconds()
Встановлює секунди для вказаної дати згідно з місцевим часом.
Date.prototype.setTime()
Встановлює об'єкту Date час, переданий кількістю мілісекунд від 1 січня 1970 року 00:00:00 за UTC. Використовуйте від'ємні значення для більш ранніх дат.
Date.prototype.setUTCDate()
Встановлює день місяця для вказаної дати згідно зі всесвітнім часом.
Date.prototype.setUTCFullYear()
Встановлює повне значення року (наприклад, 4 цифри для 4-значних років) для вказаної дати згідно зі всесвітнім часом.
Date.prototype.setUTCHours()
Встановлює години для вказаної дати згідно зі всесвітнім часом.
Date.prototype.setUTCMilliseconds()
Встановлює мілісекунди для вказаної дати згідно зі всесвітнім часом.
Date.prototype.setUTCMinutes()
Встановлює хвилини для вказаної дати згідно зі всесвітнім часом.
Date.prototype.setUTCMonth()
Встановлює місяць для вказаної дати згідно зі всесвітнім часом.
Date.prototype.setUTCSeconds()
Встановлює секунди для вказаної дати згідно зі всесвітнім часом.
Date.prototype.setYear()
Встановлює рік (зазвичай, 2–3 цифри) для вказаної дати згідно з місцевим часом. Використовуйте замість нього setFullYear().
Date.prototype.toDateString()
Повертає елементи дати об'єкта Date у вигляді зручного для читання рядка, наприклад, 'Thu Apr 12 2018'.
Date.prototype.toISOString()
Перетворює дату на рядок згідно з розширеним форматом ISO 8601.
Date.prototype.toJSON()
Повертає рядок, що відображає об'єкт Date, використовуючи toISOString(). Призначений для використання методом JSON.stringify().
Date.prototype.toGMTString()
Повертає рядок, що відображає об'єкт Date на основі часового поясу GMT (UTC). Використовуйте замість нього toUTCString().
Date.prototype.toLocaleDateString()
Повертає рядкове представлення елементів дати у відповідності до системних налаштувань.
Date.prototype.toLocaleFormat()
Перетворює дату на рядок, використовуючи рядок форматування.
Date.prototype.toLocaleString()
Повертає рядкове представлення дати відповідно до мовних налаштувань. Заміщує метод Object.prototype.toLocaleString().
Date.prototype.toLocaleTimeString()
Повертає рядкове представлення часу у відповідності до мовних налаштувань.
Date.prototype.toString()
Повертає рядкове представлення вказаного об'єкта Date. Заміщує метод Object.prototype.toString().
Date.prototype.toTimeString()
Повертає елементи часу об'єкта Date у вигляді зручного для читання рядка.
Date.prototype.toUTCString()
Перетворює дату на рядок, використовуючи часових пояс UTC.
Date.prototype.valueOf()
Повертає просте значення об'єкта Date. Заміщує метод Object.prototype.valueOf().

Приклади

Кілька способів створити екземпляр Date

Наступні приклади демонструють кілька способів створення дат JavaScript:

Заувага: Розбір рядків з датою за допомогою конструктора Date (або методу Date.parse, що є одне й те саме) є рішуче небажаним через наявні розбіжності поміж переглядачами.

let today = new Date()
let birthday = new Date('December 17, 1995 03:24:00')
let birthday = new Date('1995-12-17T03:24:00')
let birthday = new Date(1995, 11, 17)            // місяці нумеруються з 0
let birthday = new Date(1995, 11, 17, 3, 24, 0)
let birthday = new Date(628021800000)            // передаємо часову мітку

 Щоб отримати день, місяць та рік, або час

let [month, date, year]    = ( new Date() ).toLocaleDateString().split("/")
let [hour, minute, second] = ( new Date() ).toLocaleTimeString().slice(0,7).split(":")

Двозначний рік відповідає рокам 1900-1999

Для створення та отримання дат між 0 та 99 роками, слід використовувати методи Date.prototype.setFullYear() та Date.prototype.getFullYear().

let date = new Date(98, 1);  // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

// Застарілий метод, тут 98 також обертається на 1998
date.setYear(98);            // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)

date.setFullYear(98);        // Sat Feb 01 0098 00:00:00 GMT+0000 (BST)

Обчислення тривалості

У наведених прикладах показано, як визначити час, що пройшов між двома датами JavaScript.

Через різну тривалість доби (внаслідок переходів між літнім та зимовим часом), місяців та років, вираження обчисленої тривалості в одиницях, більших за години, хвилини та секунди, зустрічає багато проблем та потребує вдумливого дослідження перед застосуванням.

// Використання об'єктв Date
var start = Date.now();

// Тут якісь обчислення, тривалість яких слід з'ясувати
doSomethingForALongTime();
let end = Date.now()
let elapsed = end - start // час, що пройшов, у мілісекундах
// Використання вбудованих методів
let start = new Date()

// Подію, час якої необхідно обчислити:
doSomethingForALongTime()
let end = new Date()
let elapsed = end.getTime() - start.getTime() // час, що пройшов, у мілісекундах
// Щоб перевірити функцію та отримати її результат
function printElapsedTime(fTest) {
  let nStartTime = Date.now(),
      vReturn = fTest(),
      nEndTime = Date.now()

  console.log(`Тривалість: ${ String(nEndTime - nStartTime) } мілісекунд`);
  return vReturn
}

let yourFunctionReturn = printElapsedTime(yourFunction)

Заувага: У переглядачах з підтримкою часу високої роздільності Web Performance API, метод Performance.now() може забезпечити вищу точність та надійність вимірювання тривалості, ніж Date.now().

Отримання кількості секунд з початку епохи ECMAScript

let seconds = Math.floor(Date.now() / 1000)

У цьому випадку важливо повернути тільки ціле число, тому просте ділення не підійде. Також важливо повернути лише секунди, які вже пройшли. (Тому цей код використовує Math.floor(), а не Math.round().)

Специфікації

Специфікація
ECMAScript (ECMA-262)
The definition of 'Date' in that specification.

Підтримка веб-переглядачами

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
Date() constructorChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 3Opera Full support 3Safari Full support 1WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0nodejs Full support 0.1.100

Legend

Full support  
Full support

Див. також

  • Конструктор Date()