Temporal.Duration

Объект Temporal.Duration представляет разницу между двумя временными точками, которая может быть использована в арифметике дат/времени. По сути, он представляется как комбинация значений лет, месяцев, недель, дней, часов, минут, секунд, миллисекунд, микросекунд и наносекунд.

Описание

Формат длительности ISO 8601

Объекты Duration могут быть сериализованы и разобраны с использованием формата длительности ISO 8601 (с некоторыми расширениями, указанными ECMAScript). Строка имеет следующую форму (пробелы только для удобочитаемости и не должны присутствовать в фактической строке):

±P nY nM nW nD T nH nM nS

± Необязательно

Необязательный символ знака (+ или -), представляющий положительную или отрицательную длительность. По умолчанию — положительная.

P

Буквенный символ P или p, обозначающий "период".

nY, nM, nW, nD, nH, nM, nS

Число, за которым следует буквенный символ, представляющий количество лет (Y), месяцев (M), недель (W), дней (D), часов (H), минут (M) или секунд (S) соответственно. Все компоненты, кроме последнего существующего, должны быть целыми числами. Последний компонент, если это временной компонент (часы, минуты или секунды), может иметь дробную часть от 1 до 9 цифр, начинающуюся с точки или запятой, например PT0.0021S или PT1.1H. Любые нулевые компоненты могут быть опущены, но должен присутствовать хотя бы один компонент (даже если его значение равно нулю, в этом случае длительность равна нулю).

T

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

Вот несколько примеров:

При сериализации выходные данные максимально учитывают хранимые компоненты, сохраняя несбалансированные компоненты. Однако подсекундные компоненты сериализуются как одна дробная секунда, поэтому их точные значения, если они несбалансированы, могут быть потеряны. Знак плюс опускается для положительных длительностей. Нулевая длительность всегда сериализуется как PT0S.

Календарные длительности

Календарная длительность — это длительность, содержащая любую из календарных единиц: недели, месяцы и годы. Некалендарная длительность является переносимой и может участвовать в арифметике дат/времени без какой-либо информации о календаре, поскольку она однозначно представляет собой фиксированное количество времени. Однако календарная длительность не является переносимой, поскольку количество дней в месяце или году зависит от системы календаря и референтной временной точки. Следовательно, попытка выполнить любую арифметическую операцию над календарными длительностями вызывает ошибку, поскольку длительности сами по себе не отслеживают календарь. Например, если мы находимся в мае по григорианскому календарю, то "1 месяц" — это "31 день", но если мы находимся в апреле, то "1 месяц" становится "30 днями". Чтобы добавлять или вычитать календарные длительности, вам нужно добавлять их к датам:

const dur1 = Temporal.Duration.from({ years: 1 });
const dur2 = Temporal.Duration.from({ months: 1 });

dur1.add(dur2); // RangeError: for calendar duration arithmetic, use date arithmetic relative to a starting point

const startingPoint = Temporal.PlainDate.from("2021-01-01"); // ISO 8601 calendar
startingPoint.add(dur1).add(dur2).since(startingPoint); // "P396D"

Другие операции, round(), total() и compare(), принимают параметр relativeTo для предоставления необходимой информации о календаре и референтной времени. Этот параметр может быть Temporal.PlainDate, Temporal.PlainDateTime, Temporal.ZonedDateTime или другим объектом или строкой, которые могут быть преобразованы с помощью Temporal.ZonedDateTime.from() (если предоставлен параметр timeZone или строка содержит аннотацию часового пояса) или Temporal.PlainDate.from().

Обратите внимание, что преобразование days в hours также технически неоднозначно, поскольку продолжительность дня может варьироваться из-за изменений смещения, таких как переход на летнее время. Вы можете предоставить зонную relativeTo, чтобы учесть эти изменения; в противном случае предполагаются 24-часовые дни.

Балансировка длительности

Существует множество способов представления одной и той же длительности: например, "1 минута и 30 секунд" и "90 секунд" эквивалентны. Однако в зависимости от контекста одно представление может быть более подходящим, чем другое. Поэтому, как правило, объект Duration сохраняет входные значения насколько это возможно, чтобы при форматировании он отображался так, как вы ожидаете.

Каждый компонент длительности имеет свой оптимальный диапазон; часы должны быть от 0 до 23, минуты от 0 до 59 и так далее. Когда компонент выходит за пределы своего оптимального диапазона, избыток может быть "перенесен" в следующий более крупный компонент. Для переноса необходимо ответить на вопрос "сколько X содержится в Y?", что является сложным вопросом для календарных единиц, поэтому в этом случае требуется календарь. Также обратите внимание, что по умолчанию days напрямую переносятся в months; единица недели переносится только при явном запросе. Если мы переносим максимально возможно, конечный результат, где все компоненты находятся в своих оптимальных диапазонах, называется "сбалансированной" длительностью. Несбалансированные длительности обычно имеют "верхнетяжелую" форму, где самая крупная единица несбалансирована (например, "27 часов и 30 минут"); другие формы, такие как "23 часа и 270 минут", встречаются редко.

Метод round() всегда балансирует длительность в "верхнетяжелую" форму, вплоть до параметра largestUnit. С помощью ручного параметра largestUnit, который достаточно велик, вы можете полностью сбалансировать длительность. Аналогично, методы add() и subtract() балансируют результирующую длительность до самой крупной единицы входных длительностей.

Обратите внимание, что поскольку формат длительности ISO 8601 представляет подсекундные компоненты как одно дробное число, невозможно сохранить несбалансированные подсекундные компоненты при сериализации в формате по умолчанию. Например, "1000 миллисекунд" сериализуется как "PT1S", а затем десериализуется как "1 секунда". Если вам нужно сохранить величины подсекундных компонентов, вам нужно вручную сериализовать их как JSON-объект (поскольку по умолчанию метод toJSON() сериализует длительность в формате ISO 8601).

Знак длительности

Поскольку длительность — это разница между двумя временными точками, она может быть положительной, отрицательной или нулевой. Например, если вы отображаете время событий относительно настоящего, то отрицательные длительности могут представлять события в прошлом, а положительные — в будущем. В нашем представлении с использованием комбинации временных компонентов знак хранится в каждом компоненте: отрицательная длительность всегда имеет все компоненты отрицательными (или нулевыми), а положительная длительность всегда имеет все компоненты положительными (или нулевыми). Создание длительности с компонентами смешанных знаков недопустимо и будет отклонено конструктором или методом with(). Методы add() и subtract() будут балансировать результирующую длительность, чтобы избежать смешанных знаков.

Конструктор

Temporal.Duration()

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

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

Temporal.Duration.compare()

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

Temporal.Duration.from()

Создает новый объект Temporal.Duration из другого объекта Temporal.Duration, объекта со свойствами длительности или строки ISO 8601.

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

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

Temporal.Duration.prototype.blank

Возвращает булево значение, которое является true, если эта длительность представляет нулевую длительность, и false в противном случае. Эквивалентно duration.sign === 0.

Temporal.Duration.prototype.constructor

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

Temporal.Duration.prototype.days

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

Temporal.Duration.prototype.hours

Возвращает целое число, представляющее количество часов в длительности.

Temporal.Duration.prototype.microseconds

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

Temporal.Duration.prototype.milliseconds

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

Temporal.Duration.prototype.minutes

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

Temporal.Duration.prototype.months

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

Temporal.Duration.prototype.nanoseconds

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

Temporal.Duration.prototype.seconds

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

Temporal.Duration.prototype.sign

Возвращает 1, если эта длительность положительна, -1, если отрицательна, и 0, если равна нулю.

Temporal.Duration.prototype.weeks

Возвращает целое число, представляющее количество недель в длительности.

Temporal.Duration.prototype.years

Возвращает целое число, представляющее количество лет в длительности.

Temporal.Duration.prototype[Symbol.toStringTag]

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

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

Temporal.Duration.prototype.abs()

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

Temporal.Duration.prototype.add()

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

Temporal.Duration.prototype.negated()

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

Temporal.Duration.prototype.round()

Возвращает новый объект Temporal.Duration с длительностью, округленной до указанной наименьшей единицы и/или сбалансированной до указанной наибольшей единицы.

Temporal.Duration.prototype.subtract()

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

Temporal.Duration.prototype.toJSON()

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

Temporal.Duration.prototype.toLocaleString()

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

Temporal.Duration.prototype.toString()

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

Temporal.Duration.prototype.total()

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

Temporal.Duration.prototype.valueOf()

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

Temporal.Duration.prototype.with()

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

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

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

См. также

• Temporal