Temporal.Instant

Объект Temporal.Instant представляет собой уникальный момент времени с точностью до наносекунд. В основе его представления лежит количество наносекунд, прошедших с начала эпохи Unix (полуночи в начале 1 января 1970 года по UTC), без указания часового пояса или календарной системы.

Описание

Temporal.Instant семантически эквивалентен Date. Оба объекта представляют один момент времени, но Temporal.Instant точнее, поскольку хранит наносекунды, а не миллисекунды. Кроме того, Temporal.Instant позволяет избежать подводных камней, связанных с Date, поскольку не предполагает наличия сведений о календаре или часовом поясе. Если вам нужны какие-либо сведения о дате или времени, например год или месяц, сначала преобразуйте объект в Temporal.ZonedDateTime с помощью toZonedDateTimeISO().

Преобразовать Date в Temporal.Instant можно с помощью метода Date.prototype.toTemporalInstant(). Его следует предпочесть другим методам, например Temporal.Instant.fromEpochMilliseconds(), поскольку он требует меньше пользовательского кода и может быть лучше оптимизирован. Также можно преобразовать Temporal.Instant в Date, используя миллисекунды эпохи, например new Date(instant.epochMilliseconds).

Формат RFC 9557

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

YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm

YYYY

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

MM

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

DD

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

T

Разделитель даты и времени: T, t или пробел.

HH

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

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) может не поддерживаться другими системами; такое значение принимается, но никогда не выводится. Если указано смещение, время интерпретируется с учётом этого смещения.

В качестве входных данных можно дополнительно указать идентификатор часового пояса и календарь в том же формате, что и ZonedDateTime, но они будут проигнорированы. Другие аннотации в формате [key=value] также игнорируются и не должны иметь флаг критичности.

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

Конструктор

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

Создаёт новый объект Temporal.Instant, напрямую принимая исходные данные.

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

Temporal.Instant.compare()

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

Temporal.Instant.from()

Создаёт новый объект Temporal.Instant из другого объекта Temporal.Instant или строки в формате RFC 9557.

Temporal.Instant.fromEpochMilliseconds()

Создаёт новый объект Temporal.Instant из количества миллисекунд, прошедших с начала эпохи Unix (полуночи в начале 1 января 1970 года по UTC).

Temporal.Instant.fromEpochNanoseconds()

Создаёт новый объект Temporal.Instant из количества наносекунд, прошедших с начала эпохи Unix (полуночи в начале 1 января 1970 года по UTC).

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

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

Temporal.Instant.prototype.constructor

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

Temporal.Instant.prototype.epochMilliseconds

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

Temporal.Instant.prototype.epochNanoseconds

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

Temporal.Instant.prototype[Symbol.toStringTag]

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

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

Temporal.Instant.prototype.add()

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

Temporal.Instant.prototype.equals()

Возвращает true, если значение этого момента времени эквивалентно значению другого момента времени (в формате, который можно преобразовать с помощью Temporal.Instant.from()), и false в противном случае. Моменты сравниваются по наносекундам эпохи. Эквивалентно Temporal.Instant.compare(this, other) === 0.

Temporal.Instant.prototype.round()

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

Temporal.Instant.prototype.since()

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

Temporal.Instant.prototype.subtract()

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

Temporal.Instant.prototype.toJSON()

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

Temporal.Instant.prototype.toLocaleString()

Возвращает строку с локализованным представлением этого момента времени. В реализациях с поддержкой API Intl.DateTimeFormat этот метод делегирует вызов Intl.DateTimeFormat.

Temporal.Instant.prototype.toString()

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

Temporal.Instant.prototype.toZonedDateTimeISO()

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

Temporal.Instant.prototype.until()

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

Temporal.Instant.prototype.valueOf()

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

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

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

См. также

• Temporal
• Temporal.Duration
• Temporal.ZonedDateTime