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, але не могла бути змінена через сумісність вебу. Див. Питання некоректного парсера – реальна проблема вебу.

Синтаксис

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
• Приклад 2
• Приклад 3
• Приклад 4

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]

const start = Date.now();

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

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

Методи

getMilliseconds()

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

getDay()

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

getMinutes()

Повертає хвилини від 0 до 59 з об'єкта дати згідно з місцевим часом.

getUTCDay()

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

getDate()

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

getFullYear()

Повертає чотиризначний рік зазначеної дати відповідно до місцевого часу.

getHours()

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

constructor()

Створює новий об'єкт дати, представляючи поточний момент часу або конкретний час, заданий параметрами.

getTime()

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

getUTCFullYear()

Повертає рік вказаної дати за координованим універсальним часом (UTC).

getUTCHours()

Повертає годину (від 0 до 23) заданої дати за часовим поясом UTC.

getUTCDate()

Повертає день місяця (від 1 до 31) для заданої дати відповідно до UTC.

getSeconds()

Повертає секунди (від 0 до 59) конкретного моменту часу, представленого об'єктом дати.

setDate()

Встановлює день місяця для зазначеного об'єкта дати.

getMonth()

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

parse()

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

setFullYear()

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

getUTCMinutes()

Повертає хвилини (від 0 до 59) вказаної дати за координованим всесвітнім часом (UTC).

getUTCMilliseconds()

Отримує мілісекунди поточної дати згідно з універсальним координованим часом (UTC).

toLocaleDateString()

Конвертує дату у строкове представлення, відформатоване згідно з локальними налаштуваннями.

toString()

Перетворює об'єкт дати в рядок у стандартному форматі.

toLocaleTimeString()

Перетворює час з дати об'єкта в рядок, представляючи час відповідно до локального часового поясу.

toTimeString()

Перетворює час з об’єкта дати в рядок, представляючи тільки часову частину дати, відповідно до часового поясу комп’ютера користувача.

valueOf()

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

toLocaleString()

Перетворює дату та час у рядок згідно з локальними налаштуваннями користувача.

toUTCString()

Перетворює дату та час в рядок, відображаючи їх у форматі UTC.

setUTCHours()

Встановлює годину для дати відповідно до універсального координованого часу (UTC).

setUTCMonth()

Встановлює місяць для дати за координованим всесвітнім часом (UTC).

UTC()

Перетворює вказані дату і час в мілісекунди з 1970 року за UTC.

setUTCMilliseconds()

Встановлює мілісекунди для дати, враховуючи координований світовий час (UTC).

setUTCSeconds()

Встановлює секунди для дати за координованим всесвітнім часом (UTC).

toJSON()

Перетворює об'єкт дати в рядок у форматі JSON.

setUTCMinutes()

Встановлює хвилини для дати, враховуючи координований світовий час (UTC).

toDateString()

Повертає строкове представлення дати.

setHours()

Встановлює години для вказаного об'єкта дати, змінюючи його на місці.

setMonth()

Встановлює місяць для вказаної дати.

toISOString()

Конвертує дату в рядок за стандартом ISO 8601, представляючи дату та час в UTC.

setMilliseconds()

Встановлює мілісекунди для вказаної дати.

setSeconds()

Встановлює секунди для вказаної дати.

setUTCFullYear()

Встановлює рік для дати відповідно до універсального координованого часу (UTC).

setMinutes()

Змінює хвилини для заданого об'єкта дати, зберігаючи інші елементи дати незмінними.

setTime()

Дозволяє встановити час (в мілісекундах від 1 січня 1970 року UTC) для об’єкта дати.

setUTCDate()

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

getUTCSeconds()

Повертає секунди (від 0 до 59) конкретного моменту часу за UTC.

now()

Повертає поточний час в мілісекундах з моменту початку епохи Unix (1 січня 1970 року).

getUTCMonth()

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

getTimezoneOffset()

Повертає різницю в хвилинах між місцевим часом та Універсальним координованим часом (UTC).

Властивості

prototype

Дозволяє додавати методи та властивості до об'єктів дати, які можуть бути використані екземплярами цих об'єктів.