Signatur
Beschreibung
format() nimmt ein Dauer-Objekt entgegen und gibt es als lokalisierten String zurück, etwa "1 Stunde, 46 Minuten und 40 Sekunden" oder im Digitalformat "1:46:40". Sprache, Stil (long, short, narrow, digital) und die Anzeige einzelner Einheiten legst du beim Erzeugen der Intl.DurationFormat-Instanz fest. Die Methode wendet diese Einstellungen nur noch an.
Gedacht ist die Methode für die Anzeige von Laufzeiten, Restzeiten, Videolängen, Trainingsdauern oder Wartezeiten. Einheitennamen, Listentrenner wie „und“ oder „and“ und die Pluralformen musst du dabei nicht selbst übersetzen.
Wichtig: format() rechnet nichts um. Aus { seconds: 3600 } wird "3,600 sec" und nicht „1 Stunde“. Wenn du einen Gesamtwert in Sekunden oder Millisekunden hast, musst du ihn vorher selbst auf Stunden, Minuten und Sekunden aufteilen.
Wenn du den Text in einzelnen Teilen stylen willst, liefert formatToParts() die Bestandteile als Array.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $duration Pflicht | Object | Temporal.Duration | Ein Objekt mit mindestens einer der Eigenschaften years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds, nanoseconds. Die Werte müssen ganze Zahlen sein und dürfen kein gemischtes Vorzeichen haben. In Umgebungen mit Temporal geht auch ein Temporal.Duration. |
Rückgabewert
Beispiele
Stile im Vergleich
const dauer = { hours: 1, minutes: 46, seconds: 40 };
console.log(new Intl.DurationFormat("de", { style: "long" }).format(dauer));
console.log(new Intl.DurationFormat("en").format(dauer)); // Standard: short
console.log(new Intl.DurationFormat("en", { style: "narrow" }).format(dauer));
console.log(new Intl.DurationFormat("en", { style: "digital" }).format(dauer));Videolänge aus Gesamtsekunden anzeigen
// format() rechnet nicht um, also zuerst selbst aufteilen
const zuDauer = (gesamtSekunden) => ({
hours: Math.floor(gesamtSekunden / 3600),
minutes: Math.floor((gesamtSekunden % 3600) / 60),
seconds: gesamtSekunden % 60,
});
const df = new Intl.DurationFormat("en", { style: "digital" });
console.log(df.format(zuDauer(185)));
console.log(df.format(zuDauer(7384)));Stoppuhr mit Nachkommastellen
const df = new Intl.DurationFormat("en", {
style: "digital",
fractionalDigits: 2,
});
console.log(df.format({ hours: 1, minutes: 2, seconds: 3, milliseconds: 450 }));Ungültige Eingaben abfangen
const df = new Intl.DurationFormat("de");
const sicherFormatieren = (d) => {
try {
return df.format(d);
} catch (err) {
return `${err.name}: ungültige Dauer`;
}
};
console.log(sicherFormatieren({ hours: 1, minutes: -5 })); // gemischte Vorzeichen
console.log(sicherFormatieren({ hours: 1.5 })); // keine ganze Zahl
console.log(sicherFormatieren({})); // keine Einheit angegeben// Wichtig · Fallstricke
- Keine Umrechnung: Werte werden nicht in größere Einheiten übertragen.
{ minutes: 90 }bleibt „90 Minuten“. - Fehler bei ungültigen Eingaben: Gemischte Vorzeichen (z. B.
{ hours: 1, minutes: -5 }) und Nicht-Ganzzahlen führen zu einemRangeError. Ein Objekt ohne eine einzige Einheit führt zu einemTypeError. Strings wie"PT1H"nimmt die Methode nur an, wenn die Umgebung Temporal unterstützt. - Nachkommastellen: Bei
fractionalDigitswird abgeschnitten, nicht gerundet. - Nullwerte: Einheiten mit dem Wert
0werden in den Textstilen standardmäßig weggelassen (display: "auto"). Im Stildigitalwerden Stunden, Minuten und Sekunden immer angezeigt. - Kompatibilität: Die API ist relativ neu (Baseline 2025). Ältere Browser und Node.js unter Version 23 kennen sie nicht. Prüfe das vorher mit
if ("DurationFormat" in Intl)oder nutze ein Polyfill wie@formatjs/intl-durationformat. - Leistung: Erzeuge eine Instanz einmal und verwende sie mehrfach, statt bei jedem Aufruf
new Intl.DurationFormat()anzulegen.