Wie überprüfen Sie, welche Locale und Optionen ein Formatierer tatsächlich verwendet?

Einführung

Wenn Sie einen Intl-Formatierer in JavaScript erstellen, sind die von Ihnen angeforderten Optionen nicht immer die Optionen, die Sie erhalten. Der Browser führt eine Locale-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 überprüfen, was der Formatierer tatsächlich verwendet.

Jeder Formatierer in der Intl-API verfügt über eine resolvedOptions()-Methode. 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 Formatierer nach der Verarbeitung Ihrer Eingabe 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 Formatierer-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 immer mindestens die Eigenschaften locale, calendar und numberingSystem für Datumsformatierer oder locale und numberingSystem für Zahlenformatierer. Zusätzliche Eigenschaften hängen davon ab, welche Optionen Sie angegeben haben und welche der Formatierertyp unterstützt.

Warum angeforderte Optionen von aufgelösten Optionen abweichen

Es gibt drei Hauptgründe, warum die von Ihnen angeforderten Optionen von den aufgelösten Optionen abweichen könnten.

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

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

console.log(options.locale);
// Gibt wahrscheinlich aus: 'de-AT' oder 'de'

console.log(options.calendar);
// Gibt wahrscheinlich aus: 'gregory' (wenn der buddhistische Kalender nicht unterstützt wird)

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

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

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

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

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

Drittens normalisiert der Browser bestimmte Optionen in ihre kanonische Form. Wenn Sie dateStyle oder timeStyle verwenden, werden diese nicht in den aufgelösten Optionen enthalten sein. Stattdessen enthält er die einzelnen Komponentenoptionen, zu denen 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);
// Gibt das erste unterstützte Gebietsschema aus der Liste aus

Wenn Sie ein Gebietsschema anfordern, das Unicode-Erweiterungsschlüsselwörter enthält, enthält das aufgelöste Gebietsschema möglicherweise nicht diese Schlüsselwörter, 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);
// Könnte ausgeben: 'en-US'

console.log(options.numberingSystem);
// Könnte 'arab' oder 'latn' ausgeben, abhängig von der Unterstützung

Untersuchung der Datums- und Uhrzeitformatierungsoptionen

Für Intl.DateTimeFormat enthalten die aufgelösten Optionen Details darüber, welche Datums- und Uhrzeitkomponenten 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);
// Gibt aus: 'numeric'

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

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

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

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

Wenn Sie dateStyle oder timeStyle verwenden, sind diese Shortcuts nicht in den aufgelösten Optionen enthalten. Der Browser erweitert sie zu einzelnen Komponentenoptionen basierend auf dem Gebietsschema.

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

const options = formatter.resolvedOptions();

console.log(options.dateStyle);
// Gibt aus: undefined

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

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

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

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

Wenn Sie einen Datumsformatierer ganz ohne 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);
// Zeigt Standard-Datumskomponentenoptionen für das japanische Gebietsschema

Überprüfen der Zahlenformatierungsoptionen

Für Intl.NumberFormat zeigen die aufgelösten Optionen den Stil, die Präzision, die Gruppierung und andere Formatierungsdetails an.

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

const options = formatter.resolvedOptions();

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

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

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

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

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

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

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

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

const options = formatter.resolvedOptions();

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

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

Überprüfen anderer Formatierertypen

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

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

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

const options = formatter.resolvedOptions();

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

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

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

Für Intl.PluralRules zeigt sie den Typ und die minimalen/maximalen Stellen an.

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

const options = formatter.resolvedOptions();

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

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

console.log(options.minimumIntegerDigits);
// Ausgabe: 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 resolvedOptions() zu verstehen, was der Formatierer tatsächlich tut.

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

console.log(formatter.format(new Date()));
// Überprüfen Sie die Ausgabe

console.log(formatter.resolvedOptions());
// Sehen Sie genau, welche Optionen diese Ausgabe erzeugt haben

Ein weiterer Anwendungsfall ist die Funktionserkennung. 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('Islamischer Kalender wird unterstützt');
} else {
  console.log('Islamischer Kalender wird nicht unterstützt, verwende ' + options.calendar);
}

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

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

console.log(options.locale);
// Ausgabe: die bevorzugte Locale des Benutzers

console.log(options.timeZone);
// Ausgabe: die Zeitzone des Benutzers

console.log(options.hourCycle);
// Ausgabe: die Stundenzyklus-Präferenz des Benutzers (12- oder 24-Stunden-Format)

Schließlich können Sie die aufgelösten Optionen verwenden, um einen identischen Formatierer 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 wird Zahlen identisch zu formatter1 formatieren

Wichtige Erkenntnisse

Die Methode resolvedOptions() gibt ein Objekt zurück, das die tatsächliche Konfiguration enthält, die ein Formatierer verwendet. Diese Konfiguration kann aufgrund von Locale-Verhandlung, Standardwerten und Normalisierung von Ihren Anforderungen abweichen.

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

Verwenden Sie resolvedOptions() hauptsächlich zum Debuggen des Formatierer-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 Formatierer zu erstellen oder Benutzereinstellungen zu überprüfen.