Temporal.ZonedDateTime.prototype.toString()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Die toString()-Methode von Temporal.ZonedDateTime-Instanzen gibt einen String zurück, der dieses Datum-Zeit-Objekt im RFC 9557 Format darstellt.

Syntax

toString()
toString(options)

Parameter

options Optional

Ein Objekt, das die folgende Eigenschaft enthält:

calendarName Optional

Ob die Kalenderanmerkung ([u-ca=calendar_id]) im Rückgabewert angezeigt werden soll. Mögliche Werte sind:

"auto" (Standard): Die Kalenderanmerkung wird hinzugefügt, wenn der Kalender nicht "iso8601" ist.
"always": Die Kalenderanmerkung wird immer hinzugefügt.
"never": Die Kalenderanmerkung wird niemals hinzugefügt. Dies macht den zurückgegebenen String für dieselbe Temporal.ZonedDateTime-Instanz nicht wiederherstellbar, obwohl der Datumswert gleich bleibt.
"critical": Die Kalenderanmerkung wird immer hinzugefügt und ein kritisches Flag wird hinzugefügt: [!u-ca=calendar_id]. Nützlich, wenn der String an bestimmte Systeme gesendet wird, aber nicht für Temporal selbst von Nutzen.

fractionalSecondDigits Optional

Entweder eine Ganzzahl von 0 bis 9 oder der String "auto". Der Standardwert ist "auto". Wenn "auto" ausgewählt ist, werden die nachfolgenden Nullen aus den Bruchteilen der Sekunden entfernt. Andernfalls enthält der Bruchteil der Sekundenkomponente so viele Ziffern, die nach Bedarf mit Nullen aufgefüllt oder gerundet werden.

roundingMode Optional

Ein String, der angibt, wie Bruchteile von Sekunden, die über fractionalSecondDigits hinausgehen, abgerundet werden sollen. Siehe Intl.NumberFormat(). Der Standardwert ist "trunc".

smallestUnit Optional

Ein String, der die kleinste Einheit angibt, die in der Ausgabe enthalten sein soll. Mögliche Werte sind "minute", "second", "millisecond", "microsecond" und "nanosecond", oder deren Pluralformen, die (außer "minute") äquivalent zu fractionalSecondDigits-Werten von 0, 3, 6, 9 sind. Wenn angegeben, wird fractionalSecondDigits ignoriert.

timeZoneName Optional

Ob der Name der Zeitzone ([time_zone_id]) im Rückgabewert angezeigt werden soll. Mögliche Werte sind:

"auto" (Standard): Der Name der Zeitzone wird immer hinzugefügt.
"never": Der Name der Zeitzone wird niemals hinzugefügt. Dies macht den zurückgegebenen String für dieselbe Temporal.ZonedDateTime-Instanz nicht wiederherstellbar.
"critical": Der Name der Zeitzone wird immer hinzugefügt und ein kritisches Flag wird hinzugefügt: [!time)zone_id]. Nützlich, wenn der String an bestimmte Systeme gesendet wird, aber nicht für Temporal selbst von Nutzen.

offset Optional

Ob der Offset (±HH:mm) im Rückgabewert angezeigt werden soll. Mögliche Werte sind:

"auto" (Standard): Der Offset wird immer hinzugefügt.
"never": Der Offset wird niemals hinzugefügt. Dies macht den zurückgegebenen String für dieselbe Temporal.ZonedDateTime-Instanz nicht wiederherstellbar, wenn die Zeitzone enthalten ist, die Zeit aber mehrdeutig ist, oder wenn die Zeitzone auch nicht enthalten ist.

Rückgabewert

Ein String im RFC 9557 Format, der dieses Datum-Zeit-Objekt darstellt. Der Offset und die Kalender-/Zeitzonenanmerkungen sind wie angegeben enthalten.

Ausnahmen

RangeError: Wird ausgelöst, wenn eine der Optionen ungültig ist.
TypeError: Wird ausgelöst, wenn options kein Objekt oder undefined ist.

Beispiele

Verwendung von toString()

const zdt = Temporal.ZonedDateTime.from(
  "2021-08-01T12:34:56[America/New_York]",
);
console.log(zdt.toString()); // '2021-08-01T12:34:56-04:00[America/New_York]'

Auch für die Zeitzone UTC ist der Offset +00:00, nicht Z:

const zdt = Temporal.ZonedDateTime.from("2021-08-01T12:34:56[UTC]");
console.log(zdt.toString()); // '2021-08-01T12:34:56+00:00[UTC]'

Verwendung von Optionen

Für Beispiele mit Rundungszeiten siehe Temporal.PlainTime.prototype.toString(). Für Beispiele zur Anzeige von Kalendern siehe Temporal.PlainDate.prototype.toString(). Hier zeigen wir die Kontrolle über die Anzeige von Zeitzone und Offset:

const zdt = Temporal.ZonedDateTime.from(
  "2021-08-01T12:34:56[America/New_York]",
);
console.log(zdt.toString({ timeZoneName: "auto", offset: "never" })); // '2021-08-01T12:34:56[America/New_York]'
console.log(zdt.toString({ timeZoneName: "never", offset: "auto" })); // '2021-08-01T12:34:56-04:00'
console.log(zdt.toString({ timeZoneName: "never", offset: "never" })); // '2021-08-01T12:34:56'
console.log(zdt.toString({ timeZoneName: "critical", offset: "never" })); // '2021-08-01T12:34:56[!America/New_York]'

Spezifikationen

Specification
Temporal # sec-temporal.zoneddatetime.prototype.tostring