Управление датами в JS стало проще с помощью date-fns

Обзор

Вы когда-нибудь писали способ узнать время дня по Гринвичу? или интересно, нужно ли мне преобразовать время в UTC? В большинстве приложений есть общие манипуляции с датой и временем, которые часто повторяются, и через некоторое время их становится очень трудно поддерживать. В дополнение к этому при интернационализации приложения манипуляции с датой и временем - одна из ключевых проблем, с которыми вы столкнетесь. Настолько, что вы потеряете счет времени, исправляя все это 😉.

Tick ​​Tock, Tick Tock! Не бойтесь, мы вас прикрыли. date-fns - один из таких пакетов, который предоставляет простые вспомогательные функции для управления датой и временем. Благодаря доступным опциям интернационализации вы всегда можете воспользоваться этим и быстро выйти на международный уровень.

Особенности

Начать работу с date-fns довольно просто. Его можно установить, выполнив команду npm install date-fns. Все вспомогательные методы можно либо импортировать через основной пакет, либо вы можете установить только необходимый подмодуль. Одним из них является fp, у которого есть две копии методов с параметрами форматирования и без них.

/* Babel or ES6 */
import {methodName} from "date-fns";
/* Node or requireJs */
const methodName = require("date-fns").methodName;

Он заслуживает дополнительных очков, поскольку обеспечивает поддержку машинописного текста без каких-либо дополнительных пакетов и помогает разработчикам избавиться от необходимости поддерживать другую зависимость разработчика. Его структура пакета способствует tree-shaking, что помогает в увеличении общего размера приложения, и поэтому мы предлагаем установить основной модуль, поскольку в него будут включены только необходимые методы. Разработчик должен обрабатывать один из трех типов, а именно:

• Интервал. Это простое представление временного интервала между двумя датами. Он используется исключительно в методах, работающих с временными интервалами.
• Локаль. Представляет данные о желаемой стране, которые используются при форматировании даты.
• Продолжительность: основное различие между стандартным объектом Date и объектом Duration заключается в том, что последний не содержит никакой информации о локали. Продолжительность может частично состоять из любого из следующего:

{    
    years, months, weeks, days, hours, minutes, seconds      
}

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

Помощники времени

Эти помощники в основном сосредоточены на манипулировании и проверке предикатов по таким аспектам времени, как секунды, минуты, часы. Он предоставляет полезные утилиты на временном отрезке типа Interval. Следующая таблица дает хороший обзор нескольких методов:

Вот несколько примеров, которые помогут вам познакомиться с вышеуказанными функциями:

const interval1 = {
  start: new Date(2014, 0, 10), // 10th Jan 2014
  end: new Date(2014, 11, 21) // 21st Dec 2014
};
const interval2 = {
  start: new Date(2014, 6, 10), // 10th July 2014
  end: new Date(2015, 0, 10) // 10th Jan 2015
};
const interval3 = {
  start: new Date(2015, 6, 10), // 10th July 2015
  end: new Date(2020, 11, 10) // 10th Dec 2020
};
const interval4 = {
  start: new Date(2015, 11, 10), // 10th Dec 2015
  end: new Date(2015, 11, 10) // 10th Dec 2015
};

• areIntervalsOverlapping:

console.log(areIntervalsOverlapping(interval1, interval2)); 
// => true
console.log(areIntervalsOverlapping(interval1, interval3));  
// => false

• eachDayOfInterval:

console.log(eachDayOfInterval(interval4));
// => [Sun Jan 10 2016 00:00:00 GMT+0530 (India Standard Time)]

• isWithinInterval:

console.log(isWithinInterval(Date.now(), interval1)); // => false
console.log(isWithinInterval(Date.now(), interval3)); // => true

• fromUnixTime:

console.log(fromUnixTime(1595157314)); 
// => Sun Jul 19 2020 16:45:14 GMT+0530 (India Standard Time)

• getTime:

console.log(getTime(Date.now())); // => 1595157440507

• getUnixTime:

console.log(getUnixTime(Date.now())); // => 1595157492

• startOfMinute:

console.log(startOfMinute(Date.now())); // => Sun Jul 19 2020 17:02:00 GMT+0530 (India Standard Time)

• isThisMinute:

console.log(isThisMinute(Date.now())); // => true
console.log(isThisMinute(new Date(2020, 6, 10, 17, 4))); // => false

• roundToNearestMinute: округляет время до начала минуты, к которой данная дата ближе всего. Мы можем изменить это, указав параметр nearestTo, который может находиться в диапазоне от 1 до 30. Если он одинаково удален как от предыдущего, так и от следующего интервала, то он округляется в большую сторону.

console.log(roundToNearestMinutes(Date.now())); 
// => Sun Jul 19 2020 17:12:00 GMT+0530 (India Standard Time)
console.log(roundToNearestMinutes(Date.now(), {nearestTo: 15})); 
// => // => Sun Jul 19 2020 17:15:00 GMT+0530 (India Standard Time)
console.log(roundToNearestMinutes(new Date(2020, 6, 10, 17, 13), {nearestTo: 8})); 
// => Fri Jul 10 2020 17:16:00 GMT+0530 (India Standard Time)
console.log(roundToNearestMinutes(new Date(2020, 6, 10, 17, 11), {nearestTo: 8})); 
// => Fri Jul 10 2020 17:08:00 GMT+0530 (India Standard Time)
/* here 17:12 is equidistant from 17:8 and 17:16, the method rounds it off to 16 */
console.log(roundToNearestMinutes(new Date(2020, 6, 10, 17, 12), {nearestTo: 8})); 
// => Sun Jul 19 2020 17:16:00

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

• Подсчитайте, пришло ли бронирование во время регистрации:

const checkIfBookingIsValid = timeOfBooking => isWithinInterval(timeOfBooking, {
  start: startTimeOfRegistration,
  end: endTimeOfRegistration
});

• Укажите, когда будет выполняться следующее запланированное задание:

const getNextStartTimeOfJob = (lastExecutionTime, {days, hours, minutes, seconds}) => add(lastExecutionTime, {days, hours, minutes, seconds})

Помощники по свиданию

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

Большинство методов, описанных выше для недель, расширены до месяцев, кварталов и лет. например differenceInMonths, differenceInCalendarMonths, isSameMonth, isSameYear, setMonth, setYear, eachWeekendOfMonth и т. д.

Вот несколько примеров, которые помогут вам познакомиться с вышеуказанными функциями:

• differenceInWeeks: дата слева должна быть последней, иначе метод вернет -1.

console.log(differenceInWeeks(new Date(2015, 11, 22), new Date(2015, 11, 10))); // => 1

• differenceInCalendarWeeks:

console.log(differenceInCalendarWeeks(new Date(2015, 11, 25), new Date(2015, 11, 10))); // => 2

• getWeek: мы также можем указать, в какой день недели начинается неделя, с помощью флага weekStartsOn. Диапазон значений от 0 до 6, где 0 - воскресенье. Номер недели начинается с 1.

console.log(getWeek(Date.now())); // => 30
console.log(getWeek(Date.now(), {weekStartsOn: 1})); // => 29

• isThisWeek:

console.log(isThisWeek(Date.now())); // => true

• eachWeekendOfYear

console.log(eachWeekendOfYear(Date.now())); 
// => [Sat Jan 04 2020 00:00:00 GMT+0530 (India Standard Time)...]

Общие помощники и варианты использования

Простые операции

Помимо вышеперечисленного, мы можем складывать, вычитать и получать разницу между двумя Date объектами, и их имена очень интуитивно понятны, как показано ниже:

Вот несколько примеров, подробно описывающих вышеуказанные методы:

addQuarters(new Date("2020-01-01"), 3); 
// => Thu Oct 01 2020 05:30:00 GMT+0530 (India Standard Time)
max([new Date(2020, 2, 22), new Date(2020, 2, 2)]); 
// => Sun Mar 22 2020 00:00:00 GMT+0530 (India Standard Time)

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

Один из наиболее распространенных вопросов - отформатировать дату и время в определенном формате, который соответствует требованиям приложения. Это также означает, что это наиболее самоуправляемый метод, который может выйти из-под контроля, если формат изменится. Утилита date-fns format имеет широкий спектр параметров форматирования, а подпись метода настолько проста, что мы можем изменить формат с обновлением строки.

format(date, formatOptions)

Список formatOptions обширен, но некоторые из наиболее часто используемых примеров включают:

const date = new Date("2020-07-19 18:32:00");
format(date, "yy-MM-dd") => 20-07-19
format(date, "dd/MM/yyyy") => 19/07/2020
format(date, "do LLL yyyy") => 19th Jul 2020
format(date, "HH:mm:ss") => 18:32:00
format(date, "dd/MM/yyy hh:mm:ss x") => 19/07/2020 12:32:00 +0530
format(date, "dd/MM/yyy hh:mm:ss O) => 19/07/2020 06:32:00 GMT+5:30
format(new Date("2020-07-19 00:32:00"), "hh:mm:ss a") => 12:32:00 PM
format(new Date("2020-07-19 12:00:00"), "hh:mm:ss b") => 12:00:00 noon
format(new Date("2020-07-19 00:32:00"), "kk:mm:ss") => 24:32:00
format(new Date("2020-07-19 00:32:00"), "KK:mm:ss") => 00:32:00
//second timestamp
format(date, "t") => 1595163720
//millisecond timestamp
format(date, "T") => 1595163720000
/* some really interesting built-ins */
//Localized date
format(date, "P") => 07/19/2020
format(date, "PPPP") => Sunday, July 19th, 2020
format(date, "PPPP G") => Sunday, July 19th, 2020 AD
//Localized time
format(date, "p") => 6:32 PM
format(date, "pppp") => 6:32:00 PM GMT+05:30
// Localized date and time
format(date, "PPPPpppp") => Sunday, July 19th, 2020 at 6:32:00 PM GMT+05:30

Если вам не требуются такие мелкие параметры локали при форматировании, вы можете использовать lightFormat. Он называется таким же способом форматирования и не учитывает некоторые параметры, относящиеся к Era, Quarter, Extended year.

lightFormat(new Date("2020-07-19 18:32:00"), "dd/MM/yy") => 19/07/20
lightFormat(new Date("2020-07-19 18:32:00"), "p") =>  throws RangeError

date-fns позволяет нам форматировать интервалы и продолжительность с помощью методов formatDistance и formatDuration. Основное различие между ними заключается в том, что первый форматирует дату относительно заданной даты, а второй просто представляет продолжительность словами. formatDistanceToNow совпадает с formatDistance со ссылкой, установленной на now()

formatDistance(Date.now(), sub(Date.now(), {hours: 4})); 
// => About 4 hours
formatDistance(Date.now(), sub(Date.now(), {hours: 4}), {addSuffix: true}); 
// => in about 4 hours
formatDistance(Date.now(), sub(Date.now(), {seconds: 4}), { addSuffix: true, includeSeconds: true}); 
// => in less than 5 seconds
formatDistanceStrict(Date.now(), sub(Date.now(), {seconds: 4}), { addSuffix: true, includeSeconds: true }); 
// => in 4 seconds
formatDuration({days: 4, hours: 3}); // => 4 days 3 hours
formatDuration({days: 4, hours: 3}, {delimiter: "|"}); 
// => 4 days|3 hours
formatDuration({days: 4, hours: 3, months: 44}, {delimiter: "|", format: [ "months", "hours"]}) 
// => 44 months|3 hours

Формат ISO

Формат даты ISO - это стандартный способ представления даты, определяемой как YYYY-MM-DDTHH:mm:ss.sssZ, тогда как UTC является основным стандартом времени. Формат ISO всегда имеет стандарт времени UTC и обозначается Z в конце. date-fns имеет методы для достижения всех вышеперечисленных функций в формате ISO. Некоторые из них проиллюстрированы ниже:

Интернационализация

Большинство разработчиков и приложений сталкиваются с проблемой интернационализации, поскольку она не входит в список TODO. date-fns имеет сопутствующий модуль date-fns-tz для обработки форматирования и преобразования часового пояса. Этот вспомогательный модуль можно установить, запустив npm install date-fns-tz, и он также обеспечивает поддержку машинописного текста.

Преобразование зонального времени в UTC и ISO

Если в вашей системе дата и время хранятся в определенном часовом поясе и вам необходимо преобразовать его в UTC, тогда вам подойдет метод zonedTimeToUTC. Требуется дата и часовой пояс в формате IANA времени ввода даты.

zonedTimeToUTC(date, originTimeZone)
examples:
zonedTimeToUtc(new Date("Sun Jul 19 2020 14:41:43"), "America/Los_Angeles"); 
// => Mon Jul 20 2020 03:11:43 GMT+0530 (India Standard Time)
zonedTimeToUtc(new Date("Sun Jul 19 2020 14:41:43"), "Asia/Bangkok"); 
// => Sun Jul 19 2020 13:11:43 GMT+0530 (India Standard Time)

Преобразование всемирного координированного времени в зональное время

Рассмотрим вариант использования, когда вы должны отправлять уведомления или электронные письма своим пользователям. Для них это будет проблемой, если вы отправляете данные о времени и дате в формате UTC, и они должны преобразовать их в свое местное время. Следовательно, другим распространенным вариантом использования является преобразование времени UTC, хранящегося в базе данных, в любой часовой пояс. Это достигается utcToZonedTime. Здесь также используются дата и часовой пояс в формате IANA, но часовой пояс представляет собой зону, в которую вы хотите его преобразовать.

utcToZonedTime(date, destinationTimeZone)
examples:
console.log(utcToZonedTime(Date.now(), "Asia/Kolkata")); 
// => Mon Jul 20 2020 02:06:59 GMT+0530 (India Standard Time)
console.log(utcToZonedTime(Date.now(), "America/Los_Angeles")); 
// Sun Jul 19 2020 13:36:59 GMT+0530 (India Standard Time)

Метрики оценки

Ознакомьтесь с пакетом и некоторыми материалами для чтения

• Https://date-fns.org/v2.14.0/docs
• Попробуйте эти методы на https://codesandbox.io/s/lyq47o17z9.
• Https://www.npmjs.com/package/date-fns-tz
• Https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Видеообзор пакета

Скоро появится видеообзор пакета с интересными примерами использования и подробным изучением функций! Для получения дополнительной информации по теме посетите Обзоры без упаковки.

Раскрытие информации

Содержание и оценки, упомянутые в этой статье / обзоре, являются субъективными и являются личным мнением авторов Unpackaged Reviews, основанным на повседневном использовании и исследованиях на популярных форумах разработчиков. Они не отражают точку зрения какой-либо компании, и на них не влияет спонсорство / сотрудничество.