Signatur
Beschreibung
Die Methode toString() wandelt eine Temporal.ZonedDateTime in einen maschinenlesbaren String im Format RFC 9557 um. RFC 9557 erweitert ISO 8601 bzw. RFC 3339 um Annotationen in eckigen Klammern. Das typische Ergebnis sieht so aus: 2021-08-01T12:34:56-04:00[America/New_York]. Dazu gehören das lokale Datum, die lokale Uhrzeit, der UTC-Offset, der Zeitzonenbezeichner und bei Bedarf der Kalender, z. B. [u-ca=hebrew].
Der String ist verlustfrei: Mit Temporal.ZonedDateTime.from() lässt sich daraus wieder exakt dasselbe Objekt erzeugen. Deshalb eignet er sich gut zum Speichern in Datenbanken, zum Übertragen per JSON oder zum Protokollieren. Die Methode toJSON() liefert dasselbe Ergebnis wie toString() ohne Optionen.
Über das optionale options-Objekt steuerst du die Ausgabe genau. Du kannst die Genauigkeit der Sekunden festlegen (fractionalSecondDigits, smallestUnit), die Rundung wählen (roundingMode) und einzelne Bestandteile ein- oder ausblenden, nämlich Offset, Zeitzone und Kalender. Für eine Anzeige für Menschen nimmst du stattdessen toLocaleString().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options | object | {} | Optionales Objekt mit den folgenden Eigenschaften. |
| $options.calendarName | "auto" | "always" | "never" | "critical" | "auto" | Steuert die Kalender-Annotation [u-ca=…]. Bei "auto" erscheint sie nur, wenn der Kalender nicht iso8601 ist. "always" gibt sie immer aus, "never" nie. "critical" gibt sie immer aus und mit Ausrufezeichen ([!u-ca=…]). |
| $options.fractionalSecondDigits | "auto" | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | "auto" | Anzahl der Nachkommastellen der Sekunden. Bei "auto" werden Nullen am Ende weggelassen, bei einer Zahl wird die Ausgabe mit Nullen aufgefüllt oder gerundet. |
| $options.smallestUnit | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond" | Kleinste Einheit, die ausgegeben wird. Hat Vorrang vor fractionalSecondDigits. "minute" lässt die Sekunden ganz weg. |
|
| $options.roundingMode | "trunc" | "floor" | "ceil" | "expand" | "halfExpand" | "halfTrunc" | "halfEven" | "halfFloor" | "halfCeil" | "trunc" | Legt fest, wie beim Kürzen der Nachkommastellen gerundet wird. Standard ist Abschneiden. |
| $options.offset | "auto" | "never" | "auto" | Bei "never" wird der UTC-Offset (z. B. -04:00) weggelassen. |
| $options.timeZoneName | "auto" | "never" | "critical" | "auto" | Steuert die Zeitzonen-Annotation [Europe/Berlin]. "never" lässt sie weg, "critical" setzt ein Ausrufezeichen davor ([!Europe/Berlin]). |
Rückgabewert
"2021-08-01T12:34:56-04:00[America/New_York]".Beispiele
Standardausgabe und Rückumwandlung
const zdt = Temporal.ZonedDateTime.from("2021-08-01T12:34:56[America/New_York]");
const str = zdt.toString();
console.log(str);
// Verlustfreie Rückumwandlung
const copy = Temporal.ZonedDateTime.from(str);
console.log(copy.equals(zdt));Genauigkeit und Rundung steuern
const zdt = Temporal.ZonedDateTime.from("2024-03-15T09:30:45.6789[Europe/Berlin]");
console.log(zdt.toString({ smallestUnit: "minute" }));
console.log(zdt.toString({ fractionalSecondDigits: 2 }));
console.log(zdt.toString({ smallestUnit: "second", roundingMode: "halfExpand" }));Offset, Zeitzone und Kalender ein- und ausblenden
const zdt = Temporal.ZonedDateTime.from("2021-08-01T12:34:56[America/New_York]");
// RFC-3339-kompatibel, z. B. für Systeme ohne Annotationen
console.log(zdt.toString({ timeZoneName: "never" }));
console.log(zdt.toString({ offset: "never" }));
console.log(zdt.toString({ calendarName: "always" }));
console.log(zdt.toString({ timeZoneName: "critical", calendarName: "critical" }));Termin als JSON speichern und wieder laden
const termin = {
titel: "Team-Meeting",
start: Temporal.ZonedDateTime.from("2025-06-02T10:00[Europe/Berlin]")
};
// JSON.stringify ruft toJSON() auf; das Ergebnis entspricht toString()
const json = JSON.stringify(termin);
console.log(json);
const geladen = JSON.parse(json, (key, value) =>
key === "start" ? Temporal.ZonedDateTime.from(value) : value
);
console.log(geladen.start.hour);