Временный API

API для решения всех проблем с датами в JavaScript

Привет ребята,

В этом посте мы углубимся в новый JavaScript Temporal API и подробно изучим его функции и возможности.

Дата и время являются важной частью любого приложения, будь то простой список дел или сложная система планирования. К сожалению, работа с датами в JavaScript была проблемой для многих разработчиков из-за ограниченной встроенной функциональности и несоответствий в разных браузерах и средах. Это привело к популярности таких библиотек, как Moment.js и DateFns, которые предоставляют богатый набор инструментов для работы с датами. Однако даже с этими библиотеками по-прежнему возникают проблемы с точностью, согласованностью и производительностью. Особенно, когда мы говорим о времени и часовых поясах.

Расчет времени и часовых поясов может быть сложным из-за сложной природы времени. Время не является константой и зависит от таких факторов, как вращение Земли, високосные годы, переход на летнее время и многое другое. Кроме того, часовые пояса добавляют еще один уровень сложности, поскольку они основаны на геополитических границах, а не на физических. Это также может быть особенно сложно при работе с историческими датами, так как правила часового пояса могут меняться с течением времени.

Чтобы решить эту проблему, появился Temporal API: новый стандарт для работы с датами в JavaScript.

Temporal API — это новый, основанный на стандартах подход в JavaScript для работы с датами, временем, длительностью и периодами. Это глобальный объект, который действует как пространство имен верхнего уровня (например, Math) и предоставляет простой, согласованный и эффективный способ выполнения широкого спектра операций с временными данными, от разбора дат из строк до выполнения сложных арифметических вычислений. . Temporal API является частью API интернационализации ECMAScript и основан на последних стандартах Международной организации по стандартизации (ISO). Это означает, что он обеспечивает надежное, высококачественное решение, поддерживаемое международным сообществом экспертов.

Если вы хотите узнать больше о некоторых проблемах JavaScript Date и мотивах Temporal, см. раздел Исправление JavaScript Date.

Почему Temporal API лучше существующих библиотек?

Есть несколько причин, по которым Temporal API является лучшим решением, чем текущие библиотеки, такие как Moment.js и DateFns.

• Как я уже говорил, это основанный на стандартах API, что означает, что он обеспечивает последовательный и надежный способ работы с датами и временем, который не зависит от одной библиотеки и от того, как создатель управляет ею;
• Он высоко оптимизирован для производительности с упором на предоставление быстрых и эффективных алгоритмов для работы с временными данными;
• Он предоставляет богатый набор функций, специально предназначенных для работы с датами и временем, таких как встроенная поддержка часовых поясов, високосных лет и високосных секунд;
• Он разработан, чтобы быть простым в использовании, с простым и интуитивно понятным API, который легко понять и интегрировать в ваши приложения.

Теперь давайте рассмотрим некоторые функции Temporal API

В этом посте мы рассмотрим некоторые из наиболее важных типов данных и статических методов, доступных в Temporal. Если вы хотите изучить их все, перейдите к Temporal docs.

ПлаинДатеВремя

PlainDateTime представляет календарную дату и время по настенным часам, которые не содержат информации о часовом поясе.

Чтобы создать объект PlainDateTime, вы можете использовать конструктор Temporal.PlainDateTime, который принимает year, month и day в качестве обязательных аргументов, а также hour, minute, second, millisecond, microsecond, nanosecond и calendar в качестве необязательных аргументов, в этом заказ.

const dateTime = new Temporal.PlainDateTime(2023, 2, 23, 10, 30, 0, 0);

Это создает объект PlainDateTime, представляющий 23 февраля 2023 года в 10:30.

Темпоральный объект предлагает множество служебных методов внутри себя.

const dateTime = new Temporal.PlainDateTime(2023, 2, 23, 10, 30, 0, 0);

console.log(dateTime.year);                  
// 2023
console.log(dateTime.hour);                  
// 10
console.log(dateTime.minute);                
// 30
console.log(dateTime.nanosecond);            
// 0
console.log(dateTime.calendar.toString());   
// iso8601

Альтернативный способ — использовать объект Temporal.Now, у которого есть несколько методов, дающих информацию о текущем времени и дате.

Используя Now, у нас также есть доступ к тем же статическим методам, что и при использовании конструктора PlainDateTime.

const today = Temporal.Now.plainDateTimeISO()
console.log(today.toString()); 
// 2023-02-23T10:45:40.438072454
console.log(today.toPlainMonthDay().toString());
// '02-23'

ЗонедДатеВремя

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

Мы можем сделать то же самое, что и withPlainDateTime, используя конструктор Temporal.ZonedDateTime, который принимает обязательные epochNanoseconds (bigint) и необязательные timeZone и calendar в качестве аргументов, или мы также можем использовать Temporal.Now.

const zonedDateTime = new Temporal.ZonedDateTime(
  1677265360653057483n, 'America/Campo_Grande', 'iso8601'
);
console.log(zonedDateTime.toString()); 
// 2023-02-24T15:02:40.653057483-04:00[America/Campo_Grande]
console.log(zonedDateTime.startOfDay().toString()) 
// 2023-02-24T00:00:00-04:00[America/Campo_Grande]
console.log(zonedDateTime.dayOfWeek);        
// 5
console.log(zonedDateTime.day);              
// 24
console.log(zonedDateTime.epochNanoseconds); 
// 1677265360653057483n

const todayZoned = Temporal.Now.zonedDateTimeISO()
console.log(todayZoned.toString());
// 2023-02-23T16:44:32.454458232-04:00[America/Campo_Grande]

PlainDate

Объект PlainDate представляет календарную дату, не связанную с конкретным временем или часовым поясом.

const today = Temporal.Now.plainDateISO()
console.log(today.toString())
// 2023-02-23
const date1 = new Temporal.PlainDate(2023, 02, 19)
console.log(date1.toString())
// 2023-02-19
const date2 = Temporal.PlainDate.from("2023-02-19")
console.log(date2.toString())
// 2023-02-19
const date3 = Temporal.PlainDate.from({ year: 2023, month: 2, day: 19 })
console.log(date3.toString())
// 2023-02-19

Обратите внимание, что мы использовали статический метод from выше, а их довольно много, и мы немного поговорим о них позже.

Простое время

Объект PlainTime представляет время настенных часов, не связанное с определенной датой или часовым поясом.

const today = Temporal.Now.plainTimeISO()
console.log(today.toString())
// 16:36:50.739773623
const time1 = new Temporal.PlainTime(12, 25)
console.log(time1.toString())
// 12:25:00
const time2 = Temporal.PlainTime.from("05:43:17")
console.log(time2.toString())
// 05:43:17
const time3 = Temporal.PlainTime.from({ hour: 1, minute: 3, second: 44 })
console.log(time3.toString())
// 01:03:44

Мгновенное

Мгновенный – это момент времени (называемый "точное время") с точностью до наносекунд. Время всегда указано в формате UTC, а информация о часовом поясе или календаре отсутствует. Чтобы получить локальные единицы даты/времени, такие как год, месяц, день или час, Temporal.Instant необходимо объединить с экземпляром Temporal.TimeZone или строкой часового пояса.

const now = Temporal.Now.instant()
console.log(now.toString())
// 2023-02-23T13:53:45.308214163Z

const dateInstant = Temporal.Instant.from("2000-01-01T00:00+04:00")
console.log(dateInstant.toString())
// 1999-12-31T20:00:00Z
console.log(dateInstant.year); 
// => undefined

const tokyoZonedDateTime = dateInstant.toZonedDateTimeISO('Asia/Tokyo');
console.log(tokyoZonedDateTime.toString())
// 2000-01-01T05:00:00+09:00[Asia/Tokyo]'
console.log(tokyoZonedDateTime.year);
// 2000

Продолжительность

Длительность представляет продолжительность времени, которую можно использовать в арифметике даты/времени, и при печати она создает строку в соответствии с нотацией ISO 8601 для продолжительности.

const duration = Temporal.Duration.from({ years: 1, days: 5, months: 22 });
console.log(duration.toString());
// P1Y22M5D
console.log(new Temporal.Duration(1, 2, 3, 4, 5, 6, 7, 888, 999, 0).toString());
// P1Y2M3W4DT5H6M7.888999S

const duration1 = Temporal.Duration.from({ hours: 2, minutes: 30, seconds: 10 });
// PT2H30M10S (2 hours, 30 minutes, and 10 seconds)
const duration2 = Temporal.Duration.from({ hours: 1, minutes: 45, seconds: 30 });
// PT1H45M30S (1 hours, 45 minutes, and 30 seconds)

// Adding two durations
const sum = duration1.add(duration2);
console.log(sum.toString()); 
// PT4H15M40S (4 hours, 15 minutes, and 40 seconds)

// Subtracting two durations
const difference = duration1.subtract(duration2);
console.log(difference.toString()); 
// PT44M40S (44 minutes and 40 seconds)

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

В API есть несколько статических методов, некоторые из них мы видели в этом посте, например from, add и subtract. Они предоставляют служебные функции для работы с временными данными, и вы можете использовать их для преобразования типов, выполнения некоторых вычислений, сравнения и сортировки дат и многого другого.

Вот несколько примеров того, что мы можем сделать:

• Подсчитайте, сколько дней осталось до конца года

const today = Temporal.Now.plainDateTimeISO(); // get current date and time
const end = Temporal.PlainDate.from('2023-12-31'); // set the end of the year

const diff = Temporal.Duration.from({ days: today.until(end).days });
console.log(`Days until end of year: ${diff.days}`); 
// Days until end of year: 310

• Планирование задач

let start = Temporal.Now.plainDateTimeISO();
const duration = Temporal.Duration.from({ hours: 1, minutes: 30, seconds: 0 });
const end = start.add(duration);
const interval = Temporal.Duration.from({ minutes: 15 });

while (Temporal.PlainDateTime.compare(start, end) < 0) {
  console.log(`Scheduled task for: ${start.toString()}`);
  start = start.add(interval);
}
/* 
  Scheduled task for: 2023-02-23T15:51:50.394704559
  Scheduled task for: 2023-02-23T16:06:50.394704559
  Scheduled task for: 2023-02-23T16:21:50.394704559
  Scheduled task for: 2023-02-23T16:36:50.394704559
  Scheduled task for: 2023-02-23T16:51:50.394704559
  Scheduled task for: 2023-02-23T17:06:50.394704559
*/

• Время прибытия рейса в часовой пояс пункта назначения (из документов)

const departure = Temporal.ZonedDateTime.from('2020-03-08T11:55:00+08:00[Asia/Hong_Kong]');
const flightTime = Temporal.Duration.from({ minutes: 775 });

const arrival = departure.add(flightTime).withTimeZone('America/Los_Angeles');
console.log(arrival.toString())
// '2020-03-08T09:50:00-07:00[America/Los_Angeles]'

Как видите, API предоставляет надежный набор методов, которые могут быть действительно полезны во многих различных ситуациях и наверняка упростят жизнь разработчика, когда дело доходит до работы с датами и временем в JavaScript.

Как это использовать?

На данный момент (март 2023 г.) API по-прежнему находится на этапе 3 (это означает, что черновик почти окончательный и готов к последней обратной связи), и ни один браузер не поддерживает его в данный момент, но они должны поддерживать его в ближайшее время.

Если вы хотите протестировать его сейчас, вы можете использовать этот полифилл: @js-temporal/polyfill. Просто установите его, и вы готовы к работе.

Рекомендации

• Временные документы
• Гитхаб-репозиторий
• Temporal: новая форма обработки данных с помощью JavaScript
• ESMAScript — Знакомство со всеми этапами процесса TC39

Вот и все! Надеюсь, вам понравилось читать, пока!