WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Intl.RelativeTimeFormat.prototype.format() — relative Zeitangaben formatieren

Formatiert einen Zeitabstand mit Vorzeichen und eine explizite Einheit als lokalisierten Text. Die Methode berechnet keine Differenz zwischen Datumswerten.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

const formatter = new Intl.RelativeTimeFormat(locales, options);
formatter.format(value, unit);

Intl.RelativeTimeFormat.prototype.format ist eine Instanzmethode. formatter.format(value, unit) gibt einen String in der tatsächlich verwendeten Spracheinstellung und mit den beim Erstellen festgelegten Optionen zurück. Die Anwendung berechnet den Abstand zum Bezugspunkt und wählt die Einheit; die Methode fragt weder die Uhr ab noch subtrahiert sie Datumswerte.

Negative Werte stehen für die Vergangenheit, positive für die Zukunft. Bei numerischen Mustern wählt -0 das Vergangenheitsmuster und +0 das Zukunftsmuster. unit akzeptiert genau "second", "minute", "hour", "day", "week", "month", "quarter" und "year" sowie die jeweiligen Formen mit angehängtem s. Die Form des Bezeichners bestimmt nicht die Grammatik der Ausgabe.

numeric: "always" (Standard) verwendet ein numerisches Muster. numeric: "auto" nutzt einen eigenen Ausdruck wie yesterday, falls verfügbar, sonst ein numerisches Muster. style wählt "long" (Standard), "short" oder "narrow". Die Unterstützung hängt von der Laufzeitumgebung ab. Selbst bei derselben Spracheinstellung kann der Text abweichen, etwa durch geschützte Leerzeichen. Vergleiche die Ausgabe in portablen Tests nicht mit fest vorgegebenem Text.

Die Methode braucht eine Formatiererinstanz als this. Ein losgelöster Aufruf ohne gültiges this führt zu TypeError. Als Callback eignet sich formatter.format.bind(formatter). Nach der Prüfung von this wendet die Methode ToNumber auf value und danach ToString auf unit an. Ein BigInt als value löst zum Beispiel TypeError aus. Nach der Umwandlung führen NaN, Infinity, -Infinity oder ein nicht unterstützter Einheitenbezeichner zu RangeError.

Beispiele

{
  const numeric = new Intl.RelativeTimeFormat("en", { numeric: "always" });
  const auto = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
  const past = numeric.format(-1, "day");
  console.log(past);
  console.log(auto.format(-1, "day"));
  console.log(past === numeric.format(-1, "days"));
}

Ergebnis

1 day ago
yesterday
true

Für denselben Abstand von `-1` Tag zeigen die ersten beiden Zeilen typische englische Ausgaben für `"always"` und `"auto"`. Die dritte Zeile zeigt, dass `"day"` und `"days"` gleichwertig sind.

Zugehörige Lektionen

  • JavaScript · Lektion 24 · Fortgeschritten · Version: 4

Quellen