Wie überprüfen Sie, welches Gebietsschema und welche Optionen ein Formatter tatsächlich verwendet?

Einführung

Wenn Sie einen Intl-Formatter in JavaScript erstellen, sind die Optionen, die Sie anfordern, nicht immer die Optionen, die Sie erhalten. Der Browser führt eine Gebietsschema-Verhandlung durch, füllt Standardwerte aus und normalisiert Ihre Einstellungen, um die endgültige Konfiguration zu erstellen. Die Methode resolvedOptions() ermöglicht es Ihnen, genau zu inspizieren, was der Formatter tatsächlich verwendet.

Jeder Formatter in der Intl-API verfügt über eine Methode resolvedOptions(). Dazu gehören Intl.DateTimeFormat, Intl.NumberFormat, Intl.ListFormat, Intl.PluralRules, Intl.Collator und andere. Die Methode gibt ein Objekt zurück, das alle Konfigurationsdetails enthält, die der Formatter nach der Verarbeitung Ihrer Eingabe letztendlich erhalten hat.

Diese Methode ist hauptsächlich nützlich für das Debugging, das Verständnis des Browser-Verhaltens und die Erkennung, welche Funktionen in der aktuellen Umgebung verfügbar sind.

Die grundlegende Syntax

Die Methode resolvedOptions() nimmt keine Parameter entgegen. Sie rufen sie auf einer beliebigen Formatter-Instanz auf und sie gibt ein Objekt zurück.

const formatter = new Intl.DateTimeFormat('en-US');
const options = formatter.resolvedOptions();

console.log(options);
// {
//   locale: 'en-US',
//   calendar: 'gregory',
//   numberingSystem: 'latn',
//   timeZone: 'America/Los_Angeles',
//   ...
// }

Das zurückgegebene Objekt enthält mindestens die Eigenschaften locale, calendar und numberingSystem für Datumsformatter oder locale und numberingSystem für Zahlenformatter. Zusätzliche Eigenschaften hängen davon ab, welche Optionen Sie angegeben haben und was der Formatter-Typ unterstützt.

Warum sich angeforderte Optionen von aufgelösten Optionen unterscheiden

Es gibt drei Hauptgründe, warum sich die von Ihnen angeforderten Optionen von den aufgelösten Optionen unterscheiden können.

Erstens findet die Gebietsschema-Verhandlung das beste verfügbare Gebietsschema, wenn Ihre genaue Anforderung nicht unterstützt wird. Wenn Sie de-AT anfordern, der Browser jedoch nur de hat, wird das aufgelöste Gebietsschema de sein.

const formatter = new Intl.DateTimeFormat('de-AT-u-ca-buddhist');
const options = formatter.resolvedOptions();

console.log(options.locale);
// Likely outputs: 'de-AT' or 'de'

console.log(options.calendar);
// Likely outputs: 'gregory' (if Buddhist calendar is not supported)

Zweitens füllt der Browser Standardwerte für alle Optionen aus, die Sie nicht angeben. Diese Standardwerte sind gebietsschemaspezifisch.

const formatter = new Intl.NumberFormat('en-US');
const options = formatter.resolvedOptions();

console.log(options.style);
// Outputs: 'decimal'

console.log(options.minimumFractionDigits);
// Outputs: 0

console.log(options.maximumFractionDigits);
// Outputs: 3

Drittens normalisiert der Browser bestimmte Optionen in ihre kanonische Form. Wenn Sie dateStyle oder timeStyle verwenden, nimmt der Browser diese nicht in die aufgelösten Optionen auf. Stattdessen enthält er die einzelnen Komponentenoptionen, in die sie erweitert werden.

Überprüfung des tatsächlich verwendeten Gebietsschemas

Die Eigenschaft locale in den aufgelösten Optionen teilt Ihnen genau mit, welches Gebietsschema der Formatierer verwendet. Dies ist das Ergebnis der Gebietsschema-Aushandlung.

const formatter = new Intl.DateTimeFormat(['zh-TW', 'zh-CN', 'en-US']);
const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs the first supported locale from the list

Wenn Sie ein Gebietsschema anfordern, das Unicode-Erweiterungsschlüsselwörter enthält, enthält das aufgelöste Gebietsschema diese Schlüsselwörter möglicherweise nicht, wenn sie nicht unterstützt wurden oder als separate Optionen angewendet wurden.

const formatter = new Intl.NumberFormat('en-US-u-nu-arab');
const options = formatter.resolvedOptions();

console.log(options.locale);
// Might output: 'en-US'

console.log(options.numberingSystem);
// Might output: 'arab' or 'latn' depending on support

Überprüfung der Datums- und Zeitformatierungsoptionen

Für Intl.DateTimeFormat enthalten die aufgelösten Optionen Details darüber, welche Datums- und Zeitkomponenten angezeigt werden und wie.

const formatter = new Intl.DateTimeFormat('en-US', {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  timeZone: 'America/New_York'
});

const options = formatter.resolvedOptions();

console.log(options.year);
// Outputs: 'numeric'

console.log(options.month);
// Outputs: 'long'

console.log(options.day);
// Outputs: 'numeric'

console.log(options.timeZone);
// Outputs: 'America/New_York'

console.log(options.calendar);
// Outputs: 'gregory'

Wenn Sie dateStyle oder timeStyle verwenden, sind diese Abkürzungen nicht in den aufgelösten Optionen enthalten. Der Browser erweitert sie basierend auf dem Gebietsschema in einzelne Komponentenoptionen.

const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'full'
});

const options = formatter.resolvedOptions();

console.log(options.dateStyle);
// Outputs: undefined

console.log(options.weekday);
// Outputs: 'long'

console.log(options.year);
// Outputs: 'numeric'

console.log(options.month);
// Outputs: 'long'

console.log(options.day);
// Outputs: 'numeric'

Wenn Sie einen Datumsformatierer ohne jegliche Optionen erstellen, zeigen Ihnen die aufgelösten Optionen, was der Browser als Standardwerte für dieses Gebietsschema gewählt hat.

const formatter = new Intl.DateTimeFormat('ja-JP');
const options = formatter.resolvedOptions();

console.log(options);
// Shows default date component options for Japanese locale

Überprüfung der Zahlenformatierungsoptionen

Für Intl.NumberFormat geben Ihnen die aufgelösten Optionen Auskunft über Stil, Genauigkeit, Gruppierung und andere Formatierungsdetails.

const formatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

const options = formatter.resolvedOptions();

console.log(options.style);
// Outputs: 'currency'

console.log(options.currency);
// Outputs: 'USD'

console.log(options.currencyDisplay);
// Outputs: 'symbol'

console.log(options.minimumFractionDigits);
// Outputs: 2

console.log(options.maximumFractionDigits);
// Outputs: 2

Sie können sehen, dass der Browser, obwohl Sie nur die Währung angegeben haben, Standardwerte für currencyDisplay und die Nachkommastellen ausgefüllt hat.

Wenn Sie Rundungsoptionen verwenden, zeigen Ihnen die aufgelösten Optionen genau, wie Zahlen gerundet werden.

const formatter = new Intl.NumberFormat('en-US', {
  minimumSignificantDigits: 3,
  maximumSignificantDigits: 5
});

const options = formatter.resolvedOptions();

console.log(options.minimumSignificantDigits);
// Outputs: 3

console.log(options.maximumSignificantDigits);
// Outputs: 5

Inspektion anderer Formatter-Typen

Die Methode resolvedOptions() funktioniert bei allen Intl-Formattern auf die gleiche Weise.

Für Intl.ListFormat zeigt sie Ihnen den Typ und Stil.

const formatter = new Intl.ListFormat('en-US', {
  style: 'long',
  type: 'conjunction'
});

const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs: 'en-US'

console.log(options.style);
// Outputs: 'long'

console.log(options.type);
// Outputs: 'conjunction'

Für Intl.PluralRules zeigt sie Ihnen den Typ und die minimalen/maximalen Ziffern.

const formatter = new Intl.PluralRules('en-US', {
  type: 'ordinal'
});

const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs: 'en-US'

console.log(options.type);
// Outputs: 'ordinal'

console.log(options.minimumIntegerDigits);
// Outputs: 1

Häufige Anwendungsfälle für resolvedOptions()

Der häufigste Anwendungsfall ist das Debugging. Wenn die formatierte Ausgabe nicht so aussieht, wie Sie es erwarten, hilft Ihnen resolvedOptions() zu verstehen, was der Formatter tatsächlich tut.

const formatter = new Intl.DateTimeFormat('en-US', {
  dateStyle: 'medium'
});

console.log(formatter.format(new Date()));
// Check the output

console.log(formatter.resolvedOptions());
// See exactly which options produced that output

Ein weiterer Anwendungsfall ist die Feature-Erkennung. Sie können überprüfen, ob ein bestimmter Kalender, ein Zahlensystem oder eine andere Funktion unterstützt wird, indem Sie diese anfordern und sehen, was tatsächlich aufgelöst wurde.

const formatter = new Intl.DateTimeFormat('en-US', {
  calendar: 'islamic'
});

const options = formatter.resolvedOptions();

if (options.calendar === 'islamic') {
  console.log('Islamic calendar is supported');
} else {
  console.log('Islamic calendar is not supported, using ' + options.calendar);
}

Sie können auch resolvedOptions() verwenden, um die Locale-Präferenzen der Benutzer zu erhalten. Wenn Sie einen Formatter ohne Locale-Argument erstellen, verwendet der Browser die Präferenzen der Benutzer.

const formatter = new Intl.DateTimeFormat();
const options = formatter.resolvedOptions();

console.log(options.locale);
// Outputs: the user's preferred locale

console.log(options.timeZone);
// Outputs: the user's time zone

console.log(options.hourCycle);
// Outputs: the user's hour cycle preference (12 or 24 hour)

Schließlich können Sie die aufgelösten Optionen verwenden, um einen identischen Formatter neu zu erstellen. Das zurückgegebene Objekt kann an den Konstruktor zurückgegeben werden.

const formatter1 = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD'
});

const options = formatter1.resolvedOptions();

const formatter2 = new Intl.NumberFormat(options.locale, options);

// formatter2 will format numbers identically to formatter1

Wichtige Erkenntnisse

Die Methode resolvedOptions() gibt ein Objekt zurück, das die tatsächliche Konfiguration enthält, die ein Formatter verwendet. Diese Konfiguration kann sich aufgrund von Locale-Verhandlung, Standardwerten und Normalisierung von dem unterscheiden, was Sie angefordert haben.

Jeder Intl-Formatter verfügt über diese Methode. Sie rufen sie ohne Parameter auf und erhalten ein Objekt mit Eigenschaften wie locale, calendar, numberingSystem und formatter-spezifischen Optionen.

Verwenden Sie resolvedOptions() hauptsächlich zum Debuggen des Formatter-Verhaltens, zum Erkennen verfügbarer Funktionen und zum Verstehen, wie der Browser Ihre Optionen interpretiert hat. Das zurückgegebene Objekt kann auch verwendet werden, um einen identischen Formatter neu zu erstellen oder Benutzerpräferenzen zu überprüfen.