Работа с часами, минутами, секундами

Работа с временными единицами уровня часов, минут и секунд в date-fns основана на принципе неизменяемости данных: каждая функция возвращает новый объект Date, не изменяя исходный. Это упрощает прогнозирование поведения кода и снижает количество побочных эффектов при манипуляциях со временем.

Извлечение компонентов времени

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

Получение часов

Функция getHours возвращает значение часов в диапазоне от 0 до 23:

import { getHours } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const hours = getHours(date);
// 14

Часы извлекаются из локального времени, что важно учитывать при работе с часовыми поясами.

Получение минут

import { getMinutes } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const minutes = getMinutes(date);
// 35

Получение секунд

import { getSeconds } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const seconds = getSeconds(date);
// 50

Установка значений времени

Функции установки позволяют изменить конкретную часть времени без необходимости вручную пересобирать дату.

Установка часов

import { setHours } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const upd ated = setHours(date, 9);
// 2026-05-22T09:35:50

Остальные компоненты времени сохраняются без изменений.

Установка минут

import { setMinutes } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const upd ated = setMinutes(date, 10);
// 2026-05-22T14:10:50

Установка секунд

import { setSeconds } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const upd ated = setSeconds(date, 0);
// 2026-05-22T14:35:00

Одновременная настройка времени

date-fns предоставляет набор функций для комплексного изменения времени, что удобно при нормализации значений.

import { se t } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const upd ated = se t(date, {
  hours: 8,
  minutes: 0,
  seconds: 0
});

// 2026-05-22T08:00:00

Функция set позволяет централизованно управлять несколькими компонентами времени без цепочек вызовов.

Добавление времени

Функции добавления изменяют дату, увеличивая или уменьшая её компоненты.

Добавление часов

import { addHours } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const result = addHours(date, 5);
// 2026-05-22T19:35:50

При переходе через границу суток автоматически изменяется дата.

Добавление минут

import { addMinutes } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const result = addMinutes(date, 30);
// 2026-05-22T15:05:50

Функция корректно обрабатывает переполнение минут:

addMinutes(new Date('2026-05-22T14:50:00'), 20);
// 2026-05-22T15:10:00

Добавление секунд

import { addSeconds } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const result = addSeconds(date, 15);
// 2026-05-22T14:36:05

Вычитание времени

Для обратных операций используются функции subHours, subMinutes, subSeconds.

Вычитание часов

import { subHours } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const result = subHours(date, 3);
// 2026-05-22T11:35:50

Вычитание минут

import { subMinutes } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const result = subMinutes(date, 40);
// 2026-05-22T13:55:50

Вычитание секунд

import { subSeconds } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const result = subSeconds(date, 70);
// 2026-05-22T14:34:40

Работа с переполнением времени

Особенность date-fns заключается в автоматической нормализации значений:

  • 60 минут → +1 час
  • 60 секунд → +1 минута
  • отрицательные значения корректно перераспределяются назад

Пример переполнения минут:

import { addMinutes } from 'date-fns';

const date = new Date('2026-05-22T10:50:00');

const result = addMinutes(date, 125);
// 2026-05-22T12:55:00

Здесь 125 минут преобразуются в 2 часа и 5 минут.

Сравнение временных компонентов

Для анализа разницы используются функции вычисления интервалов.

Разница в часах

import { differenceInHours } from 'date-fns';

const a = new Date('2026-05-22T10:00:00');
const b = new Date('2026-05-22T15:30:00');

differenceInHours(b, a);
// 5

Функция возвращает целое число, отбрасывая дробные части.

Разница в минутах

import { differenceInMinutes } from 'date-fns';

differenceInMinutes(
  new Date('2026-05-22T10:30:00'),
  new Date('2026-05-22T10:00:00')
);
// 30

Разница в секундах

import { differenceInSeconds } from 'date-fns';

differenceInSeconds(
  new Date('2026-05-22T10:00:45'),
  new Date('2026-05-22T10:00:00')
);
// 45

Нормализация временных значений

При работе с пользовательским вводом часто требуется привести значения к корректному диапазону.

Пример ручной нормализации:

import { se t, addMinutes } from 'date-fns';

let date = se t(new Date(), {
  hours: 1,
  minutes: 120
});

date = addMinutes(date, 0);

// результат будет приведён к корректному времени автоматически

Даже при некорректной установке минут библиотека перераспределяет значение в часы.

Комбинирование операций

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

import { setHours, addMinutes, subSeconds } from 'date-fns';

const date = new Date('2026-05-22T12:00:00');

const result =
  subSeconds(
    addMinutes(
      setHours(date, 18),
      45
    ),
    30
  );

// 2026-05-22T18:44:30

Такая композиция позволяет точно моделировать изменения времени без ручных вычислений.

Обнуление временных компонентов

Часто требуется привести время к началу интервала.

import { setHours, setMinutes, setSeconds } from 'date-fns';

const date = new Date('2026-05-22T14:35:50');

const normalized =
  setSeconds(
    setMinutes(
      setHours(date, 0),
      0
    ),
    0
  );

// 2026-05-22T00:00:00

Этот подход используется при группировке данных по дням.

Работа с границами суток

При добавлении часов или минут возможен переход на следующий день:

import { addHours } from 'date-fns';

const date = new Date('2026-05-22T22:30:00');

const result = addHours(date, 5);
// 2026-05-23T03:30:00

Аналогично при вычитании:

import { subHours } from 'date-fns';

const date = new Date('2026-05-22T01:15:00');

const result = subHours(date, 3);
// 2026-05-21T22:15:00

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

Все операции выполняются в локальной временной зоне среды выполнения. Это означает:

  • одинаковый код может давать разные результаты в разных часовых поясах
  • преобразование к UTC требует дополнительных функций форматирования или использования специализированных утилит

Типовые сценарии использования

  • таймеры и обратный отсчёт с точностью до секунд
  • планирование задач с точным временем выполнения
  • вычисление длительности операций
  • нормализация временных меток до минутного или секундного уровня
  • построение временных шкал событий

Работа с часами, минутами и секундами в date-fns строится вокруг предсказуемых чистых функций, каждая из которых выполняет строго ограниченную операцию над объектом даты.

Оглавление