Intl.RelativeTimeFormat()-Konstruktor

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

Der Intl.RelativeTimeFormat()-Konstruktor erstellt Intl.RelativeTimeFormat-Objekte.

Syntax

js
new Intl.RelativeTimeFormat()
new Intl.RelativeTimeFormat(locales)
new Intl.RelativeTimeFormat(locales, options)

Note: Intl.RelativeTimeFormat() kann nur mit new konstruiert werden. Ein Versuch, es ohne new aufzurufen, führt zu einem TypeError.

Parameter

locales Optional

Ein String mit einem BCP 47-Sprachcode oder einer Intl.Locale-Instanz oder ein Array solcher Locale-Identifikatoren. Wenn undefined übergeben wird oder keiner der angegebenen Locale-Identifikatoren unterstützt wird, wird die Standard-Locale der Laufzeitumgebung verwendet. Für die allgemeine Form und Interpretation des locales-Arguments siehe die Parameterbeschreibung auf der Intl-Hauptseite.

Der folgende Unicode-Erweiterungsschlüssel ist erlaubt:

nu

Siehe numberingSystem.

Dieser Schlüssel kann auch mit options (wie unten aufgeführt) gesetzt werden. Wenn beide gesetzt sind, hat die options-Eigenschaft Vorrang.

options Optional

Ein Objekt, das die folgenden Eigenschaften enthält, in der Reihenfolge, in der sie abgerufen werden (alle sind optional):

localeMatcher

Der zu verwendende Locale-Abgleichalgorithmus. Mögliche Werte sind "lookup" und "best fit"; der Standard ist "best fit". Weitere Informationen zu dieser Option finden Sie unter Locale-Identifikation und -Verhandlung.

numberingSystem

Das Zahlensystem, das für die Zahlenformatierung verwendet wird, wie "arab", "hans", "mathsans" und so weiter. Eine Liste unterstützter Zahlensystemtypen finden Sie unter Intl.supportedValuesOf(). Diese Option kann auch über den Unicode-Erweiterungsschlüssel nu gesetzt werden; wenn beide bereitgestellt werden, hat diese options-Eigenschaft Vorrang.

style

Der Stil der formatierten relativen Zeit. Mögliche Werte sind:

"long" (Standard)

Z.B. "in 1 month"

"short"

Z.B. "in 1 mo."

"narrow"

Z.B. "in 1 mo.". Der schmale Stil könnte für einige Locale dem kurzen Stil ähnlich sein.

numeric

Ob numerische Werte in der Ausgabe verwendet werden sollen. Mögliche Werte sind "always" und "auto"; der Standard ist "always". Wenn auf "auto" gesetzt, kann die Ausgabe idiomatischere Formulierungen wie "yesterday" anstelle von "1 day ago" verwenden.

Ausnahmen

RangeError

Wird ausgelöst, wenn locales oder options ungültige Werte enthalten.

Beispiele

Grundlegende Formatnutzung

Das folgende Beispiel zeigt, wie ein relativer Zeitformatierer mit der englischen Sprache erstellt wird.

js
// Create a relative time formatter in your locale
// with default values explicitly passed in.
const rtf = new Intl.RelativeTimeFormat("en", {
  localeMatcher: "best fit", // other values: "lookup"
  numeric: "always", // other values: "auto"
  style: "long", // other values: "short" or "narrow"
});

// Format relative time using negative value (-1).
rtf.format(-1, "day"); // "1 day ago"

// Format relative time using positive value (1).
rtf.format(1, "day"); // "in 1 day"

Verwendung der Auto-Option

Wenn die Option numeric:auto übergeben wird, erzeugt sie den String yesterday oder tomorrow anstelle von 1 day ago oder in 1 day. Dies ermöglicht, nicht immer numerische Werte in der Ausgabe verwenden zu müssen.

js
// Create a relative time formatter in your locale
// with numeric: "auto" option value passed in.
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

// Format relative time using negative value (-1).
rtf.format(-1, "day"); // "yesterday"

// Format relative time using positive day unit (1).
rtf.format(1, "day"); // "tomorrow"

Spezifikationen

Specification
ECMAScript® 2025 Internationalization API Specification
# sec-intl-relativetimeformat-constructor

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch