Signatur
Beschreibung
toString() wandelt ein Temporal.Duration-Objekt in einen String im ISO-8601-Dauerformat um. Der String beginnt mit P (für „Period“). Danach folgen die Datumsanteile (Y, M, W, D) und nach einem T die Zeitanteile (H, M, S). Millisekunden, Mikrosekunden und Nanosekunden stehen als Nachkommastellen der Sekunden. Bei negativen Dauern steht ein - ganz vorne ("-PT2H"). Eine Nulldauer ergibt "PT0S".
Das Format eignet sich zum Speichern, Übertragen (z. B. in JSON oder als URL-Parameter) und Protokollieren. Temporal.Duration.from() liest den String ohne Verlust wieder ein. Für Texte, die Menschen lesen sollen, ist toLocaleString() (über Intl.DurationFormat) besser geeignet.
Die Methode gleicht die Einheiten nicht aus: { minutes: 90 } wird zu "PT90M" und nicht zu "PT1H30M". Wenn du ausgeglichene Einheiten willst, rufst du vorher duration.round({ largestUnit: … }) auf. Über options steuerst du nur, wie genau die Sekunden ausgegeben werden, etwa um Nanosekunden abzuschneiden oder immer eine feste Zahl von Nachkommastellen auszugeben.
Template-Literale (`${duration}`) und String(duration) rufen intern toString() auf. toJSON() liefert dasselbe Ergebnis wie toString() ohne Optionen. Deshalb wird eine Dauer mit JSON.stringify() automatisch als ISO-String gespeichert.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options | object | {} | Optionales Objekt, das die Ausgabe der Sekundenanteile steuert. |
| $options.fractionalSecondDigits | "auto" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | "auto" | Anzahl der Nachkommastellen der Sekunden. "auto" gibt so viele Stellen aus wie nötig und lässt Nullen am Ende weg. Eine Zahl erzwingt genau so viele Stellen, auch mit Nullen am Ende (0 = keine Nachkommastellen). |
| $options.smallestUnit | "second" | "millisecond" | "microsecond" | "nanosecond" | Kleinste Einheit, die ausgegeben wird. Entspricht fractionalSecondDigits 0, 3, 6 oder 9 und hat Vorrang vor fractionalSecondDigits. Größere Einheiten wie "minute" sind nicht erlaubt. |
|
| $options.roundingMode | "trunc" | "floor" | "ceil" | "expand" | "halfExpand" | "halfTrunc" | "halfEven" | "halfFloor" | "halfCeil" | "trunc" | Legt fest, wie beim Kürzen der Nachkommastellen gerundet wird. Standardmäßig wird abgeschnitten ("trunc"), also nicht kaufmännisch gerundet. |
Rückgabewert
"PT1H30M", "-P2D" oder "PT0S".