Дата

Объекты JavaScript Date представляют собой один момент времени в платформенно-независимом формате. Объекты Date инкапсулируют целое число, которое представляет миллисекунды, прошедшие с полуночи 1 января 1970 года по UTC (эпоха).

Описание

Эпоха, метки времени и неверная дата

Дата в 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()); // "Sat Sep 13 275760 00:00:00 GMT+0000 (Coordinated Universal Time)"
console.log(new Date(8.64e15 + 1).toString()); // "Invalid Date"

Существуют различные методы, позволяющие взаимодействовать с меткой времени, хранящейся в дате:

• Вы можете взаимодействовать со значением метки времени напрямую, используя методы getTime() и setTime().
• Методы valueOf() и [Symbol.toPrimitive]() (при передаче "number") — которые автоматически вызываются при приведении к числу — возвращают метку времени, заставляя объекты Date вести себя как их метки времени при использовании в числовых контекстах.
• Все статические методы (Date.now(), Date.parse() и Date.UTC()) возвращают метки времени вместо объектов Date.
• Конструктор Date() может быть вызван с меткой времени в качестве единственного аргумента.

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

Дата внутренне представлена как одно число, метка времени. При взаимодействии с ней метка времени должна быть интерпретирована как структурированное представление даты и времени. Всегда есть два способа интерпретировать метку времени: как локальное время или как Всемирное координированное время (UTC), глобальный стандарт времени, определенный Всемирным стандартом времени. Локальный часовой пояс не хранится в объекте даты, но определяется хост-средой (устройством пользователя).

Например, метка времени 0 представляет уникальный момент в истории, но ее можно интерпретировать двумя способами:

• Как время UTC, это полночь в начале 1 января 1970 года, UTC,
• Как локальное время в Нью-Йорке (UTC-5), это 19:00:00 31 декабря 1969 года.

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

Существует две группы методов Date: одна группа получает и устанавливает различные компоненты даты, интерпретируя метку времени как локальное время, в то время как другая использует UTC.

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

Когда сегмент переполняет или не достигает своего ожидаемого диапазона, он обычно «переносится» или «заимствуется» из более высокого сегмента. Например, если месяц установлен на 12 (месяцы начинаются с нуля, поэтому декабрь — это 11), он становится январем следующего года. Если день месяца установлен на 0, он становится последним днем предыдущего месяца. Это также относится к датам, заданным в формате строки даты и времени.

При попытке установить локальное время на время, попадающее в переход смещения (обычно переход на летнее время), точное время определяется с использованием того же поведения, что и опция disambiguation: "compatible" в Temporal. То есть, если локальное время соответствует двум моментам, выбирается более ранний; если локальное время не существует (имеется пробел), мы продвигаемся вперед на длительность пробела.

// Assume America/New_York local time zone
// 2024-03-10 02:30 is within the spring-forward transition and does not exist
// 01:59 (UTC-5) jumps to 03:00 (UTC-4), so 02:30 moves forward by one hour
console.log(new Date(2024, 2, 10, 2, 30).toString());
// Sun Mar 10 2024 03:30:00 GMT-0400 (Eastern Daylight Time)

// 2024-11-03 01:30 is within the fall-back transition and exists twice
// 01:59 (UTC-4) jumps to 01:00 (UTC-5), so the earlier 01:30 (UTC-4) is chosen
console.log(new Date(2024, 10, 3, 1, 30).toString());
// Sun Nov 03 2024 01:30:00 GMT-0400 (Eastern Daylight Time)

Формат строки даты и времени

Существует множество способов форматирования даты в виде строки. Спецификация 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, а формы даты и времени интерпретируются как локальное время. Интерпретация как время UTC обусловлена исторической ошибкой в спецификации, которая не соответствовала ISO 8601, но не могла быть изменена из-за совместимости с вебом. См. Broken Parser – A Web Reality Issue.

Метод Date.parse() и конструктор Date() принимают строки в формате строки даты и времени в качестве входных данных. Кроме того, реализации могут поддерживать другие форматы даты, если входные данные не соответствуют этому формату.

Метод toISOString() возвращает строковое представление даты в формате строки даты и времени, при этом смещение часового пояса всегда установлено на Z (UTC).

Нестандартные строки могут быть проанализированы любым способом, желаемым реализацией, включая часовой пояс — большинство реализаций по умолчанию используют локальный часовой пояс. Реализации не обязаны возвращать неверную дату для компонентов даты, выходящих за границы диапазона, хотя обычно они это делают. Строка может содержать компоненты даты в пределах диапазона (с границами, определенными выше), но не представлять дату в действительности (например, «30 февраля»). В этом случае поведение реализаций непоследовательно. Страница Date.parse() предлагает больше примеров таких нестандартных случаев.

Другие способы форматирования даты

• toISOString() возвращает строку в формате 1970-01-01T00:00:00.000Z (формат строки даты и времени, представленный выше, который является упрощенным ISO 8601). toJSON() вызывает toISOString() и возвращает результат.
• toString() возвращает строку в формате Thu Jan 01 1970 00:00:00 GMT+0000 (Coordinated Universal Time), тогда как toDateString() и toTimeString() возвращают части строки, соответствующие дате и времени, соответственно. [Symbol.toPrimitive]() (при передаче "string" или "default") вызывает toString() и возвращает результат.
• toUTCString() возвращает строку в формате Thu, 01 Jan 1970 00:00:00 GMT (обобщенный RFC 7231).
• toLocaleDateString(), toLocaleTimeString() и toLocaleString() используют форматы даты и времени, специфичные для локали, обычно предоставляемые API Intl.

Примеры см. в разделе Форматы возвращаемых значений метода toString.

Конструктор

Date()

При вызове в качестве конструктора возвращает новый объект Date. При вызове в качестве функции возвращает строковое представление текущей даты и времени.

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

Date.now()

Возвращает числовое значение, соответствующее текущему времени — количество миллисекунд, прошедших с 1 января 1970 00:00:00 UTC, с игнорированием високосных секунд.

Date.parse()

Парсит строковое представление даты и возвращает количество миллисекунд, прошедших с 1 января 1970 00:00:00 UTC, с игнорированием високосных секунд.

Date.UTC()

Принимает те же параметры, что и самая длинная форма конструктора (т. е. от 2 до 7), и возвращает количество миллисекунд, прошедших с 1 января 1970 00:00:00 UTC, с игнорированием високосных секунд.

Свойства экземпляра

Эти свойства определены в Date.prototype и используются всеми экземплярами Date.

Date.prototype.constructor

Функция-конструктор, создавшая объект экземпляра. Для экземпляров Date начальным значением является конструктор Date.

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

Date.prototype.getDate()

Возвращает день месяца (1 – 31) для указанной даты в соответствии с локальным временем.

Date.prototype.getDay()

Возвращает день недели (0 – 6) для указанной даты в соответствии с локальным временем.

Date.prototype.getFullYear()

Возвращает год (4 цифры для 4-значных годов) указанной даты в соответствии с локальным временем.

Date.prototype.getHours()

Возвращает час (0 – 23) в указанной дате в соответствии с локальным временем.

Date.prototype.getMilliseconds()

Возвращает миллисекунды (0 – 999) в указанной дате в соответствии с локальным временем.

Date.prototype.getMinutes()

Возвращает минуты (0 – 59) в указанной дате в соответствии с локальным временем.

Date.prototype.getMonth()

Возвращает месяц (0 – 11) в указанной дате в соответствии с локальным временем.

Date.prototype.getSeconds()

Возвращает секунды (0 – 59) в указанной дате в соответствии с локальным временем.

Date.prototype.getTime()

Возвращает числовое значение указанной даты как количество миллисекунд, прошедших с 1 января 1970 00:00:00 UTC. (Отрицательные значения возвращаются для более раннего времени.)

Date.prototype.getTimezoneOffset()

Возвращает смещение часового пояса в минутах для текущей локали.

Date.prototype.getUTCDate()

Возвращает день (число) месяца (1 – 31) в указанной дате в соответствии со всемирным временем.

Date.prototype.getUTCDay()

Возвращает день недели (0 – 6) в указанной дате в соответствии со всемирным временем.

Date.prototype.getUTCFullYear()

Возвращает год (4 цифры для 4-значных годов) в указанной дате в соответствии со всемирным временем.

Date.prototype.getUTCHours()

Возвращает часы (0 – 23) в указанной дате в соответствии со всемирным временем.

Date.prototype.getUTCMilliseconds()

Возвращает миллисекунды (0 – 999) в указанной дате в соответствии со всемирным временем.

Date.prototype.getUTCMinutes()

Возвращает минуты (0 – 59) в указанной дате в соответствии со всемирным временем.

Date.prototype.getUTCMonth()

Возвращает месяц (0 – 11) в указанной дате в соответствии со всемирным временем.

Date.prototype.getUTCSeconds()

Возвращает секунды (0 – 59) в указанной дате в соответствии со всемирным временем.

Date.prototype.getYear() Устаревший

Возвращает год (обычно 2–3 цифры) в указанной дате в соответствии с локальным временем. Вместо этого используйте getFullYear().

Date.prototype.setDate()

Устанавливает день месяца для указанной даты в соответствии с локальным временем.

Date.prototype.setFullYear()

Устанавливает полный год (например, 4 цифры для 4-значных годов) для указанной даты в соответствии с локальным временем.

Date.prototype.setHours()

Устанавливает часы для указанной даты в соответствии с локальным временем.

Date.prototype.setMilliseconds()

Устанавливает миллисекунды для указанной даты в соответствии с локальным временем.

Date.prototype.setMinutes()

Устанавливает минуты для указанной даты в соответствии с локальным временем.

Date.prototype.setMonth()

Устанавливает месяц для указанной даты в соответствии с локальным временем.

Date.prototype.setSeconds()

Устанавливает секунды для указанной даты в соответствии с локальным временем.

Date.prototype.setTime()

Устанавливает объект Date на время, представленное количеством миллисекунд, прошедших с 1 января 1970 00:00:00 UTC. Используйте отрицательные числа для более раннего времени.

Date.prototype.setUTCDate()

Устанавливает день месяца для указанной даты в соответствии со всемирным временем.

Date.prototype.setUTCFullYear()

Устанавливает полный год (например, 4 цифры для 4-значных годов) для указанной даты в соответствии со всемирным временем.

Date.prototype.setUTCHours()

Устанавливает час для указанной даты в соответствии со всемирным временем.

Date.prototype.setUTCMilliseconds()

Устанавливает миллисекунды для указанной даты в соответствии со всемирным временем.

Date.prototype.setUTCMinutes()

Устанавливает минуты для указанной даты в соответствии со всемирным временем.

Date.prototype.setUTCMonth()

Устанавливает месяц для указанной даты в соответствии со всемирным временем.

Date.prototype.setUTCSeconds()

Устанавливает секунды для указанной даты в соответствии со всемирным временем.

Date.prototype.setYear() Устаревший

Устанавливает год (обычно 2–3 цифры) для указанной даты в соответствии с локальным временем. Вместо этого используйте setFullYear().

Date.prototype.toDateString()

Возвращает «дату» часть Date в виде удобочитаемой строки, например 'Thu Apr 12 2018'.

Date.prototype.toISOString()

Преобразует дату в строку в соответствии с расширенным форматом ISO 8601.

Date.prototype.toJSON()

Возвращает строку, представляющую Date с помощью toISOString(). Предназначен для неявного вызова с помощью JSON.stringify().

Date.prototype.toLocaleDateString()

Возвращает строку с зависящим от локали представлением части даты на основе системных настроек.

Date.prototype.toLocaleString()

Возвращает строку с зависящим от локали представлением этой даты. Переопределяет метод Object.prototype.toLocaleString().

Date.prototype.toLocaleTimeString()

Возвращает строку с зависящим от локали представлением части времени этой даты на основе системных настроек.

Date.prototype.toString()

Возвращает строку, представляющую указанный объект Date. Переопределяет метод Object.prototype.toString().

Date.prototype.toTemporalInstant()

Возвращает новый объект Temporal.Instant с тем же значением epochMilliseconds, что и метка времени этой даты.

Date.prototype.toTimeString()

Возвращает «временную» часть Date в виде удобочитаемой строки.

Date.prototype.toUTCString()

Преобразует дату в строку с использованием часового пояса UTC.

Date.prototype.valueOf()

Возвращает примитивное значение объекта Date. Переопределяет метод Object.prototype.valueOf().

Date.prototype[Symbol.toPrimitive]()

Преобразует этот объект Date в примитивное значение.

Примеры

Несколько способов создания объекта Date

Следующие примеры показывают несколько способов создания дат JavaScript:

const today = new Date();
const birthday = new Date("December 17, 1995 03:24:00"); // DISCOURAGED: may not work in all runtimes
const birthday2 = new Date("1995-12-17T03:24:00"); // This is standardized and will work reliably
const birthday3 = new Date(1995, 11, 17); // the month is 0-indexed
const birthday4 = new Date(1995, 11, 17, 3, 24, 0);
const birthday5 = new Date(628021800000); // passing epoch timestamp

Форматы возвращаемых значений метода toString

const date = new Date("2020-05-12T23:50:21.817Z");
date.toString(); // Tue May 12 2020 18:50:21 GMT-0500 (Central Daylight Time)
date.toDateString(); // Tue May 12 2020
date.toTimeString(); // 18:50:21 GMT-0500 (Central Daylight Time)
date[Symbol.toPrimitive]("string"); // Tue May 12 2020 18:50:21 GMT-0500 (Central Daylight Time)

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

date.toUTCString(); // Tue, 12 May 2020 23:50:21 GMT

date.toLocaleString(); // 5/12/2020, 6:50:21 PM
date.toLocaleDateString(); // 5/12/2020
date.toLocaleTimeString(); // 6:50:21 PM

Получение Даты, Месяца и Года или Времени

const date = new Date("2000-01-17T16:45:30");
const [month, day, year] = [
  date.getMonth(),
  date.getDate(),
  date.getFullYear(),
];
// [0, 17, 2000] as month are 0-indexed
const [hour, minutes, seconds] = [
  date.getHours(),
  date.getMinutes(),
  date.getSeconds(),
];
// [16, 45, 30]

Интерпретация двузначных годов

new Date() демонстрирует устаревшее нежелательное, непоследовательное поведение со значениями двузначного года; в частности, когда вызову new Date() передается значение двузначного года, это значение года не обрабатывается как буквальный год и не используется как есть, а вместо этого интерпретируется как относительное смещение — в некоторых случаях как смещение от года 1900, а в других случаях, как смещение от года 2000.

let date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date = new Date(22, 1); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)
date = new Date("2/1/22"); // Tue Feb 01 2022 00:00:00 GMT+0000 (GMT)

// Legacy method; always interprets two-digit year values as relative to 1900
date.setYear(98);
date.toString(); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date.setYear(22);
date.toString(); // Wed Feb 01 1922 00:00:00 GMT+0000 (GMT)

Таким образом, чтобы создавать и получать даты между годами 0 и 99, вместо этого используйте предпочтительные методы setFullYear() и getFullYear().

// Preferred method; never interprets any value as being a relative offset,
// but instead uses the year value as-is
date.setFullYear(98);
date.getFullYear(); // 98 (not 1998)
date.setFullYear(22);
date.getFullYear(); // 22 (not 1922, not 2022)

Вычисление прошедшего времени

Следующие примеры показывают, как определить прошедшее время между двумя датами JavaScript в миллисекундах.

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

// Using Date objects
const start = Date.now();

// The event to time goes here:
doSomethingForALongTime();
const end = Date.now();
const elapsed = end - start; // elapsed time in milliseconds

// Using built-in methods
const start = new Date();

// The event to time goes here:
doSomethingForALongTime();
const end = new Date();
const elapsed = end.getTime() - start.getTime(); // elapsed time in milliseconds

// To test a function and get back its return
function printElapsedTime(testFn) {
  const startTime = Date.now();
  const result = testFn();
  const endTime = Date.now();

  console.log(`Elapsed time: ${String(endTime - startTime)} milliseconds`);
  return result;
}

const yourFunctionReturn = printElapsedTime(yourFunction);

Получить количество секунд с начала эпохи ECMAScript

const seconds = Math.floor(Date.now() / 1000);

В этом случае важно вернуть только целое число, поэтому простого деления будет недостаточно. Также важно возвращать только фактически прошедшие секунды. (Вот почему этот код использует Math.floor(), а не Math.round().)

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

Совместимость с браузерами

Смотри также

• Date()