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

Конструктор Date() може або створити примірник Date, або повернути рядкове представлення поточного часу.

Спробуйте його в дії

Синтаксис

new Date()
new Date(value)
new Date(dateString)
new Date(dateObject)

new Date(year, monthIndex)
new Date(year, monthIndex, day)
new Date(year, monthIndex, day, hours)
new Date(year, monthIndex, day, hours, minutes)
new Date(year, monthIndex, day, hours, minutes, seconds)
new Date(year, monthIndex, day, hours, minutes, seconds, milliseconds)

Date()

Примітка: Date() можна викликати і з, і без new, але з різними наслідками. Дивіться Повернене значення.

Параметри

Є п'ять базових форм виклику конструктора Date():

Без параметрів

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

Значення часу або мітка часу

value

Ціле число, що представляє число мілісекунд від 1 січня 1970 року, 00:00:00 за Всесвітнім координованим часом (епоха ECMAScript, рівносильна щодо епохи UNIX), без урахування високосних секунд. Слід мати на увазі, що більшість функцій мітки часу UNIX (англ.) точні лише до секунд.

Рядок дати

dateString

Рядкове значення, що представляє дату, у форматі, зрозумілому методові Date.parse(). (Специфікація ECMA262 описує спрощену версію ISO 8601 (англ.), проте інші формати можуть бути визначені реалізацією, в тому числі, зазвичай, сумісні з IETF часові мітки RFC 2822 (англ.).)

Примітка: При розборі рядків дати за допомогою конструктора Date (і Date.parse, що рівносильно) завжди слід пересвідчуватися, що введення відповідає форматові ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ): логіка розбору інших форматів визначається реалізацією та може не працювати на всіх браузерах. Підтримка рядків формату RFC 2822 (англ.) є наслідком лишень домовленості. Для обробки інших форматів може бути доцільним використати сторонню бібліотеку.

Рядки лише з датою (наприклад, "1970-01-01") обробляються за Всесвітнім координованим часом, натомість рядки з датою і часом (наприклад, "1970-01-01T12:00") обробляються за місцевим. Таким чином, краще пересвідчитись, що формат вхідних даних є сталим.

Об'єкт Date

dateObject

Наявний об'єкт Date. Фактично створюється копія наявного об'єкта Date, з такими ж датою й часом. Це рівносильно new Date(dateObject.valueOf()), окрім того, що метод valueOf() не викликається.

Коли в Date() передається один параметр, примірники Date обробляються по-особливому. Всі решта значень перетворюються на примітиви. Якщо результат є рядком, то він розбирається як рядок дати. Інакше – результівний примітив далі зводиться до числа й обробляється як мітка часу.

Значення окремих компонент дати й часу

Отримавши принаймні рік та місяць, ця форма Date() повертає об'єкт Date, чиї значення компонент (рік, місяць, день, година, хвилина, секунда й мілісекунда) походять від наступних параметрів. Усі відсутні поля отримують найменше можливе значення (1 для day і 0 для решти компонент). Значення параметрів обчислюються відносно місцевого часового поясу, а не Всесвітнього координованого часу.

Якщо будь-який параметр переповнює свої визначені межі, він "переноситься". Наприклад, якщо переданий monthIndex, більший за 11, то це змусить рік збільшитись на одиницю; якщо переданий minutes більший за 59, то відповідно збільшиться hours тощо. Таким чином, new Date(1990, 12, 1) поверне 1 січня 1991 року; new Date(2020, 5, 19, 25, 65) поверне 2:05 20 червня 2020 року.

Аналогічно, якщо якийсь параметр нижчий меж допустимих значень, він "запозичує" з вищих позицій. Наприклад, new Date(2020, 5, 0) поверне 31 травня 2020 року.

year

Ціле число, що представляє рік. Значення від 0 до 99 відповідають рокам від 1900 до 1999. Всі решта значень тотожні відповідним рокам. Дивіться приклад.

monthIndex

Ціле число, що представляє місяць, починаючи від 0 для січня і до 11 для грудня.

day Необов'язкове

Ціле число, що представляє день місяця. Усталене значення – 1.

hours Необов'язкове

Ціле число між 0 і 23, що представляє годину дня. Усталене значення – 0.

minutes Необов'язкове

Ціле число, що представляє хвилинний сегмент миті часу. Усталене значення – 0 хвилин після години.

seconds Необов'язкове

Ціле число, що представляє секундний сегмент миті часу. Усталене значення – 0 секунд після хвилини.

milliseconds Необов'язкове

Ціле число, що представляє мілісекундний сегмент миті часу. Усталене значення – 0 мілісекунд після секунди.

Повернене значення

Виклик new Date() (конструктора Date()) повертає об'єкт Date. Якщо викликати його з недійсним рядком часу, або якщо дата матиме мітку часу UNIX, меншу за -8,640,000,000,000,000 або більшу за 8,640,000,000,000,000 мілісекунд, то він поверне об'єкт Date, чий метод toString() повертатиме буквальний рядок Invalid Date.

Виклик функції Date() (без ключового слова new) повертає рядкове представлення поточних дати та часу, точно так само, як це робить new Date().toString(). Будь-які аргументи, передані при виклику функції Date() (без ключового слова new) ігноруються; незалежно від того, чи була вона викликана з недійсним рядком дати – або навіть з будь-яким довільним об'єктом чи іншим примітивом як аргументом – вона завжди повертає рядкове представлення поточних дати й часу.

Приклади

Декілька способів створити об'єкт Date

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

const today = new Date();
const birthday = new Date("December 17, 1995 03:24:00"); // КРАЩЕ НЕ ТРЕБА: може працювати не у всіх середовищах виконання
const birthday = new Date("1995-12-17T03:24:00"); // Відповідає ISO-8601 і працюватиме надійно
const birthday = new Date(1995, 11, 17); // місяці нумеруються від 0
const birthday = new Date(1995, 11, 17, 3, 24, 0);
const birthday = new Date(628021800000); // передача мітки часу епохи

Передача значення, що не є ані Date, ані рядком, ані числом

Якщо конструктор Date() викликається з одним параметром, що не є примірником Date, цей параметр буде зведений до примітива, а потім буде перевірено, чи є цей примітив рядком. Наприклад, new Date(undefined) – не те саме, що new Date():

console.log(new Date(undefined)); // Invalid Date

Річ у тому, що undefined – це примітив, але не рядок, тому це значення зводиться до числа, тобто NaN, а отже – не є дійсною міткою часу. З іншого боку, null зводиться до 0.

console.log(new Date(null)); // 1970-01-01T00:00:00.000Z

Масиви зводяться до рядка за допомогою Array.prototype.toString(), котрий склеює елементи комами. Проте результівний рядок будь-якого масиву, в котрому більш ніж один елемент, не є дійсним рядком дати ISO 8601, тож логіка його розбору залежить від реалізації. Не слід передавати в конструктор Date() масиви.

console.log(new Date(["2020-06-19", "17:13"]));
// 2020-06-19T17:13:00.000Z у Chrome, адже він розуміє "2020-06-19,17:13"
// "Invalid Date" у Firefox

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

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

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

• Date