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

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

Метод format() работает на основе разбиения даты на логические компоненты: год, месяц, день, часы, минуты, секунды и дополнительные элементы календаря. Каждый компонент задаётся отдельным токеном.

import dayjs from 'dayjs';

const date = dayjs('2026-05-22T14:35:10');

date.format('YYYY-MM-DD HH:mm:ss');
// 2026-05-22 14:35:10

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

date.format('YYYY год, MM месяц, DD число');
// 2026 год, 05 месяц, 22 число

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

Система токенов Day.js заимствована из Moment.js и использует строгие обозначения.

Год

  • YYYY — полный год (2026)
  • YY — последние две цифры года (26)
dayjs().format('YYYY'); // 2026
dayjs().format('YY');   // 26

Месяц

  • MM — месяц с ведущим нулём (01–12)
  • M — месяц без ведущего нуля (1–12)
  • MMM — сокращённое название месяца (Jan, Feb)
  • MMMM — полное название месяца (January, February)
dayjs('2026-01-01').format('MM');   // 01
dayjs('2026-01-01').format('MMM');  // Jan
dayjs('2026-01-01').format('MMMM'); // January

День

  • DD — день месяца с ведущим нулём
  • D — день месяца без ведущего нуля
dayjs('2026-05-02').format('DD'); // 02
dayjs('2026-05-02').format('D');  // 2

День недели

  • d — номер дня недели (0–6)
  • dd — сокращённое название (Su, Mo)
  • ddd — сокращённое название с локалью (Sun, Mon)
  • dddd — полное название дня недели (Sunday, Monday)
dayjs().format('dddd'); // Friday

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

Часы, минуты и секунды представлены отдельными токенами.

  • HH — 24-часовой формат с ведущим нулём
  • H — 24-часовой формат без нуля
  • hh — 12-часовой формат с нулём
  • h — 12-часовой формат без нуля
  • mm — минуты
  • m — минуты без ведущего нуля
  • ss — секунды
  • s — секунды без ведущего нуля
  • SSS — миллисекунды
const t = dayjs('2026-05-22T08:05:09.123');

t.format('HH:mm:ss');
// 08:05:09

t.format('hh:mm:ss A');
// 08:05:09 AM

Форматирование периода суток

Для обозначения AM/PM используется токен A или a:

  • A — AM / PM в верхнем регистре
  • a — am / pm в нижнем регистре
dayjs('2026-05-22T14:00:00').format('hh:mm A');
// 02:00 PM

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

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

dayjs().format('[Сегодня:] YYYY-MM-DD');
// Сегодня: 2026-05-22

Все символы внутри [] выводятся без интерпретации.

Локализация форматирования

Day.js поддерживает локализацию через плагины и подключение языковых пакетов. После подключения локали форматирование названий месяцев и дней недели становится зависимым от выбранного языка.

import 'dayjs/locale/ru';
dayjs.locale('ru');

dayjs().format('D MMMM YYYY');
// 22 май 2026

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

  • названия месяцев
  • названия дней недели
  • форматы относительного времени (при использовании дополнительных плагинов)

Плагин advancedFormat

Базовый набор токенов покрывает основные сценарии, однако расширенные форматы подключаются через advancedFormat.

Дополнительные токены:

  • Do — день месяца с порядковым суффиксом (1st, 2nd, 3rd)
  • Qo — квартал с суффиксом
  • wo — номер недели в году
import advancedFormat from 'dayjs/plugin/advancedFormat';
dayjs.extend(advancedFormat);

dayjs('2026-05-22').format('Do MMMM YYYY');
// 22nd May 2026

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

Работа с неделями требует внимательного использования токенов:

  • w — неделя года
  • ww — неделя с ведущим нулём
  • W — ISO неделя
  • WW — ISO неделя с ведущим нулём
dayjs('2026-01-01').format('w');
// номер недели года

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

Работа с Unix-временем и форматированием

Day.js позволяет форматировать временные метки Unix (миллисекунды или секунды) через обычную конвертацию:

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

Также поддерживается создание объекта из миллисекунд:

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

Микс форматов и составные шаблоны

Форматирование часто используется для генерации человекочитаемых строк с несколькими уровнями информации:

dayjs().format('dddd, DD MMMM YYYY [в] HH:mm');
// Friday, 22 May 2026 в 14:35

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

Часовые пояса и форматирование

Базовая библиотека Day.js не выполняет полноценное управление часовыми поясами без плагинов. Однако при подключении utc и timezone поведение форматирования меняется.

import utc from 'dayjs/plugin/utc';
import timezone from 'dayjs/plugin/timezone';

dayjs.extend(utc);
dayjs.extend(timezone);

dayjs().tz('Europe/Moscow').format('YYYY-MM-DD HH:mm');

Форматирование остаётся тем же, но входные данные интерпретируются в контексте указанной зоны.

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

Система токенов чувствительна к регистру. Даже небольшое изменение символа приводит к другому результату или отсутствию интерпретации.

Примеры различий:

  • MM — месяц
  • mm — минуты
dayjs().format('MM:mm');
// 05:35 (май и минуты)

Форматирование в цепочках методов

Day.js поддерживает цепочки преобразований перед форматированием:

dayjs()
  .add(2, 'day')
  .subtract(3, 'hour')
  .format('YYYY-MM-DD HH:mm');

Форматирование всегда выполняется в конце цепочки и отражает итоговое состояние объекта.

Поведение при некорректных данных

При передаче некорректной даты форматирование возвращает строку Invalid Date.

dayjs('invalid').format('YYYY-MM-DD');
// Invalid Date

Это поведение важно учитывать при работе с пользовательским вводом и внешними API.

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

Система токенов позволяет создавать сложные шаблоны отображения времени:

dayjs().format('[Дата:] YYYY/MM/DD [| Время:] HH:mm:ss');
// Дата: 2026/05/22 | Время: 14:35:10

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

Форматирование для логирования

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

dayjs().format('YYYY-MM-DDTHH:mm:ssZ');

Такой формат приближен к ISO-8601 и удобен для хранения и анализа событийных данных.

Стабильность форматов

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

Оглавление