Дополнительные токены форматирования

Система форматирования Day.js основана на наборе токенов, которые интерпретируются при вызове метода format(). Базовый набор охватывает стандартные компоненты даты и времени, однако экосистема плагинов расширяет его, добавляя более сложные и специализированные форматы. Эти токены становятся доступны после подключения соответствующих модулей и позволяют строить строки представления дат, приближенные к требованиям бизнес-логики, локализации и календарных систем.

Кварталы и расширенная календарная структура

Для работы с кварталами используется плагин quarterOfYear, который добавляет токены, отражающие принадлежность даты к кварталу.

  • Q — номер квартала без форматирования (1–4)
  • Qo — порядковый номер квартала (1st, 2nd и т. д., при наличии локализации)

Пример использования:

import dayjs from 'dayjs'
import quarterOfYear from 'dayjs/plugin/quarterOfYear'

dayjs.extend(quarterOfYear)

dayjs().format('Q')   // "2"
dayjs().format('Qo')  // "2nd"

Квартальная логика особенно полезна в финансовых отчётах и аналитике, где календарь делится не на месяцы, а на отчётные периоды.

Неделя года и ISO-структуры

Работа с неделями требует подключения weekOfYear и, при необходимости, isoWeek.

Появляются следующие токены:

  • w — номер недели в году (1–53)
  • ww — номер недели с ведущим нулём
  • wo — порядковая запись недели (1st, 2nd и т. д.)
  • W — ISO-неделя
  • WW — ISO-неделя с ведущим нулём

Пример:

import weekOfYear from 'dayjs/plugin/weekOfYear'
import isoWeek from 'dayjs/plugin/isoWeek'

dayjs.extend(weekOfYear)
dayjs.extend(isoWeek)

dayjs().format('w')   // "34"
dayjs().format('WW')  // "34"

ISO-нумерация недель отличается от локальной: первая неделя года определяется как неделя, содержащая первый четверг января, что критично для международных систем отчётности.

Расширенные годовые токены

Помимо стандартного YYYY, используются токены, учитывающие недельную структуру года:

  • gg — год недели (двузначный)
  • gggg — полный год недели
  • GG — ISO-год недели (двузначный)
  • GGGG — полный ISO-год недели

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

Пример:

import isoWeek from 'dayjs/plugin/isoWeek'
dayjs.extend(isoWeek)

dayjs().format('GGGG') // например "2026"

Порядковые числа и локализация

Токен Do активируется через плагин advancedFormat и добавляет порядковое представление дня месяца:

  • D — день месяца (1–31)
  • Do — день месяца с суффиксом (1st, 2nd, 3rd)
import advancedFormat from 'dayjs/plugin/advancedFormat'

dayjs.extend(advancedFormat)

dayjs('2026-05-01').format('Do MMMM') // "1st May"

Этот формат тесно связан с локализацией, так как суффиксы зависят от языка.

Расширенное форматирование через advancedFormat

Плагин advancedFormat добавляет набор токенов, которые делают форматирование более выразительным и приближенным к Moment.js.

Основные расширения:

  • Qo — порядковый квартал
  • k — час от 1 до 24
  • kk — час с ведущим нулём (01–24)
  • X — Unix timestamp в секундах
  • x — Unix timestamp в миллисекундах

Пример:

dayjs().format('X') // 1716370000
dayjs().format('x') // 1716370000123

Эти значения используются в API, логировании и системах синхронизации времени.

Локализованные форматы

Плагин localizedFormat добавляет предопределённые шаблоны, которые зависят от языка окружения.

Токены:

  • L — локализованная дата (например, 22.05.2026)
  • LL — полная дата (22 мая 2026 г.)
  • LLL — дата и время
  • LLLL — расширенная форма с днём недели
  • LT — время (HH:mm)
  • LTS — время с секундами
import localizedFormat from 'dayjs/plugin/localizedFormat'

dayjs.extend(localizedFormat)

dayjs().format('LL')   // "22 мая 2026 г."
dayjs().format('LLLL') // "пятница, 22 мая 2026 г., 14:30"

Эти форматы стандартизируют вывод без необходимости вручную комбинировать токены.

Экранирование символов в форматах

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

  • [text] — выводит текст без интерпретации как токены

Пример:

dayjs().format('DD [день месяца]')

Результат:

22 день месяца

Скобки позволяют безопасно комбинировать статический текст и динамические значения без конфликтов с системой токенов.

Токены локали и форматы дня недели

Дополнительные токены, связанные с локализацией и неделей:

  • E — день недели (ISO, 1–7)
  • e — локализованный день недели (0–6 или 1–7 в зависимости от локали)
  • dddd — полное название дня недели
  • ddd — сокращённое название дня недели
dayjs().format('dddd') // "пятница"
dayjs().format('E')    // 5

Эти токены активно используются в интерфейсах календарей и планировщиков.

Комбинирование расширенных токенов

Сложные форматы строятся путём сочетания нескольких расширений одновременно. Например, дата с кварталом, неделей года и локализованным временем:

dayjs()
  .format('[Q:] Q [Week:] w [Time:] LT')

Результат:

Q: 2 Week: 34 Time: 14:30

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

Особенности совместимости и поведения токенов

Расширенные токены не входят в базовый пакет Day.js и активируются только через плагины. Это влияет на поведение форматирования:

  • отсутствие плагина приводит к выводу токена как строки
  • разные плагины могут пересекаться по функциональности
  • ISO-форматы строго отделены от локальных реализаций

Система построена таким образом, чтобы минимизировать размер библиотеки и сохранять модульность, оставляя расширения на усмотрение проекта.

Оглавление