Date

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

Примітка: TC39 наразі працює над Temporal (англ.), новим API для дати й часу. Більше про це в блозі Igalia (англ.). Однак цей інтерфейс іще не готовий для застосування в програмних продуктах.

Опис

Епоха ECMAScript і мітки часу

В основі своїй дата в JavaScript задається як кількість мілісекунд, що минули від епохи ECMAScript (англ.), що визначена як північ на початку 1 січня 1970 року за UTC (еквівалентно епосі UNIX).

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

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

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

Існує кілька різних способів отримання дати в різних форматах, як і перетворення між часовими зонами. Особливо корисні ті функції, які повертають результат у форматі Всесвітнього координованого часу (UTC) — загального формату часу, визначеного у світовому стандарті часу (цей час також історично відомий як Середній час за Гринвічем (GMT), оскільки UTC лежить вздовж меридіану, який включає Лондон – і розташований неподалік Гринвіч – у Великобританії). Пристрій користувача надає локальний час.

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

Конструктор

Date()

Коли викликається як функція — повертає поточні дату і час, оформлені у рядок. Всі аргументи ігноруються. Результат такий самий, як від виклику new Date().toString().

new Date()

Коли викликається як конструктор — повертає новий об'єкт Date.

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

Date.now()

Повертає числове значення, що відповідає поточному часові: кількість мілісекунд, що сплили від 1 січня 1970 року, 00:00:00 UTC, без врахування високосних секунд.

Date.parse()

Розбирає рядок з датою і повертає відповідну кількість мілісекунд від 1 січня 1970 року 00:00:00 UTC, без врахування високосних секунд.

Примітка: Наполегливо не рекомендовано розбирати рядки з датами за допомогою Date.parse у зв'язку з відмінностями та неузгодженістю браузерів.

Date.UTC()

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

Властивості примірника

Ці властивості означені на Date.prototype і є спільними для всіх примірників Date.

Date.prototype.constructor

Функція-конструктор, що створила об'єкт-примірник. Для примірників Date початковим значенням є конструктор Date.

Методи примірника

Date.prototype.getDate() (отримати дату)

Повертає день місяця (1 – 31) вказаної дати, відповідно до локального часу.

Date.prototype.getDay() (отримати день)

Повертає день тижня (0 – 6) вказаної дати, відповідно до локального часу.

Date.prototype.getFullYear() (отримати повний рік)

Повертає рік (4 цифри у випадку 4-цифрових років) вказаної дати, відповідно до локального часу.

Date.prototype.getHours() (отримати години)

Повертає годину (0 – 23) вказаної дати, відповідно до локального часу.

Date.prototype.getMilliseconds() (отримати мілісекунди)

Повертає мілісекунди (0 – 999) вказаної дати, відповідно до локального часу.

Date.prototype.getMinutes() (отримати хвилини)

Повертає хвилини (0 – 59) вказаної дати, відповідно до локального часу.

Date.prototype.getMonth() (отримати місяць)

Повертає місяць (0 – 11) вказаної дати, відповідно до локального часу.

Date.prototype.getSeconds() (отримати секунди)

Повертає секунди (0 – 59) вказаної дати, відповідно до локального часу.

Date.prototype.getTime() (отримати час)

Повертає числове значення вказаної дати як число мілісекунд, що минули від 1 січня 1970 року 00:00:00 UTC. (Для більш ранньої дати буде повернено від'ємне значення.)

Date.prototype.getTimezoneOffset() (отримати зміщення часової зони)

Повертає зміщення часової зони у хвилинах для поточної локалі.

Date.prototype.getUTCDate() (отримати дату відповідно до всесвітнього часу)

Повертає день (дату) місяця (1 – 31) вказаної дати, відповідно до всесвітнього часу.

Date.prototype.getUTCDay() (отримати день відповідно до всесвітнього часу)

Повертає день тижня (0 – 6) вказаної дати, відповідно до всесвітнього часу.

Date.prototype.getUTCFullYear() (отримати повний рік відповідно до всесвітнього часу)

Повертає рік (4 цифри у випадку 4-цифрових років) вказаної дати, відповідно до всесвітнього часу.

Date.prototype.getUTCHours() (отримати години відповідно до всесвітнього часу)

Повертає годину (0 – 23) вказаної дати, відповідно до всесвітнього часу.

Date.prototype.getUTCMilliseconds() (отримати мілісекунди відповідно до всесвітнього часу)

Повертає мілісекунди (0 – 999) вказаної дати, відповідно до всесвітнього часу.

Date.prototype.getUTCMinutes() (отримати хвилини відповідно до всесвітнього часу)

Повертає хвилини (0 – 59) вказаної дати, відповідно до всесвітнього часу.

Date.prototype.getUTCMonth() (отримати місяць відповідно до всесвітнього часу)

Повертає місяць (0 – 11) вказаної дати, відповідно до всесвітнього часу.

Date.prototype.getUTCSeconds() (отримати секунди відповідно до всесвітнього часу)

Повертає секунди (0 – 59) вказаної дати, відповідно до всесвітнього часу.

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)

Перетворює дату на рядок відповідно до формату ISO 8601 Extended Format.

Date.prototype.toJSON() (до JSON)

Повертає рядок, що відповідає даті в Date, сформований за допомогою toISOString(). Призначений для використання функцією JSON.stringify().

Date.prototype.toLocaleDateString() (до місцевого рядка дати)

Повертає порцію об'єкта Date, що містить дату, як рядок, оформлений з урахуванням локально специфічних деталей на основі системних налаштувань.

Date.prototype.toLocaleString() (до місцевого рядка)

Повертає рядок даної дати, оформлений з урахуванням локально специфічних деталей. Заміщує метод Object.prototype.toLocaleString().

Date.prototype.toLocaleTimeString() (до місцевого рядка часу)

Повертає порцію об'єкта Date, що містить час, як рядок, оформлений з урахуванням локально специфічних деталей на основі системних налаштувань.

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, що еквівалентно), завжди слідкуйте, аби вихідні дані відповідали форматові ISO 8601 (англ.) (YYYY-MM-DDTHH:mm:ss.sssZ): логіка розбору інших форматів визначається реалізацією, такий розбір може не працювати на всіх браузерах. З пристосуванням до розмаїття форматів може допомогти бібліотека.

const today = new Date();
const birthday = new Date("December 17, 1995 03:24:00"); // НЕРЕКОМЕНДОВАНО: може не працювати в усіх середовищах виконання
const birthday2 = new Date("1995-12-17T03:24:00"); // Відповідає форматові ISO8601, а тому надійно працюватиме
const birthday3 = new Date(1995, 11, 17); // індекс місяця починається з 0
const birthday4 = new Date(1995, 11, 17, 3, 24, 0);
const birthday5 = new Date(628021800000); // передача мітки часу

Формати значень, повернених методом toString

const date = new Date("2020-05-12T23:50:21.817Z");
date.toString(); // Wed May 13 2020 02:50:21 GMT+0300 (Eastern European Summer Time)
date.toDateString(); // Wed May 13 2020
date.toTimeString(); // 02:50:21 GMT+0300 (Eastern European Summer Time)
date.toISOString(); // 2020-05-12T23:50:21.817Z
date.toUTCString(); // Tue, 12 May 2020 23:50:21 GMT
date.toJSON(); // 2020-05-12T23:50:21.817Z
date.toLocaleString(); // 13/05/2020, 02:50:21
date.toLocaleDateString(); // 13/05/2020
date.toLocaleTimeString(); // 02:50:21

Отримання дати, місяця, року чи часу

const date = new Date();
const [month, day, year] = [
  date.getMonth(),
  date.getDate(),
  date.getFullYear(),
];
const [hour, minutes, seconds] = [
  date.getHours(),
  date.getMinutes(),
  date.getSeconds(),
];

Інтерпретація двоцифрових років

Конструктор new Date() демонструє непослідовну поведінку під час роботи з двоцифровими значеннями року. Така поведінка застаріла і зазвичай небажана. Власне, коли у виклик new Date() передається двоцифрове значення року, замість опрацьовуватися буквально як рік і використовуватися як є, це число інтерпретується як відносне значення. В деяких випадках як зміщення від 1900 року, а в інших — як зміщення відносно 2000.

let date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date = new Date(22, 1); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)
date = new Date("2/1/22"); // Tue Feb 01 2022 00:00:00 GMT+0000 (GMT)

// Застарілий метод; завжди інтерпретує двоцифрове значення року відносно 1900
date.setYear(98);
date.toString(); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date.setYear(22);
date.toString(); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)

Таким чином, щоб створити й отримати дати між роками 0 і 99, натомість слід використовувати методи setFullYear() та getFullYear().

// Бажаний спосіб; ніколи не сприймає значення як відносні,
// проте натомість використовує значення як є
date.setFullYear(98);
date.getFullYear(); // 98 (не 1998)
date.setFullYear(22);
date.getFullYear(); // 22 (не 1922 і не 2022)

Обчислення часу, який минув

Наступний приклад ілюструє, як визначити час (в мілісекундах), що пройшов між двома датами в JavaScript.

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

// Використавши об'єкт дати
const start = Date.now();

// Зафіксуємо момент завершення події:
doSomethingForALongTime();
const end = Date.now();
const elapsed = end - start; // час, що минув, у мілісекундах

// Використавши вбудовані методи
const start = new Date();

// Зафіксуємо момент завершення події:
doSomethingForALongTime();
const end = new Date();
const elapsed = end.getTime() - start.getTime(); // час, що минув, у мілісекундах

// Отак перевіряємо функцію й отримуємо її вивід
function printElapsedTime(testFn) {
  const startTime = Date.now();
  const result = testFn();
  const endTime = Date.now();

  console.log(`Минуло часу: ${String(endTime - startTime)} мілісекунд`);
  return result;
}

const yourFunctionReturn = printElapsedTime(yourFunction);

Примітка: В браузерах, які мають підтримку Web Performance API — вимірів часу високої точності — метод Performance.now() надасть значно точніші й надійніші виміри часу, аніж Date.now().

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

const seconds = Math.floor(Date.now() / 1000);

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

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

Сумісність із браузерами

Дивіться також

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