Intl.Collator.prototype.resolvedOptions() — Methode · JavaScript-Referenz

Signatur

Intl.Collator.prototype.resolvedOptions()

Beschreibung

resolvedOptions() zeigt, welche Einstellungen ein Intl.Collator tatsächlich verwendet. Das kann von den übergebenen Werten abweichen: Die Engine gleicht die gewünschten Locales mit den verfügbaren ab, ergänzt fehlende Optionen durch Standardwerte und übernimmt Unicode-Erweiterungen wie -u-kn-true oder -u-co-phonebk aus dem Locale-String.

Das zurückgegebene Objekt enthält diese Eigenschaften:

locale: der BCP-47-Tag der tatsächlich verwendeten Locale, einschließlich der unterstützten Unicode-Erweiterungen
usage: "sort" oder "search"
sensitivity: "base", "accent", "case" oder "variant"
ignorePunctuation: true oder false
collation: die Sortierart, z. B. "default", "phonebk" oder "pinyin"
numeric: true oder false (numerische Sortierung, „2“ vor „10“)
caseFirst: "upper", "lower" oder "false" (als String!)

Typische Einsatzfälle: Sie prüfen, ob die gewünschte Sprache wirklich unterstützt wird oder ob die Engine auf eine andere Locale ausgewichen ist. Sie protokollieren die Sortiereinstellungen beim Debuggen. Oder Sie übernehmen die Konfiguration eines Collators, um einen zweiten mit denselben Einstellungen zu erzeugen.

Rückgabewert

Typ

{ locale: string, usage: string, sensitivity: string, ignorePunctuation: boolean, collation: string, numeric: boolean, caseFirst: string }

Beschreibung

Ein neues, einfaches Objekt mit den ausgehandelten Optionen. Wenn Sie es ändern, ändert sich am Collator nichts.

Beispiele

Standard-Optionen eines deutschen Collators anzeigen

const collator = new Intl.Collator('de');
console.log(collator.resolvedOptions());

{ locale: 'de', usage: 'sort', sensitivity: 'variant', ignorePunctuation: false, collation: 'default', numeric: false, caseFirst: 'false' }

Optionen aus Unicode-Erweiterung und Options-Objekt

// numeric per Erweiterung „kn“, sensitivity per Options-Objekt
const collator = new Intl.Collator('de-DE-u-kn-true', { sensitivity: 'base' });
const { locale, numeric, sensitivity } = collator.resolvedOptions();

console.log(locale, numeric, sensitivity);
console.log(['Datei10', 'datei2', 'Datei1'].sort(collator.compare));

de-DE-u-kn true base [ 'Datei1', 'datei2', 'Datei10' ]

Prüfen, ob die Engine auf eine andere Locale ausgewichen ist

const createCollator = (wanted) => {
  const collator = new Intl.Collator(wanted);
  const { locale } = collator.resolvedOptions();
  if (!locale.toLowerCase().startsWith(wanted.split('-')[0].toLowerCase())) {
    console.warn(`„${wanted}“ wird nicht unterstützt, verwende „${locale}“.`);
  }
  return collator;
};

createCollator('tlh'); // Klingonisch: in der Regel nicht verfügbar

„tlh“ wird nicht unterstützt, verwende „de-DE“. (die Ersatz-Locale hängt von der Systemsprache ab)

Collator mit identischen Einstellungen nachbauen

const original = new Intl.Collator('sv', { sensitivity: 'accent', numeric: true });
const { locale, ...options } = original.resolvedOptions();

const kopie = new Intl.Collator(locale, options);
console.log(kopie.compare('a', 'A'), kopie.compare('a', 'ä'));

0 -1

// Wichtig · Fallstricke

Die Werte hängen von der Umgebung ab: Welche Locale ausgewählt wird und welche collation-Werte verfügbar sind, bestimmt die ICU-Version der Engine. Die Ausgaben können sich zwischen Browsern, Node.js-Builds (z. B. small-icu) und Betriebssystemen unterscheiden.
caseFirst ist bei „keine Präferenz“ der String "false", nicht der boolesche Wert false. Ein Vergleich mit === false schlägt also fehl.
Laut Spezifikation sind numeric und caseFirst nur vorhanden, wenn die Implementierung diese Optionen unterstützt. Alle aktuellen Engines liefern beide.
Der Standardwert von ignorePunctuation hängt von der Locale ab. Für Thai (th) ist er zum Beispiel true.
In locale erscheinen nur unterstützte Unicode-Erweiterungen. Nicht erkannte oder durch das Options-Objekt überschriebene Erweiterungen fehlen, deshalb weicht der zurückgegebene Tag oft vom übergebenen ab.
Jeder Aufruf erzeugt ein neues Objekt. Rufen Sie die Methode in Schleifen, die viel Leistung brauchen, nicht bei jedem Durchlauf auf, sondern speichern Sie das Ergebnis zwischen.
Wird die Methode auf einem Objekt aufgerufen, das kein Intl.Collator ist (z. B. über call), wirft sie einen TypeError.

Siehe auch

Intl.Collator Intl.Collator.prototype.compare Intl.Collator.supportedLocalesOf() String.prototype.localeCompare() Intl.DateTimeFormat.prototype.resolvedOptions() Intl.NumberFormat.prototype.resolvedOptions()