Порядковые числительные

Порядковые числительные в контексте дат используются для отображения чисел с суффиксами, отражающими их позиционное значение: 1st, 2nd, 3rd, 4th и так далее. В форматировании дат они применяются прежде всего к дням месяца, неделям и кварталам, позволяя получать более «человекоориентированное» представление времени.

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

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

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

Подключение расширенного формата

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

import dayjs from 'dayjs'
import advancedFormat from 'dayjs/plugin/advancedFormat'

dayjs.extend(advancedFormat)

После подключения становятся доступны дополнительные токены, включая Do, Qo, Wo, которые отвечают за порядковое представление значений.

Основные токены порядковых числительных

Дата месяца: Do

Наиболее часто используемый формат — Do, который выводит день месяца с порядковым суффиксом.

dayjs('2026-05-01').format('Do MMMM YYYY')
// 1st May 2026
dayjs('2026-05-02').format('Do MMMM YYYY')
// 2nd May 2026
dayjs('2026-05-03').format('Do MMMM YYYY')
// 3rd May 2026

Поведение определяется локалью, что позволяет адаптировать формат под разные языки и правила.

Кварталы: Qo

Токен Qo используется для отображения номера квартала в порядковой форме.

dayjs('2026-05-22').format('Qo [quarter] YYYY')
// 2nd quarter 2026

Кварталы вычисляются на основе месяца:

  • январь–март → 1st
  • апрель–июнь → 2nd
  • июль–сентябрь → 3rd
  • октябрь–декабрь → 4th

Недели года: Wo

Токен Wo применяется для отображения номера недели года в порядковой форме.

dayjs('2026-01-15').format('Wo [week of] YYYY')
// 3rd week of 2026

Расчёт недели зависит от локали и настроек начала недели, что может влиять на итоговое значение.

Локализация порядковых числительных

Day.js использует функцию ordinal внутри локали для формирования суффиксов. Это позволяет задавать правила для разных языков и регионов.

Стандартная английская локаль использует правила:

  • 1 → 1st
  • 2 → 2nd
  • 3 → 3rd
  • остальные → th

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

import dayjs from 'dayjs'

dayjs.locale({
  name: 'custom-en',
  ordinal: function (n) {
    const s = ['th', 'st', 'nd', 'rd']
    const v = n % 100
    return n + (s[(v - 20) % 10] || s[v] || s[0])
  }
})

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

Принцип работы токенов с суффиксом o

Все токены, заканчивающиеся на o, используют внутренний механизм преобразования через функцию локали ordinal. Это означает, что:

  • значение сначала вычисляется как число
  • затем передаётся в ordinal
  • результат подставляется в строку форматирования

Примеры токенов:

  • Do — день месяца
  • Mo — месяц (в некоторых локалях)
  • Qo — квартал
  • Wo — неделя года
  • Yo — годовой порядковый формат (в зависимости от расширений)

Комбинирование порядковых форматов

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

dayjs('2026-07-04').format('Do [day of] MMMM, Qo [quarter]')
// 4th day of July, 3rd quarter
dayjs('2026-12-31').format('Do MMMM YYYY, Wo [week]')
// 31st December 2026, 53rd week

Такие комбинации позволяют формировать сложные текстовые шаблоны дат без дополнительной логики.

Поведение при отсутствии advancedFormat

При отсутствии подключённого плагина advancedFormat токены Do, Qo, Wo не интерпретируются и возвращаются как строковые литералы:

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

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

Особенности вычисления значений

Порядковые значения зависят от двух факторов:

  1. Исходное числовое значение

    • день месяца
    • номер недели
    • номер квартала

  2. Локаль

    • правила суффиксов
    • языковые особенности
    • региональные стандарты

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

Практическая модель использования

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

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

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

dayjs('2026-09-18').format('[Today is the] Do [day of] MMMM')
// Today is the 18th day of September

Взаимодействие с другими плагинами

Порядковые форматы могут использоваться совместно с другими расширениями Day.js:

  • localizedFormat — улучшенное локализованное форматирование
  • utc — работа с UTC временем
  • timezone — поддержка временных зон

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

Обработка крайних значений

Числа, выходящие за стандартные диапазоны (например, при кастомных календарных расчётах), также проходят через функцию ordinal, что позволяет сохранять единообразие:

dayjs().locale('en').format('Wo')
// корректная обработка даже при изменённых настройках недели

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

Оглавление