Intl.DateTimeFormat.prototype.formatToParts()

Метод formatToParts() экземпляров Intl.DateTimeFormat возвращает массив объектов, представляющих каждую часть отформатированной строки, которая была бы возвращена методом format(). Он полезен для построения пользовательских строк из локализованных токенов.

Попробуйте

const date = new Date(2012, 5);
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
const dateTimeFormat = new Intl.DateTimeFormat("en-US", options);

const parts = dateTimeFormat.formatToParts(date);
const partValues = parts.map((p) => p.value);

console.log(partValues);
// Expected output: "["Friday", ", ", "June", " ", "1", ", ", "2012"]"

Синтаксис

formatToParts(date)

Параметры

date Необязательный

Дата для форматирования. Может быть объектом Date или Temporal.PlainDateTime. Дополнительно может быть объектом Temporal.PlainTime, Temporal.PlainDate, Temporal.PlainYearMonth или Temporal.PlainMonthDay, если объект DateTimeFormat был сконфигурирован для вывода хотя бы одной соответствующей части даты.

Примечание: Объект Temporal.ZonedDateTime всегда вызовет TypeError; вместо этого используйте Temporal.ZonedDateTime.prototype.toLocaleString() или преобразуйте его в объект Temporal.PlainDateTime.

Пропуск этого параметра приводит к форматированию текущей даты (возвращаемой Date.now()), что может вызвать некоторое замешательство, поэтому рекомендуется всегда явно передавать дату.

Возвращаемое значение

Массив Array объектов, содержащих отформатированную дату по частям. Каждый объект имеет два свойства, type и value, каждое из которых содержит строку. Конкатенация строк value в указанном порядке даст ту же строку, что и format(). type может быть одним из компонентов даты и времени:

weekday

Например, "M", "Monday" или "Montag".

era

Например, "BC" или "AD".

year

Например, "2012" или "96".

month

Например, "12" или "January".

day

Например, "17".

dayPeriod

Например, "AM", "PM", "in the morning" или "noon".

hour

Например, "3" или "03".

minute

Например, "00".

second

Например, "07" или "42".

fractionalSecond

Например, "0", "00" или "000".

timeZoneName

Например, "UTC", "CET" или "Central European Time".

type также может быть одним из следующих:

literal

Любая строка, которая является частью шаблона форматирования и не зависит от date; например, "/", ", ", "o'clock", "de", " " и т. д.

relatedYear

4-значный год по григорианскому календарю, в случае, если представление календаря было бы yearName вместо года; например, "2019". См. именованные годы для получения более подробной информации.

yearName

Имя, данное году, обычно в календарях без концепции непрерывных лет; например, "geng-zi".

unknown

Зарезервировано для любого токена, который не распознан как один из вышеперечисленных; встречается редко.

Примеры

Использование formatToParts()

Метод format() выводит локализованные, непрозрачные строки, которые нельзя напрямую манипулировать:

const date = Date.UTC(2012, 11, 17, 3, 0, 42);

const formatter = new Intl.DateTimeFormat("en-us", {
  weekday: "long",
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  fractionalSecondDigits: 3,
  hour12: true,
  timeZone: "UTC",
});

formatter.format(date);
// "Monday, 12/17/2012, 3:00:42.000 AM"

Однако во многих пользовательских интерфейсах вы можете захотеть настроить форматирование этой строки или вставить ее между другими текстами. Метод formatToParts() выдает ту же информацию по частям:

formatter.formatToParts(date);

// return value:
[
  { type: "weekday", value: "Monday" },
  { type: "literal", value: ", " },
  { type: "month", value: "12" },
  { type: "literal", value: "/" },
  { type: "day", value: "17" },
  { type: "literal", value: "/" },
  { type: "year", value: "2012" },
  { type: "literal", value: ", " },
  { type: "hour", value: "3" },
  { type: "literal", value: ":" },
  { type: "minute", value: "00" },
  { type: "literal", value: ":" },
  { type: "second", value: "42" },
  { type: "fractionalSecond", value: "000" },
  { type: "literal", value: " " },
  { type: "dayPeriod", value: "AM" },
];

Теперь информация доступна отдельно, и ее можно снова форматировать и объединять настраиваемым образом. Например, используя Array.prototype.map(), стрелочные функции, оператор switch, шаблонные литералы и Array.prototype.join(), для вставки дополнительной разметки для определенных компонентов.

const dateString = formatter
  .formatToParts(date)
  .map(({ type, value }) => {
    switch (type) {
      case "dayPeriod":
        return `<em>${value}</em>`;
      default:
        return value;
    }
  })
  .join("");

console.log(dateString);
// "Monday, 12/17/2012, 3:00:42.000 <em>AM</em>"

Именованные годы

Некоторые календари используют именованные годы; например, китайский и тибетский календари используют 60-летний цикл сексагенария именованных лет. Эти календари не имеют универсального способа однозначно нумеровать каждый год, поэтому годы различаются по отношению к соответствующим годам в григорианском календаре. В этом случае, когда DateTimeFormat настроен на вывод компонента года, вместо year выдается токен relatedYear.

const df = new Intl.DateTimeFormat("zh-u-ca-chinese");
df.formatToParts(Date.UTC(2012, 11, 17, 3, 0, 42));

// return value:
[
  { type: "relatedYear", value: "2012" },
  { type: "literal", value: "年" },
  { type: "month", value: "十一月" },
  { type: "day", value: "4" },
];

Иногда комбинация опций компонента даты и времени соответствует формату, который также включает yearName. Нет отдельной опции, которая контролирует, отображается ли yearName или нет. Например, приведенные ниже опции устанавливают month в "long" и приводят к выводу токена yearName, несмотря на то, что year остается "numeric":

const opts = { year: "numeric", month: "long", day: "numeric" };
const df = new Intl.DateTimeFormat("zh-u-ca-chinese", opts);
df.formatToParts(Date.UTC(2012, 11, 17, 3, 0, 42));

// return value:
[
  { type: "relatedYear", value: "2012" },
  { type: "yearName", value: "壬辰" },
  { type: "literal", value: "年" },
  { type: "month", value: "十一月" },
  { type: "day", value: "4" },
];

Поскольку format() просто объединяет все строки value вместе, в этом случае вы увидите год по григорианскому календарю и название года вместе в выводе.

Спецификации

Совместимость с браузерами

См. также

• Intl.DateTimeFormat
• Intl.DateTimeFormat.prototype.format()