Date

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

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

Опис

Епоха, мітки часу та недійсна дата

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

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

Максимальна мітка часу, яку може представити об'єкт Date, трохи менша за максимальне безпечне ціле число (Number.MAX_SAFE_INTEGER, яке дорівнює 9.007.199.254.740.991). Об'єкт Date може представляти максимум ±8.640.000.000.000.000 мілісекунд, або ±100 000 000 (сто мільйонів) днів відносно епохи. Це діапазон від 20 квітня 271821 року до н.е. до 13 вересня 275760 року н.е.. Будь-яка спроба представити час за межами цього діапазону дає об'єкт Date, що містить значення мітки часу NaN, що є "Invalid Date" (недійсною датою).

console.log(new Date(8.64e15).toString()); // "Sat Sep 13 275760 03:00:00 GMT+0300 (Eastern European Summer Time)"
console.log(new Date(8.64e15 + 1).toString()); // "Invalid Date"

Є різні методи, що дозволяють взаємодіяти з міткою часу, що зберігається в даті:

• Взаємодіяти зі значенням мітки часу безпосередньо можна за допомогою методів getTime() і setTime().
• Методи valueOf() і [@@toPrimitive]() (при передачі "number") – котрі автоматично викликаються при зведенні до числа – повертають мітку часу, що призводить до того, що об'єкти Date поводяться як їх мітки часу при використанні в числових контекстах.
• Усі статичні методи (Date.now(), Date.parse() і Date.UTC()) повертають мітки часу замість об'єктів Date.
• Конструктор Date() може бути викликаний з міткою часу як єдиним аргументом.

Компоненти дати та часові зони

Дата за лаштунками представлена як єдине число, мітка часу. При взаємодії з нею, мітка часу потребує тлумачення як структуроване представлення дати та часу. Існує два способи інтерпретації мітки часу: як локальний час чи як Координований всесвітній час (UTC), глобальний стандартний час, визначений Світовим часовим стандартом. Локальна часова зона не зберігається в об'єкті дати, а визначається середовищем виконання (пристроєм користувача).

Примітка: UTC не слід плутати з Середнім часом за Гринвічем (GMT), тому що вони не завжди рівні: це докладніше пояснено на сторінці Вікіпедії, на яку веде посилання. Наприклад, мітка часу 0 представляє унікальний момент в історії, але її можна тлумачити двома способами:

• Як час UTC, це північ на початку 1 січня 1970 року, UTC,
• Як локальний час у Києві (UTC+2), це 02:00:00 1 січня 1970 року.

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

Є дві групи методів Date: одна група отримує та задає різні компоненти дати, тлумачачи мітку часу як локальний час, а інша – використовує UTC.

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

Примітка: Частина методів, включно з конструктором Date(), Date.UTC() та нерекомендованими методами getYear()/setYear(), тлумачать двозначний рік як рік 1900-х. Наприклад, new Date(99, 5, 24) тлумачиться як 24 червня 1999 року, а не 24 червня 99 року. Дивіться більше інформації про це в Інтерпретації двоцифрових років. Коли сегмент перевищує або не досягає очікуваного діапазону, він зазвичай "переноситься" або "позичає" зі старшого сегмента. Наприклад, якщо місяць задано як 12 (місяці нумеруються з нуля, тому грудень - це 11), він стає січнем наступного року. Якщо день місяця задано як 0, він стає останнім днем попереднього місяця. Це також стосується дат, заданих у форматі рядка дати та часу.

Формат рядка дати та часу

Є чимало способів форматування дати як рядка. Специфікація JavaScript визначає лише один формат, який повинен мати повсюдну підтримку – формат рядка дати та часу, спрощення розширеного формату календарної дати ISO 8601. Цей формат – наступний:

YYYY-MM-DDTHH:mm:ss.sssZ

• YYYY – це рік, з чотирма цифрами (від 0000 до 9999), або як розширений рік з + або - перед шістьома цифрами. Для розширених років знак обов'язковий. -000000 явно заборонено як дійсний рік.
• MM – це місяць, з двома цифрами (від 01 до 12). Усталено – 01.
• DD – це день місяця, з двома цифрами (від 01 до 31). Усталено – 01.
• T – це буквальний символ, котрий позначає початок часової частини рядка. Він обов'язковий при заданні часової частини.
• HH – це година, з двома цифрами (від 00 до 23). Як особливий випадок, допускається 24:00:00 – він тлумачиться як північ на початку наступного дня. Усталено – 00.
• mm – це хвилина, з двома цифрами (від 00 до 59). Усталено – 00.
• ss – це секунда, з двома цифрами (від 00 до 59). Усталено – 00.
• sss – це мілісекунда, з трьома цифрами (від 000 до 999). Усталено – 000.
• Z – це зміщення часового поясу, котре може бути буквальним символом Z (що позначає UTC), або + або - перед HH:mm, зміщенням в годинах та хвилинах від UTC.

Можна пропускати різні компоненти, тому наступні рядки є дійсними:

• Форма суто дати: YYYY, YYYY-MM, YYYY-MM-DD
• Форма дати та часу: одна з вищезазначених форм суто дати, за якою слідує T, за якою слідує HH:mm, HH:mm:ss або HH:mm:ss.sss. Після кожної з комбінацій може стояти зміщення часової зони.

Наприклад, і "2011-10-10" (форма суто дати), і "2011-10-10T14:48:00" (форма дати та часу), і "2011-10-10T14:48:00.000+09:00" (форма дати та часу з мілісекундами та часовою зоною) – дійсні рядки дати та часу.

Коли зміщення часової зони – відсутнє, форми суто дати тлумачаться як UTC, а форми дати та часу – як місцевий час. Причина цього – історична помилка специфікації, котра не була узгоджена з ISO 8601, але не могла бути змінена у зв'язку з сумісністю з вебом. Дивіться Зламаний розбирач – Проблема дійсності Вебу.

І Date.parse(), і конструктор Date() приймають як вихідні дані рядки в форматі дати та часу. Крім того, реалізації можуть підтримувати інші формати дати, коли вхідні дані не відповідають цьому формату.

Примітка: Рекомендується пересвідчуватися, що вихідні дані відповідають вищеописаному форматові рядка дати та часу, – заради максимальної сумісності, тому що підтримка інших форматів – не гарантована. Проте є деякі формати, що підтримуються в усіх головних реалізаціях – наприклад, формат RFC 2822 – у випадку чого їх використання може бути прийнятним. Слід завжди проводити кросбраузерне тестування, аби пересвідчитися, що код працює в усіх цільових браузерах. Якщо потрібно враховувати багато різних форматів, може допомогти бібліотека. Метод toISOString() повертає рядкове представлення дати у форматі рядка дати та часу, зі зміщенням часової зони, завжди заданим як Z (UTC).

Інші способи форматувати дату

• toISOString() повертає рядок у форматі 1970-01-01T00:00:00.000Z (форматі рядка дати та часу, що був введений вище, і який є спрощеним варіантом ISO 8601). toJSON() викликає toISOString() і повертає результат.
• toString() повертає рядок у форматі Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time), а toDateString() та toTimeString() повертають, відповідно, частини дати та часу такого рядка. [@@toPrimitive]() (коли йому передати "string" або "default") викликає toString() і повертає результат.
• toUTCString() повертає рядок у форматі Thu, 01 Jan 1970 00:00:00 GMT (узагальненому RFC 7231).
• toLocaleDateString(), toLocaleTimeString() і toLocaleString() використовують специфічні для локалі формати дати та часу, які зазвичай надаються з боку API Intl.

Дивіться приклади в розділі Формати значень, повернених методом toString.

Конструктор

Date()

Коли викликається як конструктор — повертає новий об'єкт Date. Коли викликається як функція — повертає поточні дату і час, оформлені у рядок.

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

Date.now()

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

Date.parse()

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

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.prototype[@@toPrimitive]()

Перетворює цей об'єкт Date на примітивне значення.

Приклади

Декілька способів створити об'єкт 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[Symbol.toPrimitive]("string"); // Wed May 13 2020 02:50:21 GMT+0300 (Eastern European Summer Time)

date.toISOString(); // 2020-05-12T23:50:21.817Z
date.toJSON(); // 2020-05-12T23:50:21.817Z

date.toUTCString(); // Tue, 12 May 2020 23:50:21 GMT

date.toLocaleString(); // 13/05/2020, 02:50:21
date.toLocaleDateString(); // 13/05/2020
date.toLocaleTimeString(); // 02:50:21

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

const date = new Date("2000-01-17T16:45:30");
const [month, day, year] = [
  date.getMonth(),
  date.getDate(),
  date.getFullYear(),
];
// [0, 17, 2000], оскільки місяці нумеруються від 0
const [hour, minutes, seconds] = [
  date.getHours(),
  date.getMinutes(),
  date.getSeconds(),
];
// [16, 45, 30]

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

Конструктор 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()