Intl.DurationFormat.prototype.formatToParts()

Baseline 2025

Newly available

Since March 2025, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Die Methode formatToParts() von Intl.DurationFormat-Instanzen gibt ein Array von Objekten zurück, die jeden Teil des formatierten Strings darstellen würden, der von format() zurückgegeben wird. Diese Methode ist nützlich, um benutzerdefinierte Strings aus den lokalspezifischen Tokens zu erstellen.

Syntax

formatToParts(duration)

Parameter

duration Optional: Das zu formatierende Dauerobjekt. Es sollte einige oder alle der folgenden Eigenschaften enthalten: years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds. Der Wert jeder Eigenschaft sollte eine ganze Zahl sein, und ihre Vorzeichen sollten konsistent sein. Dies kann ein Temporal.Duration-Objekt sein; siehe die Temporal.Duration-Dokumentation für weitere Informationen über diese Eigenschaften.

Rückgabewert

Ein Array von Objekten, das die formatierte Dauer in Teilen enthält. Jedes Objekt hat zwei oder drei Eigenschaften: type, value und optional unit, die jeweils einen String enthalten. Die String-Verkettung von value, in der angegebenen Reihenfolge, ergibt denselben String wie format(). Die Teile können als direkt von einem Aufruf von Intl.NumberFormat.prototype.formatToParts() mit dem numerischen Wert und den jeweiligen Einheiten erhalten betrachtet werden. Alle Tokens, die vom NumberFormat erzeugt werden, haben eine zusätzliche unit-Eigenschaft, die die Singularform der Eingabeeinheit darstellt; dies dient der programmatischen Nutzung und ist nicht lokalisiert. Die lokalisierte Einheit wird als separates unit-Token als Teil des NumberFormat-Ergebnisses ausgegeben. Die Teile von jeder Dauer-Einheit werden in gleicher Weise wie ein Aufruf von Intl.ListFormat.prototype.formatToParts() mit { type: "unit" } zusammengefügt, sodass zusätzliche literale Tokens eingefügt werden.

Beispiele

Die formatToParts-Methode ermöglicht das lokalisierungsbewusste Formatieren von Strings, die von DurationFormat-Formatierern erzeugt werden, indem Sie den String in Teile zerlegt:

const duration = {
  hours: 7,
  minutes: 8,
  seconds: 9,
  milliseconds: 123,
  microseconds: 456,
  nanoseconds: 789,
};

new Intl.DurationFormat("en", { style: "long" }).formatToParts(duration);

// Returned value:
[
  { type: "integer", value: "7", unit: "hour" },
  { type: "literal", value: " ", unit: "hour" },
  { type: "unit", value: "hours", unit: "hour" },
  { type: "literal", value: ", " },
  { type: "integer", value: "8", unit: "minute" },
  { type: "literal", value: " ", unit: "minute" },
  { type: "unit", value: "minutes", unit: "minute" },
  { type: "literal", value: ", " },
  { type: "integer", value: "9", unit: "second" },
  { type: "literal", value: " ", unit: "second" },
  { type: "unit", value: "seconds", unit: "second" },
  { type: "literal", value: ", " },
  { type: "integer", value: "123", unit: "millisecond" },
  { type: "literal", value: " ", unit: "millisecond" },
  { type: "unit", value: "milliseconds", unit: "millisecond" },
  { type: "literal", value: ", " },
  { type: "integer", value: "456", unit: "microsecond" },
  { type: "literal", value: " ", unit: "microsecond" },
  { type: "unit", value: "microseconds", unit: "microsecond" },
  { type: "literal", value: ", " },
  { type: "integer", value: "789", unit: "nanosecond" },
  { type: "literal", value: " ", unit: "nanosecond" },
  { type: "unit", value: "nanoseconds", unit: "nanosecond" },
];

Spezifikationen

Specification
Intl.DurationFormat # sec-Intl.DurationFormat.prototype.formatToParts