Метод toHuman

В библиотеке Luxon работа с форматированием дат и времени строится вокруг DateTime, Duration и Interval. Среди вспомогательных способов преобразования данных в читаемую форму выделяется метод toHuman, предназначенный для генерации человеко-читаемого представления временных значений без необходимости вручную подбирать формат.

Назначение и поведение

toHuman используется для преобразования объектов даты, времени или длительности в строку, ориентированную на восприятие человеком. В отличие от строгих форматтеров (toISO, toFormat), он:

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

Основная идея метода — выдавать «естественный» текст вместо строго заданного шаблона.

Общая сигнатура

В зависимости от типа объекта поведение метода может отличаться, но концептуально используется единый подход:

value.toHuman(options?)

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

Применение к Duration

Наиболее характерный сценарий — работа с длительностями.

import { Duration } from "luxon";

const d = Duration.fromObject({
  hours: 2,
  minutes: 45,
  seconds: 10
});

console.log(d.toHuman());

Результат может быть представлен в виде:

2 hours, 45 minutes, 10 seconds

Метод автоматически:

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

Локализация вывода

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

const d = Duration.fromObject({
  hours: 1,
  minutes: 30
});

console.log(d.setLocale("en").toHuman());
console.log(d.setLocale("fr").toHuman());

Пример возможного результата:

1 hour, 30 minutes
1 heure, 30 minutes

Локализация затрагивает:

  • формы множественного числа;
  • разделители между компонентами;
  • порядок слов (в зависимости от языка).

Управление единицами

Метод позволяет контролировать набор отображаемых единиц.

d.toHuman({ unitDisplay: "short" });

Возможные режимы:

  • long — полные слова (hours, minutes);
  • short — сокращения (hr, min);
  • narrow — максимально компактная форма.

Пример:

2 hr, 45 min

Ограничение точности

При необходимости можно ограничить детализацию:

const d = Duration.fromObject({
  hours: 5,
  minutes: 20,
  seconds: 45
});

d.toHuman({ maximumUnitCount: 2 });

Результат:

5 hours, 20 minutes

Оставшиеся единицы отбрасываются, начиная с наименьших.

Поведение при нулевых значениях

toHuman автоматически исключает нулевые компоненты:

Duration.fromObject({
  hours: 3,
  minutes: 0,
  seconds: 0
}).toHuman();

Результат:

3 hours

При этом при полностью нулевой длительности поведение зависит от конфигурации и может возвращать:

0 seconds

или локализованный эквивалент.

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

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

import { Interval } from "luxon";

const i = Interval.fromDateTimes(
  DateTime.local(2026, 1, 1),
  DateTime.local(2026, 1, 2, 3)
);

console.log(i.toDuration().toHuman());

Вывод:

1 day, 3 hours

Интервал сначала преобразуется в Duration, после чего применяется toHuman.

Отличие от toFormat и toLocaleString

toHuman занимает отдельную нишу между строгим и автоматическим форматированием.

Метод Назначение Особенность
toFormat кастомный формат полный контроль строки
toLocaleString стандарт локали системные правила
toHuman человеко-ориентированный вывод упрощённое представление

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

d.toFormat("h 'hours' m 'minutes'");
d.toLocaleString();
d.toHuman();
  • toFormat требует ручного шаблона;
  • toLocaleString зависит от стандартов Intl;
  • toHuman автоматически подбирает оптимальную форму.

Работа с дробными значениями

При наличии дробных единиц происходит нормализация:

Duration.fromObject({
  hours: 1.5
}).toHuman();

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

1 hour, 30 minutes

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

Кастомизация вывода

Поддерживаются дополнительные параметры:

d.toHuman({
  listStyle: "long",
  maxDecimalPoints: 1
});

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

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

Ограничения метода

Несмотря на удобство, toHuman имеет особенности:

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

Сценарии использования

Типичные области применения:

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

Взаимодействие с другими методами Luxon

toHuman часто используется после вычислений:

const start = DateTime.local();
const end = start.plus({ hours: 4, minutes: 30 });

console.log(end.diff(start).toHuman());

Здесь:

  • diff создаёт Duration;
  • toHuman формирует читаемое представление.

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

Оглавление