Использование в методах

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

const d = dayjs();

Каждый вызов метода не изменяет исходный объект, а создаёт новую копию с применёнными изменениями. Это ключевая особенность, определяющая стиль использования библиотеки.

Арифметические методы дат

add — добавление времени

Метод add используется для прибавления интервалов времени к текущей дате. Интервал задаётся числом и единицей измерения.

dayjs().add(5, 'day');
dayjs().add(2, 'month');
dayjs().add(1, 'year');

Поддерживаемые единицы:

  • day
  • month
  • year
  • hour
  • minute
  • second
  • millisecond

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

dayjs('2024-01-31').add(1, 'month'); // 2024-02-29 или 28 в зависимости от года

subtract — вычитание времени

Метод subtract работает аналогично add, но выполняет обратную операцию.

dayjs().subtract(10, 'day');
dayjs().subtract(3, 'hour');

Комбинирование add и subtract часто применяется для построения сложных временных вычислений:

dayjs()
  .add(1, 'month')
  .subtract(7, 'day');

Методы начала и конца периода

startOf — начало временного интервала

Метод startOf устанавливает дату в начало указанного периода.

dayjs().startOf('day');
dayjs().startOf('month');
dayjs().startOf('year');

Примеры поведения:

  • day → 00:00:00
  • month → первое число месяца, 00:00:00
  • year → 1 января, 00:00:00

endOf — конец временного интервала

Метод endOf устанавливает дату в конец указанного периода.

dayjs().endOf('day');
dayjs().endOf('month');
dayjs().endOf('year');

Особенность реализации заключается в установке максимального значения времени:

  • 23:59:59.999 для дня
  • последний день месяца с максимальным временем
  • конец года — 31 декабря 23:59:59.999

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

format — преобразование в строку

Метод format преобразует объект даты в строковое представление.

dayjs().format('YYYY-MM-DD');
dayjs().format('DD.MM.YYYY');
dayjs().format('HH:mm:ss');

Основные токены форматирования:

  • YYYY — год
  • MM — месяц
  • DD — день
  • HH — часы (24-часовой формат)
  • mm — минуты
  • ss — секунды

Комбинирование токенов позволяет формировать любые представления даты:

dayjs().format('YYYY-MM-DD HH:mm');

Сравнение дат

isBefore — проверка «раньше»

Метод isBefore проверяет, предшествует ли одна дата другой.

dayjs('2024-01-01').isBefore('2024-01-10');

Можно указать точность сравнения:

dayjs('2024-01-01').isBefore('2024-02-01', 'month');

isAfter — проверка «позже»

dayjs('2024-02-01').isAfter('2024-01-01');

С указанием уровня точности:

dayjs('2024-02-01').isAfter('2024-01-01', 'year');

isSame — равенство дат

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

dayjs('2024-01-01').isSame('2024-01-01');
dayjs('2024-01-01').isSame('2024-01-15', 'month');

Разница между датами

diff — вычисление интервала

Метод diff возвращает разницу между двумя датами.

dayjs('2024-01-10').diff('2024-01-01');

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

Можно указать единицы измерения:

dayjs('2024-01-10').diff('2024-01-01', 'day');
dayjs('2024-01-10').diff('2024-01-01', 'month');

Также поддерживается округление:

dayjs('2024-01-10').diff('2024-01-01', 'day', true);

Цепочки методов (chaining)

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

dayjs()
  .add(1, 'month')
  .subtract(2, 'day')
  .startOf('day')
  .format('YYYY-MM-DD');

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

Работа с клонами и неизменяемостью

Каждый метод Day.js возвращает новый экземпляр даты. Это исключает побочные эффекты:

const a = dayjs();
const b = a.add(1, 'day');

a.format(); // исходное значение
b.format(); // изменённое значение

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

Методы проверки валидности

isValid — проверка корректности даты

dayjs('invalid-date').isValid();

Возвращает логическое значение, позволяя отфильтровывать некорректные входные данные до выполнения дальнейших операций.

Методы доступа к компонентам даты

Day.js предоставляет методы для извлечения отдельных частей даты:

dayjs().year();
dayjs().month();
dayjs().date();
dayjs().hour();
dayjs().minute();
dayjs().second();

Особенность:

  • month() возвращает значение от 0 до 11
  • остальные методы возвращают стандартные календарные значения

Также возможна установка значений:

dayjs().year(2025);
dayjs().month(5);

Универсальная работа с единицами времени

Многие методы поддерживают передачу единицы времени в виде строки, что унифицирует работу с интервалами:

dayjs().add(10, 'minute');
dayjs().subtract(2, 'year');
dayjs().diff('2023-01-01', 'month');

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

Преобразование в стандартные типы

toDate — преобразование в объект Date

dayjs().toDate();

Возвращает нативный объект JavaScript Date, что позволяет интегрировать Day.js с API, требующими стандартные типы.

valueOf — числовое представление

dayjs().valueOf();

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

Переиспользование вычислений через методы

Методы Day.js часто комбинируются для построения логики временных диапазонов:

const start = dayjs().startOf('month');
const end = dayjs().endOf('month');

const diffDays = end.diff(start, 'day');

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

Оглавление