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

Библиотека Js-joda предоставляет API для работы с датой и временем, вдохновлённый пакетом java.time из Java. Форматирование времени строится вокруг класса DateTimeFormatter, который отвечает за преобразование объектов даты и времени в строку и обратно.

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

const {
    LocalDate,
    LocalTime,
    LocalDateTime,
    ZonedDateTime,
    OffsetDateTime,
    DateTimeFormatter
} = require('@js-joda/core');

Базовое форматирование выполняется методом format():

const date = LocalDate.of(2025, 5, 18);

const result = date.format(DateTimeFormatter.ISO_LOCAL_DATE);

console.log(result);

Результат:

2025-05-18

Готовые форматтеры

В библиотеке присутствует набор встроенных форматтеров стандарта ISO.

ISO_LOCAL_DATE

Форматирует только дату:

const date = LocalDate.of(2025, 12, 31);

console.log(
    date.format(DateTimeFormatter.ISO_LOCAL_DATE)
);

Результат:

2025-12-31

ISO_LOCAL_TIME

Форматирует только время:

const time = LocalTime.of(14, 45, 12);

console.log(
    time.format(DateTimeFormatter.ISO_LOCAL_TIME)
);

Результат:

14:45:12

ISO_LOCAL_DATE_TIME

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

const dateTime = LocalDateTime.of(2025, 5, 18, 14, 30);

console.log(
    dateTime.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME)
);

Результат:

2025-05-18T14:30:00

ISO_OFFSET_DATE_TIME

Форматирование даты со смещением UTC:

const {
    ZoneOffset,
    OffsetDateTime
} = require('@js-joda/core');

const dateTime = OffsetDateTime.of(
    2025,
    5,
    18,
    14,
    30,
    0,
    0,
    ZoneOffset.ofHours(3)
);

console.log(
    dateTime.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME)
);

Результат:

2025-05-18T14:30:00+03:00

Создание собственного шаблона

Для задания пользовательского формата применяется метод DateTimeFormatter.ofPattern().

const formatter = DateTimeFormatter.ofPattern(
    'dd.MM.yyyy HH:mm:ss'
);

const dateTime = LocalDateTime.of(
    2025,
    5,
    18,
    9,
    15,
    40
);

console.log(dateTime.format(formatter));

Результат:

18.05.2025 09:15:40

Основные символы шаблонов

Год

Шаблон Описание Пример
y год 2025
yy две цифры года 25
yyyy полный год 2025

Пример:

const formatter = DateTimeFormatter.ofPattern('dd.MM.yy');

Месяц

Шаблон Описание Пример
M номер месяца 5
MM месяц с нулём 05
MMM краткое название May
MMMM полное название May

Пример:

const formatter = DateTimeFormatter.ofPattern('dd MMMM yyyy');

День

Шаблон Описание Пример
d день месяца 3
dd день с нулём 03

Часы

Шаблон Описание Пример
H часы 0–23 7
HH часы с нулём 07

Минуты и секунды

Шаблон Описание
m минуты
mm минуты с нулём
s секунды
ss секунды с нулём

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

Вывод часов и минут

const time = LocalTime.of(8, 5);

const formatter = DateTimeFormatter.ofPattern('HH:mm');

console.log(time.format(formatter));

Результат:

08:05

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

const time = LocalTime.of(21, 17, 9);

const formatter = DateTimeFormatter.ofPattern(
    'HH:mm:ss'
);

console.log(time.format(formatter));

Результат:

21:17:09

12-часовой формат

Для отображения времени в 12-часовом формате используются символы hh и a.

const formatter = DateTimeFormatter.ofPattern(
    'hh:mm a'
);

const time = LocalTime.of(18, 45);

console.log(time.format(formatter));

Результат:

06:45 PM

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

const dateTime = LocalDateTime.of(
    2025,
    11,
    3,
    16,
    20,
    10
);

const formatter = DateTimeFormatter.ofPattern(
    'dd.MM.yyyy HH:mm:ss'
);

console.log(dateTime.format(formatter));

Результат:

03.11.2025 16:20:10

Использование текстовых значений

День недели

const formatter = DateTimeFormatter.ofPattern(
    'EEEE'
);

const date = LocalDate.of(2025, 5, 18);

console.log(date.format(formatter));

Результат:

Sunday

Краткое название дня

const formatter = DateTimeFormatter.ofPattern(
    'EEE'
);

Пример результата:

Sun

Полное название месяца

const formatter = DateTimeFormatter.ofPattern(
    'MMMM'
);

Результат:

May

Литералы в шаблоне

Любой текст можно встроить в формат при помощи одинарных кавычек.

const formatter = DateTimeFormatter.ofPattern(
    "dd.MM.yyyy 'время:' HH:mm"
);

const dateTime = LocalDateTime.of(
    2025,
    5,
    18,
    10,
    30
);

console.log(dateTime.format(formatter));

Результат:

18.05.2025 время: 10:30

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

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

const dateTime = LocalDateTime.of(
    2025,
    5,
    18,
    10,
    30,
    15,
    123000000
);

const formatter = DateTimeFormatter.ofPattern(
    'HH:mm:ss.SSS'
);

console.log(dateTime.format(formatter));

Результат:

10:30:15.123

Форматирование временной зоны

Смещение UTC

const formatter = DateTimeFormatter.ofPattern(
    'yyyy-MM-dd HH:mm XXX'
);

Пример результата:

2025-05-18 14:30 +03:00

Название зоны

const formatter = DateTimeFormatter.ofPattern(
    'yyyy-MM-dd HH:mm z'
);

Локализация

Для поддержки локалей требуется пакет:

npm install @js-joda/locale

Подключение локали:

require('@js-joda/locale_ru');

Использование:

const formatter = DateTimeFormatter
    .ofPattern('d MMMM yyyy');

const date = LocalDate.of(2025, 5, 18);

console.log(date.format(formatter));

После подключения русской локали:

18 мая 2025

Парсинг строк

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

const formatter = DateTimeFormatter.ofPattern(
    'dd.MM.yyyy'
);

const date = LocalDate.parse(
    '18.05.2025',
    formatter
);

console.log(date);

Ошибки несовпадения форматов

Если строка не соответствует шаблону, возникает исключение.

const formatter = DateTimeFormatter.ofPattern(
    'dd.MM.yyyy'
);

LocalDate.parse(
    '2025-05-18',
    formatter
);

Ошибка:

DateTimeParseException

Комбинирование различных форматов

Формат для логов

const formatter = DateTimeFormatter.ofPattern(
    'yyyy-MM-dd HH:mm:ss.SSS'
);

Пример:

2025-05-18 14:33:22.381

Формат для интерфейсов

const formatter = DateTimeFormatter.ofPattern(
    'dd MMM yyyy'
);

Пример:

18 May 2025

Формат для файлов

const formatter = DateTimeFormatter.ofPattern(
    'yyyyMMdd_HHmmss'
);

Пример:

20250518_143322

Неизменяемость форматтеров

Объекты DateTimeFormatter являются immutable-структурами. После создания форматтер нельзя изменить.

const formatter = DateTimeFormatter.ofPattern(
    'dd.MM.yyyy'
);

Это позволяет:

  • безопасно переиспользовать форматтер;
  • хранить его как константу;
  • использовать в многопоточном окружении;
  • избегать побочных эффектов.

Повторное использование форматтера

Создание форматтера — относительно дорогая операция. Часто используемые экземпляры рекомендуется выносить в константы.

const DATE_FORMATTER =
    DateTimeFormatter.ofPattern(
        'dd.MM.yyyy'
    );

function formatDate(date) {
    return date.format(DATE_FORMATTER);
}

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

Символы шаблона интерпретируются как управляющие. Для вывода специальных символов применяется экранирование.

const formatter = DateTimeFormatter.ofPattern(
    "yyyy-MM-dd'T'HH:mm:ss"
);

Результат:

2025-05-18T10:30:00

Частые ошибки

Использование mm вместо MM

MM — месяц, mm — минуты.

Ошибка:

DateTimeFormatter.ofPattern(
    'dd.mm.yyyy'
);

Правильно:

DateTimeFormatter.ofPattern(
    'dd.MM.yyyy'
);

Использование hh вместо HH

Шаблон Формат
HH 24 часа
hh 12 часов

Несовпадение шаблона и строки

const formatter = DateTimeFormatter.ofPattern(
    'yyyy-MM-dd'
);

LocalDate.parse(
    '18.05.2025',
    formatter
);

Такой код завершится ошибкой разбора.

Практический пример форматирования

const {
    LocalDateTime,
    DateTimeFormatter
} = require('@js-joda/core');

const formatter = DateTimeFormatter.ofPattern(
    'dd.MM.yyyy HH:mm:ss'
);

const now = LocalDateTime.now();

const result = now.format(formatter);

console.log(result);

Возможный результат:

18.05.2025 21:44:11
Оглавление