Temporal.ZonedDateTime

Объект Temporal.ZonedDateTime представляет дату и время с часовым поясом. По сути, он представлен как сочетание момента времени, часового пояса и календарной системы.

Описание

Объект ZonedDateTime служит связующим звеном между точным временем и временем на настенных часах: он одновременно представляет момент в истории (например, Temporal.Instant) и местное время (например, Temporal.PlainDateTime). Для этого он хранит момент времени, часовой пояс и календарную систему. Часовой пояс используется для преобразования момента времени в местное время и наоборот, а календарная система — для интерпретации местного времени.

ZonedDateTime — единственный класс Temporal, учитывающий часовой пояс. Наличие часового пояса приводит к тому, что объекты ZonedDateTime имеют важные поведенческие отличия от объектов Temporal.PlainDateTime. В частности, нельзя считать, что «время на 1 минуту позже» одинаково каждый день или что сутки длятся 24 часа. В худшем случае из местного календаря может исчезнуть целый день. Ниже приведён краткий обзор часовых поясов и смещений, а также их влияния на преобразование времени UTC в местное время.

Часовые пояса и смещения

Для всего времени в JavaScript существует один золотой стандарт — время UTC, которое непрерывно и равномерно увеличивается по мере течения физического времени. В отличие от него, пользователей больше интересует местное время, которое они видят в календарях и на часах. Для преобразования времени UTC в местное время и наоборот используется смещение часового пояса, которое рассчитывается следующим образом:

local time = UTC time + offset

Например, если время UTC — 1970-01-01T00:00:00, а смещение — «-05:00», местное время будет таким:

1970-01-01T00:00:00 + -05:00 = 1969-12-31T19:00:00

Добавив это смещение к местному времени и представив время как «1969-12-31T19:00:00-05:00», его теперь можно однозначно интерпретировать как момент в истории.

Чтобы определить смещение, нужны две вещи: часовой пояс и момент времени. Часовой пояс — это регион Земли, в котором в любой момент времени используется одинаковое смещение. Два часа в одном часовом поясе всегда показывают одно и то же время одновременно, но смещение не обязательно постоянно: показания этих часов могут резко измениться. Такое часто происходит при переходах на летнее время и обратно: смещение меняется на час, что происходит дважды в год. Смещения также могут изменяться навсегда из-за политических изменений, например, когда страна меняет часовой пояс.

Часовые пояса хранятся в базе данных часовых поясов IANA. Для каждого часового пояса IANA определены:

• Основной идентификатор часового пояса, который однозначно определяет часовой пояс. Обычно он обозначает географическую область, привязанную к городу (например, Europe/Paris или Africa/Kampala), но может также обозначать часовой пояс с одним смещением, например UTC (постоянное смещение +00:00) или Etc/GMT+5 (который по историческим причинам имеет отрицательное смещение -05:00). По историческим причинам основное название часового пояса UTC — UTC, хотя в IANA это Etc/UTC.
• Определение часового пояса в виде таблицы, сопоставляющей диапазоны дат и времени UTC (включая будущие диапазоны) с конкретными смещениями.
• Ноль или более неосновных идентификаторов часового пояса, являющихся псевдонимами основного идентификатора часового пояса. Обычно это исторические названия, которые больше не используются, но сохранены для обеспечения совместимости. Подробнее см. ниже.

При вводе именованные идентификаторы сопоставляются без учёта регистра. Внутри они хранятся с предпочтительным регистром, а неосновные идентификаторы не преобразуются в основные.

Когда API Temporal принимает идентификатор часового пояса, помимо основных и неосновных идентификаторов часовых поясов он также принимает идентификатор часового пояса со смещением. Его формат совпадает с форматом смещения, за исключением того, что точность меньше минуты не допускается. Например, +05:30, -08 и +0600 — допустимые идентификаторы смещения. Внутри идентификаторы смещения хранятся в формате ±HH:mm.

Для удобства при передаче идентификатора часового пояса в API Temporal, например в Temporal.ZonedDateTime.prototype.withTimeZone() и параметр timeZoneId метода Temporal.ZonedDateTime.from(), можно использовать ещё несколько вариантов:

• Другой экземпляр ZonedDateTime, значение timeZoneId которого будет использовано.
• Строку RFC 9557 с аннотацией часового пояса, идентификатор которого будет использован.
• Строку ISO 8601 / RFC 3339 со смещением, которое будет использовано как идентификатор смещения; если используется Z, то применяется часовой пояс "UTC". Обычно это не рекомендуется, поскольку, как описано выше, идентификаторы смещения не позволяют безопасно создавать другие экземпляры Temporal.ZonedDateTime через переходы смещения, например при начале или окончании действия летнего времени. Вместо этого рассмотрите возможность использовать Temporal.Instant или получить фактический именованный часовой пояс пользователя.

База данных часовых поясов IANA время от времени меняется — обычно в неё добавляются новые часовые пояса в ответ на политические изменения. Однако в редких случаях идентификаторы часовых поясов IANA переименовываются, чтобы соответствовать обновлённому английскому переводу названия города или новым правилам именования. Вот несколько примечательных примеров переименования:

Исторически эти переименования создавали проблемы для программистов, поскольку база данных Unicode CLDR (библиотека, используемая браузерами для предоставления идентификаторов и данных часовых поясов) не следовала переименованиям IANA по соображениям стабильности. В результате одни браузеры, например Chrome и Safari, сообщали устаревшие идентификаторы CLDR, а другие, например Firefox, переопределяли значения CLDR по умолчанию и сообщали актуальные основные идентификаторы.

С появлением Temporal это поведение стало более стандартизированным:

• Данные CLDR теперь включают атрибут "_iana", указывающий наиболее актуальный идентификатор, если старый стабильный идентификатор был переименован. Браузеры могут использовать этот новый атрибут, чтобы предоставлять вызывающему коду актуальные идентификаторы.
• Идентификаторы часовых поясов, указанные программистом, никогда не заменяются псевдонимом. Например, если вызывающий код передаст Asia/Calcutta или Asia/Kolkata в качестве входного идентификатора в Temporal.ZonedDateTime.from(), в свойстве timeZoneId полученного экземпляра будет возвращён тот же идентификатор. Обратите внимание: регистр выходных значений нормализуется в соответствии с IANA, поэтому при передаче ASIA/calCuTTa в качестве входного значения свойство timeZoneId вернёт Asia/Calcutta.
• Если идентификатор часового пояса не передан вызывающим кодом, а получен из самой системы (например, при использовании Temporal.Now.timeZoneId()), во всех браузерах возвращаются современные идентификаторы. Для переименований городов API, получающие идентификаторы из системы, начинают предоставлять новое имя через два года. Это даёт другим компонентам (например, серверу Node) время обновить свои копии базы данных IANA и распознавать новое имя.

Обратите внимание: при определении основных идентификаторов сохраняется код страны. Например, база данных IANA указывает Atlantic/Reykjavik как псевдоним Africa/Abidjan, но, поскольку они относятся к разным странам (Исландии и Кот-д’Ивуару соответственно), считаются разными основными идентификаторами.

Эта стандартизация распространяется и на другие области за пределами Temporal. Например, значение параметра timeZone, возвращаемое методом Intl.DateTimeFormat.prototype.resolvedOptions(), также никогда не заменяется псевдонимом, хотя до стандартизации Temporal браузеры обычно канонизировали эти идентификаторы. С другой стороны, методы Intl.Locale.prototype.getTimeZones() и Intl.supportedValuesOf() (параметр timeZone) возвращают наиболее актуальный идентификатор, тогда как некоторые браузеры раньше возвращали старый неосновной идентификатор.

Формат RFC 9557

Объекты ZonedDateTime можно сериализовать и анализировать с использованием формата RFC 9557 — расширения формата ISO 8601 / RFC 3339. Строка имеет следующий вид (пробелы добавлены только для удобства чтения и не должны присутствовать в реальной строке):

YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm [time_zone_id] [u-ca=calendar_id]

YYYY

Либо четырёхзначное число, либо шестизначное число со знаком + или -.

MM

Двухзначное число от 01 до 12.

DD

Двухзначное число от 01 до 31. Компоненты YYYY, MM и DD можно разделить символом - или не разделять.

T Необязательный

Разделитель даты и времени: T, t или пробел. Присутствует тогда и только тогда, когда присутствует HH.

HH Необязательный

Двухзначное число от 00 до 23. По умолчанию — 00.

mm Необязательный

Двухзначное число от 00 до 59. По умолчанию — 00.

ss.sssssssss Необязательный

Двухзначное число от 00 до 59. После него может следовать . или , и от одной до девяти цифр. По умолчанию — 00. Компоненты HH, mm и ss можно разделить символом : или не разделять. Можно опустить либо только ss, либо оба компонента — ss и mm, поэтому время может иметь один из трёх форматов: HH, HH:mm или HH:mm:ss.sssssssss.

Z/±HH:mm Необязательный

Либо обозначение UTC Z или z, либо смещение относительно UTC в формате + или -, за которым следует такой же формат, как и у компонента времени. Обратите внимание: точность меньше минуты (:ss.sssssssss) может не поддерживаться другими системами; такой формат принимается, но никогда не выводится. Если смещение не указано, оно определяется на основе идентификатора часового пояса. Если оно указано, необходимо также указать время. Z — это не то же самое, что +00:00: первое означает, что время указано в формате UTC независимо от идентификатора часового пояса, а второе — что время указано по местному времени, которое просто совпадает с UTC+0, и будет проверено на соответствие идентификатору часового пояса с помощью параметра offset.

[time_zone_id]

Замените time_zone_id идентификатором часового пояса (именованным или со смещением), описанным выше. Можно добавить критический флаг, поставив перед идентификатором !, например [!America/New_York]. Этот флаг обычно сообщает другим системам, что его нельзя игнорировать, если они его не поддерживают. Обратите внимание: для Temporal.ZonedDateTime.from() он обязателен: его отсутствие приводит к RangeError. Чтобы анализировать строки ISO 8601 / RFC 3339 без аннотаций идентификатора часового пояса, используйте вместо этого Temporal.Instant.from().

[u-ca=calendar_id] Необязательный

Замените calendar_id используемым календарём. Список часто поддерживаемых типов календарей см. в разделе Intl.supportedValuesOf(). По умолчанию используется [u-ca=iso8601]. Можно добавить критический флаг, поставив перед ключом !, например [!u-ca=iso8601]. Этот флаг обычно сообщает другим системам, что его нельзя игнорировать, если они его не поддерживают. Парсер Temporal выдаст ошибку, если аннотации содержат две или более аннотации календаря и одна из них является критической. Обратите внимание: YYYY-MM-DD всегда интерпретируется как дата календаря ISO 8601, а затем преобразуется в указанный календарь.

При вводе другие аннотации в формате [key=value] игнорируются и не должны иметь критический флаг.

При сериализации можно настроить количество дробных цифр секунд, отображение смещения, идентификатора часового пояса и идентификатора календаря, а также добавление критического флага к аннотациям.

Неоднозначность и пробелы при преобразовании местного времени во время UTC

Зная часовой пояс, преобразовать время UTC в местное несложно: сначала нужно получить смещение по названию часового пояса и моменту времени, а затем прибавить смещение к моменту времени. Обратное преобразование устроено иначе: перевод местного времени во время UTC без явно заданного смещения неоднозначен, поскольку одному местному времени может соответствовать ноль, один или несколько вариантов времени UTC. Рассмотрим самую распространённую причину — переходы на летнее время и обратно. Возьмём для примера Нью-Йорк. Стандартное смещение в нём — UTC-5, но при переходе на летнее время все часы переводятся на час вперёд, поэтому смещение становится UTC-4. В США переходы происходят в 2:00 по местному времени. Рассмотрим два дня перехода:

Как видно, в марте один час исчезает из местного времени, а в ноябре два часа имеют одинаковое время на настенных часах. Предположим, что у нас есть объект PlainDateTime со значением «2024-03-10T02:05:00», которое нужно интерпретировать в часовом поясе America/New_York. Этому времени не будет соответствовать ни один момент, тогда как значение «2024-11-03T01:05:00» объекта PlainDateTime может соответствовать двум разным моментам.

При создании объекта ZonedDateTime на основе местного времени (с помощью Temporal.ZonedDateTime.from(), Temporal.ZonedDateTime.prototype.with(), Temporal.PlainDateTime.prototype.toZonedDateTime()) поведение при неоднозначности и пробелах можно настроить с помощью параметра disambiguation:

earlier

Если возможны два момента, выбирается более ранний. Если есть пробел, время сдвигается назад на его длительность.

later

Если возможны два момента, выбирается более поздний. Если есть пробел, время сдвигается вперёд на его длительность.

compatible (по умолчанию)

Поведение такое же, как у Date: для пробелов используется later, а для неоднозначных случаев — earlier.

reject

Выбрасывается RangeError при наличии неоднозначности или пробела.

Существует несколько случаев, когда при создании объекта ZonedDateTime неоднозначность отсутствует:

• Если время указано в UTC с помощью смещения Z.
• Если смещение задано явно и используется (см. ниже).

Неоднозначность смещения

Мы уже показали, как может возникнуть неоднозначность при интерпретации местного времени в часовом поясе без явного указания смещения. Однако явное указание смещения вызывает другой конфликт: между заданным смещением и смещением, рассчитанным по часовому поясу и местному времени. Это неизбежная проблема реального мира: если сохранить время в будущем с предполагаемым смещением, то до наступления этого времени определение часового пояса может измениться по политическим причинам. Например, предположим, что в 2018 году мы устанавливаем напоминание на время 2019-12-23T12:00:00-02:00[America/Sao_Paulo] (это летнее время; Бразилия находится в Южном полушарии, поэтому переходит на летнее время в октябре и возвращается на зимнее в феврале). Но до наступления этого времени, в начале 2019 года, Бразилия решает отказаться от летнего времени, и фактическое смещение становится -03:00. Должно ли напоминание по-прежнему срабатывать в полдень (с сохранением местного времени) или в 11:00 (с сохранением точного времени)?

Неоднозначность смещения возникает, если строка с отметкой времени анализируется с использованием правил базы данных часовых поясов IANA, отличных от правил, использованных при создании этой строки. Этого никогда не происходит, когда отметки времени создаются в ходе одного и того же выполнения программы JavaScript, поскольку спецификация ECMAScript требует, чтобы правила базы данных часовых поясов IANA оставались неизменными в течение всего времени работы программы JavaScript.

Однако неоднозначность смещения может возникнуть, если программа JavaScript анализирует отметки времени, сохранённые ранее, как в приведённом выше примере America/Sao_Paulo, а база данных часовых поясов IANA с момента создания отметки времени была обновлена. Это также может случиться при передаче отметок времени между компьютерами (или, в редких случаях, между разными программами на одном компьютере!), использующими разные версии базы данных часовых поясов IANA. Кроме того, в базе данных часовых поясов IANA есть параметры сборки (например, использование или неиспользование устаревших правил в backzone), которые могут привести к неоднозначности смещения при передаче отметок времени между компьютерами с разным программным обеспечением, даже если версия базы данных часовых поясов IANA совпадает.

Неоднозначность смещения встречается редко и почти всегда относится только к отметкам времени до 1970 года или к отметкам времени, приходящимся на несколько месяцев или лет вперёд. Но если такая проблема возникает, по умолчанию будет выброшено исключение RangeError. При создании объекта ZonedDateTime с помощью Temporal.ZonedDateTime.from() или его обновлении с помощью метода with() можно избежать этого исключения, используя параметр offset, который определяет, что имеет приоритет: смещение или идентификатор часового пояса.

use

Использовать смещение для вычисления точного времени. Этот параметр «использует» смещение, чтобы определить момент, заданный строкой с отметкой времени, даже если смещение в этот момент изменилось. Затем идентификатор часового пояса по-прежнему используется для определения (возможно, обновлённого) смещения и преобразования точного времени в местное. В приведённом выше примере 2019-12-23T12:00:00-02:00[America/Sao_Paulo] этот параметр приведёт к тому, что напоминание сработает в 11:00 по местному времени.

ignore

Использовать идентификатор часового пояса для повторного вычисления смещения, игнорируя смещение, заданное в строке. Этот параметр сохраняет то же местное время, которое было рассчитано при сохранении времени, но может привести к другому моменту времени. Обратите внимание: игнорирование смещения может вызвать ту же неоднозначность при интерпретации местного времени, которая разрешается с помощью параметра disambiguation. В приведённом выше примере 2019-12-23T12:00:00-02:00[America/Sao_Paulo] этот параметр приведёт к тому, что напоминание сработает в 12:00 по местному времени.

reject

Выбрасывать RangeError при любом конфликте между смещением и идентификатором часового пояса. Это значение по умолчанию для Temporal.ZonedDateTime.from().

prefer

Использовать смещение, если оно допустимо; в противном случае вычислить смещение по идентификатору часового пояса. Это значение по умолчанию для Temporal.ZonedDateTime.prototype.with() (подробнее см. описание этого метода). Этот вариант отличается от ignore тем, что при неоднозначности местного времени для её разрешения используется смещение, а не параметр disambiguation.

Если вы заранее знаете, как обрабатывать неоднозначность смещения, рассмотрите возможность использовать параметр offset, чтобы избежать исключений, выбрасываемых по умолчанию. Например, приложению-календарю, скорее всего, нужно, чтобы приоритет имел идентификатор часового пояса: тогда повторяющиеся встречи будут отображаться по наиболее актуальному местному времени для этого часового пояса, поэтому подойдёт offset: "ignore". С другой стороны, приложение-планировщик задач, которое выполняет задачу ровно через 3 часа, вероятно, должно выбрать offset: "use", поскольку изменения правил часового пояса не должны менять смысл выражения «через 3 часа».

В некоторых случаях без участия пользователя невозможно определить, какой параметр offset является правильным. В таких случаях можно перехватить RangeError, спросить пользователя, какое местное время является правильным, а затем повторить анализ с другим параметром offset, соответствующим выбору пользователя.

Обратите внимание: смещение Z не эквивалентно +00:00. Смещение Z означает «время UTC известно, но смещение для местного времени неизвестно» согласно RFC 9557. Если в строке времени используется смещение Z, параметр offset игнорируется, а смещение определяется по идентификатору часового пояса. С другой стороны, смещение +00:00 интерпретируется как смещение местного времени, которое просто совпадает с UTC, и проверяется на соответствие идентификатору часового пояса.

Конструктор

Temporal.ZonedDateTime() Экспериментальная функция

Создаёт новый объект Temporal.ZonedDateTime, напрямую получая его базовые данные.

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

Temporal.ZonedDateTime.compare()

Возвращает число (-1, 0 или 1), указывающее, предшествует ли первая дата и время второй, совпадает с ней или следует за ней. Эквивалентно сравнению значений epochNanoseconds двух дат и времени.

Temporal.ZonedDateTime.from()

Создаёт новый объект Temporal.ZonedDateTime на основе другого объекта Temporal.ZonedDateTime, объекта со свойствами даты, времени и часового пояса или строки RFC 9557.

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

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

Temporal.ZonedDateTime.prototype.calendarId

Возвращает строку, представляющую календарь, используемый для интерпретации внутренней даты ISO 8601.

Temporal.ZonedDateTime.prototype.constructor

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

Temporal.ZonedDateTime.prototype.day

Возвращает положительное целое число, представляющее порядковый номер дня в месяце этой даты, начиная с 1; это тот же номер дня, который отображается в календаре. Зависит от календаря. Обычно нумерация начинается с 1 и идет непрерывно, но не всегда.

Temporal.ZonedDateTime.prototype.dayOfWeek

Возвращает положительное целое число, представляющее порядковый номер дня недели этой даты, начиная с 1. Дни недели нумеруются последовательно от 1 до daysInWeek, причем каждому числу соответствует свое название. Зависит от календаря. Обычно число 1 соответствует понедельнику в календаре, даже если в локалях, использующих этот календарь, первым днем недели считается другой день (см. Intl.Locale.prototype.getWeekInfo()).

Temporal.ZonedDateTime.prototype.dayOfYear

Возвращает положительное целое число, представляющее порядковый номер дня этой даты в году, начиная с 1. Первый день этого года — 1, а последний — daysInYear. Зависит от календаря.

Temporal.ZonedDateTime.prototype.daysInMonth

Возвращает положительное целое число, представляющее количество дней в месяце этой даты. Зависит от календаря.

Temporal.ZonedDateTime.prototype.daysInWeek

Возвращает положительное целое число, представляющее количество дней в неделе этой даты. Зависит от календаря. В календаре ISO 8601 это всегда 7, но в других календарных системах число может меняться от недели к неделе.

Temporal.ZonedDateTime.prototype.daysInYear

Возвращает положительное целое число, представляющее количество дней в году этой даты. Зависит от календаря. В календаре ISO 8601 это 365 или 366 в високосном году.

Temporal.ZonedDateTime.prototype.epochMilliseconds

Возвращает целое число, представляющее количество миллисекунд, прошедших от начала эпохи Unix (полночь в начале 1 января 1970 года UTC) до этого момента времени. Эквивалентно результату деления epochNanoseconds на 1e6 с округлением вниз.

Temporal.ZonedDateTime.prototype.epochNanoseconds

Возвращает значение типа BigInt, представляющее количество наносекунд, прошедших от начала эпохи Unix (полночь в начале 1 января 1970 года UTC) до этого момента времени.

Temporal.ZonedDateTime.prototype.era

Возвращает строчную строку, специфичную для календаря и представляющую эру этой даты, или undefined, если в календаре нет эр (например, в ISO 8601). era и eraYear вместе однозначно определяют год в календаре так же, как year. Зависит от календаря. В григорианском календаре это либо "ce", либо "bce".

Temporal.ZonedDateTime.prototype.eraYear

Возвращает неотрицательное целое число, представляющее год этой даты в пределах эры, или undefined, если в календаре нет эр (например, в ISO 8601). Нумерация лет обычно начинается с 1 (чаще) или 0; годы эры могут убывать со временем (например, годы до нашей эры в григорианском календаре). era и eraYear вместе однозначно определяют год в календаре так же, как year. Зависит от календаря.

Temporal.ZonedDateTime.prototype.hour

Возвращает целое число от 0 до 23, представляющее компонент часов этого времени.

Temporal.ZonedDateTime.prototype.hoursInDay

Возвращает положительное целое число, представляющее количество часов в дне этой даты в данном часовом поясе. Оно может быть больше или меньше 24 при изменении смещения, например при переходе на летнее время.

Temporal.ZonedDateTime.prototype.inLeapYear

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

Temporal.ZonedDateTime.prototype.microsecond

Возвращает целое число от 0 до 999, представляющее компонент микросекунд (10^-6 секунды) этого времени.

Temporal.ZonedDateTime.prototype.millisecond

Возвращает целое число от 0 до 999, представляющее компонент миллисекунд (10^-3 секунды) этого времени.

Temporal.ZonedDateTime.prototype.minute

Возвращает целое число от 0 до 59, представляющее компонент минут этого времени.

Temporal.ZonedDateTime.prototype.month

Возвращает положительное целое число, представляющее порядковый номер месяца этой даты в году, начиная с 1. Первый месяц этого года — 1, а последний — monthsInYear. Зависит от календаря. Обратите внимание: в отличие от Date.prototype.getMonth(), нумерация начинается с 1. Если в календаре есть високосные месяцы, то месяц с одним и тем же monthCode может иметь разные индексы month в разные годы.

Temporal.ZonedDateTime.prototype.monthCode

Возвращает строку, специфичную для календаря и представляющую месяц этой даты. Зависит от календаря. Обычно это M и двузначный номер месяца. Для високосных месяцев к коду предыдущего месяца добавляется L. Если високосный месяц является первым месяцем года, код — M00L.

Temporal.ZonedDateTime.prototype.monthsInYear

Возвращает положительное целое число, представляющее количество месяцев в году этой даты. Зависит от календаря. В календаре ISO 8601 это всегда 12, но в других календарных системах число может отличаться.

Temporal.ZonedDateTime.prototype.nanosecond

Возвращает целое число от 0 до 999, представляющее компонент наносекунд (10^-9 секунды) этого времени.

Temporal.ZonedDateTime.prototype.offset

Возвращает строку, представляющую смещение, используемое для интерпретации внутреннего момента времени, в формате ±HH:mm (или ±HH:mm:ss.sssssssss с необходимой точностью до долей секунды).

Temporal.ZonedDateTime.prototype.offsetNanoseconds

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

Temporal.ZonedDateTime.prototype.second

Возвращает целое число от 0 до 59, представляющее компонент секунд этого времени.

Temporal.ZonedDateTime.prototype.timeZoneId

Возвращает строку, представляющую идентификатор часового пояса, используемый для интерпретации внутреннего момента времени. Используется та же строка, что и при создании объекта Temporal.ZonedDateTime; это либо название часового пояса IANA, либо фиксированное смещение.

Temporal.ZonedDateTime.prototype.weekOfYear

Возвращает положительное целое число, представляющее порядковый номер недели в yearOfWeek этой даты, начиная с 1, или undefined, если в календаре нет четко определенной системы нумерации недель. Первая неделя года — 1. Зависит от календаря. Обратите внимание: в ISO 8601 первые и последние несколько дней года могут относиться к последней неделе предыдущего года или первой неделе следующего года.

Temporal.ZonedDateTime.prototype.year

Возвращает целое число, представляющее число лет этой даты относительно начала календарного года, принятого за эпоху. Зависит от календаря. Обычно год 1 — это либо первый год последней эры, либо год ISO 8601 0001. Если эпоха приходится на середину года, этот год будет иметь одинаковое значение до и после даты начала эры.

Temporal.ZonedDateTime.prototype.yearOfWeek

Возвращает целое число, представляющее год, соответствующий weekOfYear этой даты, или undefined, если в календаре нет четко определенной системы нумерации недель. Зависит от календаря. Обычно это год даты, но в ISO 8601 первые и последние несколько дней года могут относиться к последней неделе предыдущего года или первой неделе следующего года, из-за чего значение yearOfWeek отличается на 1.

Temporal.ZonedDateTime.prototype[Symbol.toStringTag]

Начальное значение свойства [Symbol.toStringTag] — строка "Temporal.ZonedDateTime". Это свойство используется в Object.prototype.toString().

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

Temporal.ZonedDateTime.prototype.add()

Возвращает новый объект Temporal.ZonedDateTime, представляющий эту дату и время, сдвинутые вперед на заданную длительность (в форме, преобразуемой с помощью Temporal.Duration.from()).

Temporal.ZonedDateTime.prototype.equals()

Возвращает true, если значение этой даты и времени эквивалентно значению другой даты и времени (в форме, преобразуемой с помощью Temporal.ZonedDateTime.from()), и false в противном случае. Сравниваются моменты времени, часовые пояса и календари, поэтому даты и время из разных календарей или часовых поясов могут считаться равными при использовании Temporal.ZonedDateTime.compare(), но не при использовании equals().

Temporal.ZonedDateTime.prototype.getTimeZoneTransition()

Возвращает объект Temporal.ZonedDateTime, представляющий первый момент времени после или до этого момента, когда меняется смещение часового пояса относительно UTC, или null, если такого перехода нет. Это полезно для определения правил смещения часового пояса, например схемы перехода на летнее время.

Temporal.ZonedDateTime.prototype.round()

Возвращает новый объект Temporal.ZonedDateTime, представляющий эту дату и время, округленные до заданной единицы.

Temporal.ZonedDateTime.prototype.since()

Возвращает новый объект Temporal.Duration, представляющий длительность от другой даты и времени (в форме, преобразуемой с помощью Temporal.ZonedDateTime.from()) до этой даты и времени. Длительность положительна, если другая дата и время предшествует этой, и отрицательна, если следует за ней.

Temporal.ZonedDateTime.prototype.startOfDay()

Возвращает объект Temporal.ZonedDateTime, представляющий первый момент времени этой даты в часовом поясе. Обычно это время 00:00:00, но оно может отличаться, если полночь не наступает из-за изменения смещения; в таком случае возвращается первое существующее время.

Temporal.ZonedDateTime.prototype.subtract()

Возвращает новый объект Temporal.ZonedDateTime, представляющий эту дату и время, сдвинутые назад на заданную длительность (в форме, преобразуемой с помощью Temporal.Duration.from()).

Temporal.ZonedDateTime.prototype.toInstant()

Возвращает новый объект Temporal.Instant, представляющий момент времени этой даты и времени.

Temporal.ZonedDateTime.prototype.toJSON()

Возвращает строку, представляющую эту дату и время в том же формате RFC 9557, что и вызов toString(). Предназначен для неявного вызова методом JSON.stringify().

Temporal.ZonedDateTime.prototype.toLocaleString()

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

Temporal.ZonedDateTime.prototype.toPlainDate()

Возвращает новый объект Temporal.PlainDate, представляющий часть этой даты и времени, относящуюся к дате.

Temporal.ZonedDateTime.prototype.toPlainDateTime()

Возвращает новый объект Temporal.PlainDateTime, представляющий дату и время без часового пояса. Удаляется только информация о часовом поясе.

Temporal.ZonedDateTime.prototype.toPlainTime()

Возвращает новый объект Temporal.PlainTime, представляющий часть этой даты и времени, относящуюся ко времени.

Temporal.ZonedDateTime.prototype.toString()

Возвращает строку, представляющую эту дату и время в формате RFC 9557.

Temporal.ZonedDateTime.prototype.until()

Возвращает новый объект Temporal.Duration, представляющий длительность от этой даты и времени до другой даты и времени (в форме, преобразуемой с помощью Temporal.ZonedDateTime.from()). Длительность положительна, если другая дата и время следует за этой, и отрицательна, если предшествует ей.

Temporal.ZonedDateTime.prototype.valueOf()

Выбрасывает исключение TypeError, не позволяя экземплярам Temporal.ZonedDateTime неявно преобразовываться в примитивы при использовании в арифметических операциях или операциях сравнения.

Temporal.ZonedDateTime.prototype.with()

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

Temporal.ZonedDateTime.prototype.withCalendar()

Возвращает новый объект Temporal.ZonedDateTime, представляющий эту дату и время, интерпретируемые в новой календарной системе.

Temporal.ZonedDateTime.prototype.withPlainTime()

Возвращает новый объект Temporal.ZonedDateTime, представляющий эту дату и время, у которых часть, относящаяся ко времени, полностью заменена новым временем (в форме, преобразуемой с помощью Temporal.PlainTime.from())

Temporal.ZonedDateTime.prototype.withTimeZone()

Возвращает новый объект Temporal.ZonedDateTime, представляющий тот же момент времени, что и эта дата и время, но в новом часовом поясе.

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

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

См. также

• Temporal
• Temporal.Duration
• Temporal.Instant
• Temporal.PlainDateTime
• Temporal.PlainDate
• Temporal.PlainTime