Temporal.ZonedDateTime.compare() — Methode · JavaScript-Referenz

Signatur

Temporal.ZonedDateTime.compare(dateTime1, dateTime2)

Beschreibung

Temporal.ZonedDateTime.compare() ist eine statische Methode. Du rufst sie also auf Temporal.ZonedDateTime auf und nicht auf einer Instanz. Sie gibt -1 zurück, wenn dateTime1 vor dateTime2 liegt, 0, wenn beide denselben Zeitpunkt bezeichnen, und 1, wenn dateTime1 später liegt.

Verglichen wird nur der exakte Zeitpunkt, also intern epochNanoseconds. Zeitzone und Kalender spielen dabei keine Rolle. 12:00 Uhr in Berlin und 06:00 Uhr in New York können deshalb als gleich (0) gelten. Soll auch geprüft werden, ob Zeitzone und Kalender übereinstimmen, nimm Temporal.ZonedDateTime.prototype.equals().

Die Rückgabewerte passen genau zu dem, was Array.prototype.sort() erwartet. Du kannst die Methode deshalb direkt übergeben: termine.sort(Temporal.ZonedDateTime.compare). Das ist praktisch für Kalender, Buchungssysteme oder Logs mit Einträgen aus mehreren Zeitzonen.

Neben Temporal.ZonedDateTime-Objekten sind auch Strings nach RFC 9557 (z. B. "2024-03-05T12:00+01:00[Europe/Berlin]") und Objekte mit einzelnen Datumsfeldern (Property-Bags) erlaubt. Beide werden intern wie bei Temporal.ZonedDateTime.from() umgewandelt.

Parameter

Name	Typ	Default	Beschreibung
$dateTime1 Pflicht	Temporal.ZonedDateTime \| string \| object		Erster Zeitpunkt. Das kann eine `ZonedDateTime`-Instanz sein, ein RFC-9557-String mit Zeitzonen-Angabe in eckigen Klammern oder ein Objekt mit Datumsfeldern und `timeZone`.
$dateTime2 Pflicht	Temporal.ZonedDateTime \| string \| object		Zweiter Zeitpunkt, mit dem `dateTime1` verglichen wird. Erlaubt sind dieselben Formen wie bei `dateTime1`.

Beispiele

Gleicher Zeitpunkt in verschiedenen Zeitzonen

const berlin = Temporal.ZonedDateTime.from("2024-03-05T12:00[Europe/Berlin]");
const newYork = Temporal.ZonedDateTime.from("2024-03-05T06:00[America/New_York]");

// compare() betrachtet nur den exakten Zeitpunkt (beide = 11:00 UTC)
console.log(Temporal.ZonedDateTime.compare(berlin, newYork));

// equals() prüft zusätzlich Zeitzone und Kalender
console.log(berlin.equals(newYork));

0 false

Termine aus mehreren Zeitzonen chronologisch sortieren

const termine = [
  Temporal.ZonedDateTime.from("2024-03-05T09:00[America/New_York]"),
  Temporal.ZonedDateTime.from("2024-03-05T12:00[Europe/Berlin]"),
  Temporal.ZonedDateTime.from("2024-03-05T19:00[Asia/Tokyo]"),
];

// Aufsteigend: direkt als Vergleichsfunktion übergeben
termine.sort(Temporal.ZonedDateTime.compare);
termine.forEach((t) => console.log(t.toString()));

// Absteigend: Argumente vertauschen
const neuesteZuerst = termine.toSorted((a, b) => Temporal.ZonedDateTime.compare(b, a));
console.log(neuesteZuerst[0].timeZoneId);

2024-03-05T19:00:00+09:00[Asia/Tokyo] 2024-03-05T12:00:00+01:00[Europe/Berlin] 2024-03-05T09:00:00-05:00[America/New_York] America/New_York

Doppelte Stunde bei der Zeitumstellung unterscheiden

// Am 27.10.2024 gibt es in Berlin 02:30 Uhr zweimal (erst CEST, dann CET)
const ersteMal = "2024-10-27T02:30+02:00[Europe/Berlin]";
const zweitesMal = "2024-10-27T02:30+01:00[Europe/Berlin]";

// Strings werden wie bei from() umgewandelt
console.log(Temporal.ZonedDateTime.compare(ersteMal, zweitesMal));

-1

Prüfen, ob eine Frist abgelaufen ist

const frist = Temporal.ZonedDateTime.from({
  year: 2024, month: 12, day: 31, hour: 23, minute: 59,
  timeZone: "Europe/Berlin",
});

const istAbgelaufen = (jetzt) => Temporal.ZonedDateTime.compare(jetzt, frist) > 0;

const eingang = Temporal.ZonedDateTime.from("2025-01-01T00:30[Europe/London]");
console.log(istAbgelaufen(eingang)); // 00:30 London = 01:30 Berlin

true

// Wichtig · Fallstricke

compare() ist nicht dasselbe wie equals(): compare() achtet nur auf den exakten Zeitpunkt. equals() verlangt zusätzlich dieselbe Zeitzone und denselben Kalender. Ein Ergebnis von 0 heißt deshalb nicht, dass equals() true liefert.
Keine Vergleichsoperatoren: <, > usw. lösen bei Temporal-Objekten einen TypeError aus, weil valueOf() absichtlich einen Fehler wirft. Nutze immer compare().
Strings brauchen eine Zeitzone: Ein String ohne Zeitzonen-Angabe in eckigen Klammern (z. B. "2024-01-01T12:00Z") führt zu einem RangeError. Bei einem Objekt ohne timeZone gibt es einen TypeError. Passen Offset und Zeitzone in einem String nicht zusammen, gibt es ebenfalls einen RangeError.
Willst du nur die Wanduhrzeit vergleichen, also ohne Zeitzone, wandle die Werte vorher mit toPlainDateTime() um und verwende Temporal.PlainDateTime.compare().
Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar. Unterstützt wird es in Firefox ab 139 und in Chrome/Edge ab 144, in Safari noch nicht. Für ältere Umgebungen gibt es Polyfills wie @js-temporal/polyfill oder temporal-polyfill.

Siehe auch

Temporal.PlainDateTime.compare() Temporal.ZonedDateTime.from() Temporal.PlainTime.compare() Temporal.PlainDate.compare() Temporal.Duration.compare()