JavaScript объект Date

Описание объекта

Объекты Date основаны на значении времени, которое является числом миллисекунд с 00:00:00 1 января 1970 UTC. Эти объекты обладают большим количеством методов для выполнения различных вычислений с участием дат. Числовая метка времени имеет одинаковый смысл на разных платформах; местное отображение и разбор нестандартных строк могут различаться. Значение времени может передаваться между системами для создания даты, представляющей один и тот же момент времени.

Объект Date поддерживает ряд UTC (универсальных) методов, а также методов локального времени. UTC — всемирное координированное время. Местное время определяется часовым поясом среды выполнения JavaScript. Сам объект хранит только метку времени, а не название часового пояса или исходное смещение. Для создания объектов Date в языке JavaScript имеется специальный конструктор Date(), который рассмотрен ниже.

Поддержка браузерами

Спецификация: ecma262

Поддерживается во всех основных браузерах с 2015 года.

Отдельные значения (1) поддерживаются не везде — смотрите таблицу.

Показать браузеры
Совместимостьjavascript.builtins.Date
ВозможностьКомпьютерыМобильные
ChromeEdgeFirefoxOperaSafariChrome AndroidFirefox for AndroidOpera AndroidSafari on iOSSamsung BrowserWebView AndroidWebView on iOS
Date✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
@@toPrimitive✓47✓15✓44✓34✓10✓47✓44✓34✓10✓5.0✓47✓10
Date✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
UTC✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
monthIndex defaults to 0✓≤15✓≤15✓≤4✓15✓≤10.1✓18✓4✓14✓≤10.3✓1.0✓4.4✓≤10.3
getDate✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getDay✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getFullYear✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getHours✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getMilliseconds✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getMinutes✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getMonth✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getSeconds✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getTime✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getTimezoneOffset✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getUTCDate✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getUTCDay✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getUTCFullYear✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getUTCHours✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getUTCMilliseconds✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getUTCMinutes✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getUTCMonth✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getUTCSeconds✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
getYear✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
now✓1✓12✓1✓10.5✓4✓18✓4✓14✓4✓1.0✓4.4✓4
parse✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
ISO 8601 format✓6✓12✓4✓6✓5.1✓18✓4✓10.1✓5✓1.0✓4.4✓5
setDate✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setFullYear✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setHours✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setMilliseconds✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setMinutes✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setMonth✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setSeconds✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setTime✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setUTCDate✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setUTCFullYear✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setUTCHours✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setUTCMilliseconds✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setUTCMinutes✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setUTCMonth✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setUTCSeconds✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
setYear✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
toDateString✓1✓12✓1✓5✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
toGMTString✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
toISOString✓3✓12✓1✓10.5✓4✓18✓4✓11✓3.2✓1.0✓4.4✓3.2
toJSON✓3✓12✓1✓10.5✓4✓18✓4✓11✓3.2✓1.0✓4.4✓3.2
toLocaleDateString✓1✓12✓1✓5✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
IANA time zone names in timeZone option✓24✓14✓52✓15✓7✓25✓56✓14✓7✓1.5✓4.4✓7
locales parameter✓24✓12✓29✓15✓10✓25✓56✓14✓10✓1.5✓4.4✓10
options parameter✓24✓12✓29✓15✓10✓25✓56✓14✓10✓1.5✓4.4✓10
toLocaleString✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
IANA time zone names in timeZone option✓24✓14✓52✓15✓7✓25✓56✓14✓7✓1.5✓4.4✓7
locales parameter✓24✓12✓29✓15✓10✓25✓56✓14✓10✓1.5✓4.4✓10
options parameter✓24✓12✓29✓15✓10✓25✓56✓14✓10✓1.5✓4.4✓10
toLocaleTimeString✓1✓12✓1✓5✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
IANA time zone names in timeZone option✓24✓14✓52✓15✓7✓25✓56✓14✓7✓1.5✓4.4✓7
locales parameter✓24✓12✓29✓15✓10✓25✓56✓14✓10✓1.5✓4.4✓10
options parameter✓24✓12✓29✓15✓10✓25✓56✓14✓10✓1.5✓4.4✓10
toString✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
toTemporalInstant✓144✓144✓139✓128✓preview✓144✓139✓95××✓144×
toTimeString✓1✓12✓1✓5✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
toUTCString✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1
valueOf✓1✓12✓1✓3✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1

поддерживаетсяс ограниченияминет поддержкинет данных≤31 — не позднее версии 31

Синтаксис конструктора объекта

JavaScript
// Текущий момент, метка времени, строка или копия даты
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 могут быть созданы только путем вызова Date в качестве конструктора, в случае вызова в качестве обычной функции (без использования оператора new), то в качестве возвращаемого значения мы получим строку, а не объект Date. При таком вызове Date() (как функция - без оператора new) игнорирует любые переданные аргументы. В отличие от других типов объектов JavaScript, объекты Date не имеют литерального синтаксиса.

Конструктор Date(), вызванный без аргументов создаст объект Date со значением, которое будет соответствовать текущей дате и времени.

Если конструктору передается единственный числовой аргумент, то это значение используется как внутреннее числовое представление даты в миллисекундах. Это значение аналогично значению, которое возвращается с использованием метода getTime().

Если конструктору передается единственный строковый аргумент, то это значение рассматривается как строковое представление даты в формате, принимаемом методом parse().

Конструктору Date() допускается так же передать от двух до семи числовых аргументов, которые определяют индивидуальные настройки даты и времени. Используя этот синтаксис, обратите внимание на то, что все аргументы, кроме первых двух (год и месяц) не являются обязательными. Полное описание аргументов конструктора представлено ниже.

При передаче другого объекта Date создаётся независимая копия с той же меткой времени: new Date(dateObject). Простое присваивание переменной копирует ссылку на тот же объект.

В форме с несколькими аргументами компоненты задаются по местному времени. Неуказанный день равен 1, часы, минуты, секунды и миллисекунды — 0. Дробные компоненты усекаются; переполнение и отрицательные значения переносятся в соседние компоненты. Например, месяц 12 означает январь следующего года, а день 0 — последний день предыдущего месяца.

Значения параметров

Параметры конструктора Date
Параметр Описание
value Целое значение, представляющее количество миллисекунд с 00:00:00 1 января 1970 по UTC.
dateString Строковое значение, представляющее дату. Строка должна быть в формате, распознаваемом методом parse() ; для переносимого кода используйте стандартный формат даты и времени JavaScript, например 2024-01-15T12:00:00Z. Поддержка других форматов зависит от реализации.
dateObject Другой объект Date, значение времени которого нужно скопировать.
year Целое значение, представляющее год. Значения от 0 до 99 соответствуют годам с 1900 по 1999.
monthIndex Целое значение, представляющее месяц. Значение 0 соответствует январю, а 11 — декабрю.
day День месяца, заданный в виде целого значения от 1 до 31. Необязательный аргумент.
hours Часы, заданные в виде целого от 0 (полночь) до 23 (11 часов вечера). Необязательный аргумент.
minutes Целое значение от 0 до 59, представляющее минутный отрезок времени. Необязательный аргумент.
seconds Целое значение от 0 до 59, представляющее секундный отрезок времени. Необязательный аргумент.
milliseconds Целое значение от 0 до 999, представляющее миллисекундный отрезок времени. Необязательный аргумент.

UTC, местное время и недействительная дата

Строка только с датой (2024-01-15) означает полночь по UTC. Дата со временем без смещения (2024-01-15T12:00:00) задаёт местное время. Суффикс Z и смещения вроде +03:00 явно задают связь с UTC. В другом часовом поясе тот же момент может отображаться другим календарным днём.

Допустимы метки от −8,64 × 1015 до +8,64 × 1015 миллисекунд включительно. Отрицательные значения соответствуют моментам до 1970 года. Нераспознаваемая строка, NaN или выход за пределы диапазона дают объект Invalid Date; его можно проверить через Number.isNaN(date.getTime()).

Отсутствие аргумента и значение undefined различаются: new Date() создаёт текущую дату, а new Date(undefined) — недействительную. new Date(null) соответствует метке 0. Переполнение календарных компонентов нормализуется, поэтому конструктор сам по себе не является строгой проверкой календарного ввода.

Методы set* изменяют исходный объект и возвращают новую числовую метку времени. Операции по местному времени учитывают переходы на летнее и зимнее время: календарный день не всегда равен 24 часам. Для UTC используются методы с UTC в имени; для заданного количества миллисекунд — getTime() и setTime().

Свойства Date

Свойства Date
Свойство Описание
Date.prototype Общий прототип экземпляров даты, содержащий их методы. Это свойство конструктора; у экземпляра date.prototype по умолчанию отсутствует.
Date.prototype.constructor Унаследованная экземплярами ссылка на конструктор, исходно равная Date. Свойство можно переопределить, поэтому оно не гарантирует тип объекта.
Date.length Собственное свойство функции-конструктора: равно 7, числу формальных параметров. Не означает количество переданных аргументов или длительность.
Date.name Собственное свойство функции-конструктора: строка "Date".

У экземпляра даты нет стандартных собственных свойств для года, месяца или метки времени: эти данные читают и меняют методами. Внутреннее значение времени не является доступным свойством JavaScript. Общие унаследованные свойства Object и Function в таблицу не включены.

Методы объекта Date

Статические методы вызывают у Date: Date.now(), Date.parse(), Date.UTC(). Остальные перечисленные ниже методы вызывают у экземпляра, например date.getDate(). Методы чтения компонентов возвращают NaN для недействительной даты.

Статические методы

Статические методы Date
Метод Описание
Date.now() Возвращает числовое значение, соответствующее текущему времени - количество миллисекунд, прошедших с 00:00:00 1 января 1970 по UTC.
Date.parse() Анализирует строковое представление даты и возвращает количество миллисекунд, прошедших с 00:00:00 1 января 1970 года по UTC, или возвращает значение NaN (англ. Not-a-Number, "не число"), если строка не распознана или содержит недопустимые значения даты.
Date.UTC() Принимает компоненты даты как UTC и возвращает метку времени в миллисекундах, а не объект Date.

Методы экземпляра

Методы Date
Метод Описание
getDate() Возвращает числовое значение (1-31), которое соответствует дню месяца для указанной даты по местному времени.
getDay() Возвращает числовое значение (0-6), которое соответствует дню недели для указанной даты по местному времени.
getFullYear() Возвращает числовое значение, которое соответствует году из указанной даты по местному времени.
getHours() Возвращает числовое значение (0-23), которое соответствует определенному часу для указанной даты по местному времени.
getMilliseconds() Возвращает числовое значение (0-999), которое соответствует миллисекундам для указанной даты по местному времени.
getMinutes() Возвращает числовое значение (0-59), которое соответствует минутам для указанной даты по местному времени.
getMonth() Возвращает числовое значение (0-11), которое соответствует месяцу для указанной даты по местному времени.
getSeconds() Возвращает числовое значение (0-59), которое соответствует секундам для указанной даты по местному времени.
getTime() Возвращает числовое значение указанной даты в виде количества миллисекунд, прошедших с 00:00:00 1 января 1970 года по UTC.
getTimezoneOffset() Возвращает разность UTC − местное время в минутах для даты и часового пояса среды выполнения; при UTC+3 результат равен −180.
getUTCDate() Возвращает числовое значение (1-31), которое соответствует дню месяца для указанной даты по всемирному времени.
getUTCDay() Возвращает числовое значение (0-6), которое соответствует дню недели для указанной даты по всемирному времени.
getUTCFullYear() Возвращает числовое значение, которое соответствует году из указанной даты по всемирному времени.
getUTCHours() Возвращает числовое значение (0-23), которое соответствует часу для указанной даты по всемирному времени.
getUTCMilliseconds() Возвращает числовое значение (0-999), которое соответствует миллисекундам для указанной даты по всемирному времени.
getUTCMinutes() Возвращает числовое значение (0-59), которое соответствует минутам для указанной даты по всемирному времени.
getUTCMonth() Возвращает числовое значение (0-11), которое соответствует месяцу для указанной даты по всемирному времени.
getUTCSeconds() Возвращает числовое значение (0-59), которое соответствует секундам для указанной даты по всемирному времени.
setDate() Устанавливает день месяца для указанной даты по местному времени.
setFullYear() Устанавливает полный год для указанной даты по местному времени.
setHours() Устанавливает часы для указанной даты по местному времени.
setMilliseconds() Устанавливает миллисекунды для указанной даты по местному времени.
setMinutes() Устанавливает минуты для указанной даты по местному времени.
setMonth() Устанавливает месяц для указанной даты по местному времени.
setSeconds() Устанавливает секунды для указанной даты по местному времени.
setTime() Устанавливает для объекта Date значение времени, представленное числом миллисекунд с 00:00:00 1 января 1970 года по UTC.
setUTCDate() Устанавливает день месяца для указанной даты по всемирному времени.
setUTCFullYear() Устанавливает полный год для указанной даты по всемирному времени.
setUTCHours() Устанавливает часы для указанной даты по всемирному времени.
setUTCMilliseconds() Устанавливает миллисекунды для указанной даты по всемирному времени.
setUTCMinutes() Устанавливает минуты для указанной даты по всемирному времени.
setUTCMonth() Устанавливает месяц для указанной даты по всемирному времени.
setUTCSeconds() Устанавливает секунды для указанной даты по всемирному времени.
toDateString() Возвращает часть, содержащую только дату объекта Date в виде удобочитаемой строки.
toISOString() Возвращает строку в формате ISO по UTC; для недействительной даты выбрасывает RangeError.
toJSON() Возвращает строку ISO по UTC через toISOString() или null для недействительной даты. Автоматически вызывается при JSON.stringify().
toLocaleDateString() Возвращает строку с чувствительным к локале представлением части даты на основе системных параметров.
toLocaleString() Возвращает строку с чувствительным к локале представлением даты.
toLocaleTimeString() Возвращает строку с чувствительным к локале представлением временной части даты на основе системных параметров.
toString() Возвращает строку, представляющую указанный объект Date.
toTimeString() Возвращает часть времени, содержащую только время объекта Date в виде человеко-читаемой строки на американском английском.
toUTCString() Преобразует дату в строку с использованием часового пояса UTC.
valueOf() Возвращает числовую метку времени в миллисекундах или NaN, как getTime().
toTemporalInstant() Создаёт Temporal.Instant для того же момента времени. Поддержка ограничена: перед вызовом проверяйте typeof date.toTemporalInstant === "function". Для недействительной даты выбрасывает RangeError. Описан в спецификации Temporal.
[Symbol.toPrimitive](hint) Участвует в приведении даты к примитиву. При hint = "number" сначала вызывает valueOf(), затем toString(); при "string" или "default" — в обратном порядке. Используется первый результат-примитив.
getYear() Устарело Возвращает местный год минус 1900. Используйте getFullYear(). Сохранён для совместимости со старым кодом; описан в приложении B ECMAScript.
setYear() Устарело Устанавливает местный год, трактуя значения от 0 до 99 как 1900–1999. Используйте setFullYear(). Сохранён для совместимости со старым кодом; описан в приложении B ECMAScript.
toGMTString() Устарело Устаревшее имя того же метода, что и toUTCString(). В новом коде используйте toUTCString(). Сохранён для совместимости со старым кодом; описан в приложении B ECMAScript.

Спецификация

ECMAScript — Date Objects.

Примеры, попробуйте сами

Создание и копирование даты

Сравните число, строку и объект Date. Изменение копии не затрагивает исходную дату.

index.html
HTML
<p>Результат выполнения выводится в консоль.</p>
main.js
JavaScript
const original = new Date('2024-01-15T12:00:00Z')
const fromNumber = new Date(original.getTime())
const copy = new Date(original)
console.log(fromNumber.toISOString()) // "2024-01-15T12:00:00.000Z"
console.log(copy === original) // false
copy.setUTCDate(16)
console.log(original.toISOString()) // "2024-01-15T12:00:00.000Z"
console.log(copy.toISOString()) // "2024-01-16T12:00:00.000Z"
console.log(typeof Date()) // "string"
console.log(new Date() instanceof Date) // true

Компоненты даты и нормализация

Месяцы начинаются с 0; неуказанный день равен 1. Сравните переполнение месяца и года.

index.html
HTML
<p>Результат выполнения выводится в консоль.</p>
main.js
JavaScript
console.log(new Date(2024, 0).toDateString()) // "Mon Jan 01 2024"
console.log(new Date(2024, 12, 1).toDateString()) // "Wed Jan 01 2025"
console.log(new Date(2024, 2, 0).toDateString()) // "Thu Feb 29 2024"
const earlyYear = new Date(20, 0, 1)
console.log(earlyYear.getFullYear()) // 1920
earlyYear.setFullYear(20)
console.log(earlyYear.getFullYear()) // 20

UTC и местное время

Сравните дату без времени с местной полуночью. Явное смещение задаёт один и тот же момент во всех часовых поясах.

index.html
HTML
<p>Результат выполнения выводится в консоль.</p>
main.js
JavaScript
const utc = new Date('2024-01-15')
const local = new Date(2024, 0, 15)
console.log(utc.toISOString()) // "2024-01-15T00:00:00.000Z"
console.log(local.toISOString()) // Зависит от часового пояса браузера.
console.log(local.getHours()) // 0
console.log(new Date('2024-01-15T03:00:00+03:00').getTime() === utc.getTime()) // true
console.log(new Date(Date.UTC(2024, 0, 15)).toISOString()) // "2024-01-15T00:00:00.000Z"

Недействительная дата

Сравните undefined, null и выход за пределы допустимой метки времени.

index.html
HTML
<p>Результат выполнения выводится в консоль.</p>
main.js
JavaScript
console.log(Number.isNaN(new Date(undefined).getTime())) // true
console.log(new Date(null).toISOString()) // "1970-01-01T00:00:00.000Z"
console.log(Number.isNaN(new Date('not a date').getTime())) // true
console.log(Number.isNaN(new Date(8640000000000001).getTime())) // true
console.log(new Date(NaN).toJSON()) // null