JS об'єкт Date

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

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

Максимальна часова мітка, яку може представити об'єкт 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, яке є "недійсною датою".

console.log(new Date(8.64e15).toString()); // "Сб, 13 вересня 275760 00:00:00 GMT+0000 (UTC)"
console.log(new Date(8.64e15 + 1).toString()); // Недійсна дата

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

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

правити

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

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

Наприклад, часова мітка 0 відображає унікальний момент в історії, але його можна розглядати двома способами:

• Як UTC-час, це 1 січня 1970 року за UTC;
• Як місцевий час в Нью-Йорку (UTC-5), це 19:00:00 31 грудня 1969 року.

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

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

Коли який-небудь сегмент виходить за очікуваний діапазон, він зазвичай "перекидається на" або "забирає у" вищий сегмент. Наприклад, якщо місяць встановлено як 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 - літерний символ, який вказує початок часової частини рядка. 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, але не могла бути змінена через сумісність вебу. Див. Питання некоректного парсера – реальна проблема вебу.

правити

Порада

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

автор: Bond правити

Нотатка

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

автор: Bond правити

Нотатка

Деякі методи, зокрема конструктор Date(), Date.UTC() та застарілі методи getYear()/ setYear(), інтерпретують двозначний рік як рік у 1900-х. Наприклад, new Date(99, 5, 24) інтерпретується як 24 червня 1999 року, а не 24 червня 99 року.

автор: Bond правити

Нотатка

Існують деякі формати, які підтримуються у всіх основних реалізаціях - наприклад, формат RFC 2822 - тому їх використання може бути прийнятним. Завжди проводьте тестування в різних браузерах, щоб переконатися, що ваш код працює у всіх цільових браузерах.

автор: Bond правити

+ додати пораду чи нотатку

Синтаксис

var d = new Date();
var d = new Date(date string);

var d = new Date(year,month);
var d = new Date(year,month,day);
var d = new Date(year,month,day,hours);
var d = new Date(year,month,day,hours,minutes);
var d = new Date(year,month,day,hours,minutes,seconds);
var d = new Date(year,month,day,hours,minutes,seconds,ms);

var d = new Date(milliseconds);

методи

властивості

Переглядачі

Стаціонарні переглядачі Мобільні переглядачі Серверні переглядачі

Підтримка: стаціонарні переглядачі

Переглядач
	1	1	1	3	12

Підтримка: мобільні переглядачі

Переглядач
	4.4	18	4	1

Підтримка: серверні переглядачі

Переглядач
	0.10.0	1.0

Приклади

+ запропонувати свій приклад у пісочниці

// умовна тривала операція для прикладу
function doSomethingForALongTime() {
    for (let i = 0; i < 1e6; i++);
}

const start = Date.now();

// Тут відбувається подія, тривалість якої необхідно засікти:
doSomethingForALongTime();

const end = Date.now();
const elapsed = end - start; // минулий час у мілісекундах

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

const date = new Date("2020-05-12T23:50:21.817Z");
date.toString(); // Вівторок, 12 травня 2020 р. 18:50:21 GMT-0500 (Центральний літній час)
date.toDateString(); // Вівторок, 12 травня 2020 р.
date.toTimeString(); // 18:50:21 GMT-0500 (Центральний літній час)
date[Symbol.toPrimitive]("string"); // Вівторок, 12 травня 2020 р. 18:50:21 GMT-0500 (Центральний літній час)

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

date.toUTCString(); // Вів, 12 трав 2020 23:50:21 GMT

date.toLocaleString(); // 12.05.2020, 18:50:21
date.toLocaleDateString(); // 12.05.2020
date.toLocaleTimeString(); // 18: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]