Конструктор 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 представляє поточні дату й час на мить свого створення. Мітка часу поверненої дати – така сама, як число, повернене Date.now().

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

value

Значення – ціле число, що представляє мітку часу (число мілісекунд від півночі на початку 1 січня 1970 року за Всесвітнім координованим часом – також відоме як епоха).

Рядок дати

dateString

Рядкове значення, що представляє дату і розбирається та тлумачиться згідно з тим самим форматом, що реалізований Date.parse(). Застереження щодо використання різних форматів дивіться в форматі рядків дати й часу.

Об'єкт Date

dateObject

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

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

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

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

Якщо будь-який параметр переповнює свої визначені межі, він "переноситься". Наприклад, якщо переданий 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", а метод valueOf() повертає NaN).

Виклик функції 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"); // Стандартизований і надійний спосіб
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