Signatur
Beschreibung
toString() wandelt ein Temporal.Instant – also einen exakten Zeitpunkt auf der Zeitachse mit Nanosekunden-Genauigkeit – in einen maschinenlesbaren String um. Ohne Optionen sieht das Ergebnis z. B. so aus: 2024-03-15T12:30:45.123456789Z. Das Z steht für UTC.
Mit der Option timeZone wird dieselbe Uhrzeit als Ortszeit der angegebenen Zeitzone ausgegeben, mit numerischem Offset (z. B. +01:00). Der Name der Zeitzone in eckigen Klammern (z. B. [Europe/Berlin]) wird dabei nicht angehängt. Wer diese Angabe braucht, wandelt den Zeitpunkt mit toZonedDateTimeISO() in ein Temporal.ZonedDateTime um.
Mit smallestUnit, fractionalSecondDigits und roundingMode legst du fest, wie genau der String ist. Das ist nützlich für Logs, Datenbankspalten oder APIs, die z. B. nur Millisekunden oder ganze Sekunden annehmen. Der erzeugte String lässt sich mit Temporal.Instant.from() ohne Verlust wieder einlesen, solange nicht gerundet wurde.
Für Anzeigen, die Menschen lesen, ist toLocaleString() besser geeignet. toString() ist für den Austausch zwischen Programmen und für die Speicherung gedacht.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $options | object | {} | Optionales Objekt mit den folgenden Eigenschaften. |
| $options.timeZone | string | Temporal.ZonedDateTime | "UTC" (Ausgabe mit <code>Z</code>) | IANA-Zeitzone (z. B. "Europe/Berlin") oder fester Offset (z. B. "+05:30"). Die Uhrzeit wird in diese Zone umgerechnet und mit Offset statt Z ausgegeben. |
| $options.fractionalSecondDigits | number | "auto" | "auto" | Anzahl der Nachkommastellen der Sekunden (0–9). Bei "auto" werden Nullen am Ende weggelassen. Wird ignoriert, wenn smallestUnit gesetzt ist. |
| $options.smallestUnit | "minute" | "second" | "millisecond" | "microsecond" | "nanosecond" | Kleinste Einheit im Ergebnis. Hat Vorrang vor fractionalSecondDigits. Bei "minute" fehlen die Sekunden ganz. |
|
| $options.roundingMode | "trunc" | "floor" | "ceil" | "expand" | "halfExpand" | "halfTrunc" | "halfEven" | "halfFloor" | "halfCeil" | "trunc" | Legt fest, wie überzählige Stellen behandelt werden. Standardmäßig werden sie einfach abgeschnitten. |
Rückgabewert
"2024-03-15T12:30:45.123Z" oder mit Offset "2024-03-15T13:30:45.123+01:00".Beispiele
Standardausgabe in UTC
const instant = Temporal.Instant.from("2024-03-15T12:30:45.123456789Z");
console.log(instant.toString());
// Nullen in den Nachkommastellen werden bei "auto" weggelassen
console.log(Temporal.Instant.fromEpochMilliseconds(0).toString());Genauigkeit für Logs und APIs festlegen
const instant = Temporal.Instant.from("2024-03-15T12:30:45.987654321Z");
// Millisekunden, z. B. für eine JavaScript-kompatible API
console.log(instant.toString({ fractionalSecondDigits: 3 }));
// Ganze Sekunden, standardmäßig abgeschnitten
console.log(instant.toString({ smallestUnit: "second" }));
// Kaufmännisch auf Minuten runden
console.log(instant.toString({ smallestUnit: "minute", roundingMode: "halfExpand" }));Ausgabe mit dem Offset einer Zeitzone
const instant = Temporal.Instant.from("2024-07-01T08:00:00Z");
console.log(instant.toString({ timeZone: "Europe/Berlin" }));
console.log(instant.toString({ timeZone: "America/New_York", smallestUnit: "minute" }));
// Mit Zeitzonen-Name in Klammern: über ZonedDateTime
console.log(instant.toZonedDateTimeISO("Europe/Berlin").toString());Zeitstempel speichern und wieder einlesen
const createdAt = Temporal.Now.instant();
const stored = createdAt.toString(); // z. B. in einer Datenbank ablegen
const restored = Temporal.Instant.from(stored);
console.log(restored.equals(createdAt));
// JSON.stringify nutzt toJSON(), das dasselbe Ergebnis liefert wie toString()
console.log(JSON.stringify({ at: Temporal.Instant.fromEpochMilliseconds(0) }));