Параметры методов

Библиотека Day.js строится вокруг компактного набора методов, где поведение почти каждого вызова определяется типами и порядком передаваемых параметров. Основные категории параметров можно разделить на:

  • строковые значения (форматы, единицы измерения, локали);
  • числовые значения (смещения, индексы, длительности);
  • объекты конфигурации (расширенные опции парсинга и форматирования);
  • булевы флаги (строгий режим, дополнительные режимы сравнения);
  • даты и временные сущности (Date, dayjs-объекты, timestamps).

Понимание структуры аргументов критично, поскольку Day.js не использует перегруженные сигнатуры в стиле TypeScript-методов с явной типизацией — различие поведения определяется именно комбинацией типов входных данных.

Конструктор dayjs() и его параметры

Базовая функция создания экземпляра имеет несколько форм вызова:

1. Без параметров

dayjs()

Используется текущее время системы. Аргументы отсутствуют, поведение фиксированное.

2. Строка, число или Date

dayjs('2024-01-01')
dayjs(1710000000000)
dayjs(new Date())

Тип входного параметра определяет стратегию парсинга:

  • строка → парсинг ISO или формата из плагинов;
  • число → Unix timestamp в миллисекундах;
  • Date → прямое преобразование без анализа формата.

3. Строка + формат + строгий режим

dayjs('01-02-2024', 'DD-MM-YYYY', true)

Сигнатура:

dayjs(input, format?, strict?)

Параметры:

  • input — строка даты;
  • format — строка шаблона;
  • strict — булево значение.

Строгий режим

Булев флаг strict изменяет алгоритм парсинга:

  • true — полное соответствие формату;
  • false или отсутствует — допускается частичное совпадение.

Особенность: строгий режим влияет только при наличии формата, иначе игнорируется.

4. Множественные форматы (плагин CustomParseFormat)

При подключении плагина допускается массив форматов:

dayjs('12-01-2024', ['DD-MM-YYYY', 'MM-DD-YYYY'], true)

Здесь параметры:

  • строка входа;
  • массив строк форматов;
  • булев строгий режим.

Алгоритм перебирает форматы последовательно до первого совпадения.

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

add(number, unit)

Метод смещения времени имеет фиксированную сигнатуру:

dayjs().add(2, 'day')

Параметры:

  • number — числовое значение (может быть отрицательным);
  • unit — строка единицы измерения.

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

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

Особенность: строка unit не нормализуется автоматически, требуется точное совпадение с внутренним словарём.

subtract(number, unit)

Идентична add, но знак операции инвертирован:

dayjs().subtract(10, 'minute')

Параметры полностью повторяют структуру add.

diff(other, unit?, floating?)

Сигнатура:

dayjs().diff(dayjs(), 'day', true)

Параметры:

  • other — дата сравнения (dayjs, Date, timestamp);
  • unit — строка единицы измерения;
  • floating — булев флаг дробного результата.

Поведение параметров

  • без unit возвращается разница в миллисекундах;
  • с unit результат конвертируется;
  • floating = true возвращает дробные значения;
  • floating = false округляет вниз.

startOf(unit) и endOf(unit)

dayjs().startOf('month')
dayjs().endOf('day')

Параметр:

  • unit — строка временной гранулярности.

Поддерживаемые значения:

  • year
  • month
  • week
  • day
  • hour
  • minute
  • second

Поведение зависит от календарной модели:

  • startOf обнуляет младшие единицы;
  • endOf устанавливает максимальные значения для интервала.

set(unit, value)

Метод точечного изменения временного компонента:

dayjs().set('hour', 15)

Параметры:

  • unit — строка поля времени;
  • value — числовое значение.

Допустимые единицы:

  • year
  • month
  • date
  • hour
  • minute
  • second
  • millisecond

Особенность: month индексируется с нуля (0–11), что влияет на передачу параметров.

Параметры форматирования

format(template?)

dayjs().format('YYYY-MM-DD')

Параметр:

  • template — строка шаблона формата.

Если параметр отсутствует, используется формат ISO-подобного представления по умолчанию.

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

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

Форматирование строго зависит от строки шаблона, дополнительные параметры отсутствуют.

Параметры локализации

locale(lang?)

dayjs().locale('ru')

Параметр:

  • lang — строка идентификатора локали.

Поведение:

  • при передаче строки устанавливается новая локаль;
  • при отсутствии параметра возвращается текущая локаль экземпляра.

Локаль влияет на:

  • названия месяцев;
  • названия дней недели;
  • форматирование относительного времени.

Параметры проверки и конверсии

isValid()

dayjs('invalid').isValid()

Параметры отсутствуют. Метод опирается на внутренний флаг состояния объекта.

toDate()

dayjs().toDate()

Без параметров. Возвращает стандартный объект Date.

valueOf()

dayjs().valueOf()

Без параметров. Возвращает timestamp в миллисекундах.

Параметры цепочек вызовов

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

dayjs()
  .add(1, 'day')
  .set('hour', 10)
  .format('YYYY-MM-DD HH:mm')

Здесь параметры распределяются по этапам:

  • add(1, 'day') — смещение;
  • set('hour', 10) — модификация поля;
  • format(...) — финальное представление.

Особенности типизации параметров

Строковые параметры

Используются для:

  • форматов ('YYYY-MM-DD');
  • единиц измерения ('month');
  • локалей ('ru').

Строгая проверка отсутствует на уровне API, ошибки проявляются в поведении результата.

Числовые параметры

Применяются в:

  • add, subtract, set, diff.

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

  • допускаются отрицательные значения;
  • дробные значения поддерживаются только в ограниченных случаях (diff с floating).

Булевы параметры

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

  • строгий режим парсинга;
  • дробный режим вычисления разницы.

Булевы флаги всегда располагаются последними в сигнатуре методов.

Объекты как параметры

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

  • конфигурации расширенного парсинга;
  • настройки UTC;
  • параметры timezone.

Общая особенность: объект всегда рассматривается как единый параметр без перегрузки ключей на уровне сигнатуры.

Параметры плагинов и расширений

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

Пример: UTC

dayjs().utcOffset(180)

Параметр:

  • number — смещение в минутах.

Пример: Duration

dayjs.duration(2, 'hours')

Параметры:

  • числовое значение;
  • строка единицы измерения.

Структура аналогична add, но используется для представления длительности.

Итоговая структура параметров

Параметры методов Day.js формируют унифицированную систему, где:

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

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

Оглавление