Constructeur Intl.Collator()

Exemple interactif

console.log(["Z", "a", "z", "ä"].sort(new Intl.Collator("de").compare));
// Résultat attendu : Array ["a", "ä", "z", "Z"]

console.log(["Z", "a", "z", "ä"].sort(new Intl.Collator("sv").compare));
// Résultat attendu : Array ["a", "z", "Z", "ä"]

console.log(
  ["Z", "a", "z", "ä"].sort(
    new Intl.Collator("de", { caseFirst: "upper" }).compare,
  ),
);
// Résultat attendu : Array ["a", "ä", "Z", "z"]

Syntaxe

new Intl.Collator()
new Intl.Collator(locales)
new Intl.Collator(locales, options)

Intl.Collator()
Intl.Collator(locales)
Intl.Collator(locales, options)

Paramètres

locales Facultatif

Une chaîne de caractères avec une étiquette de langue BCP 47 ou une instance de Intl.Locale, ou un tableau de ces identifiants de locale. La locale par défaut de l'environnement d'exécution est utilisée lorsque undefined est passé ou lorsqu'aucun des identifiants de locale définis n'est pris en charge. Pour la forme générale et l'interprétation de l'argument locales, voir la description du paramètre sur la page principale d'Intl.

Les clés d'extension Unicode suivantes sont autorisées :

co

Voir collation.

kn

Voir numeric.

kf

Voir caseFirst.

Ces clés peuvent également être définies avec options (comme listé ci-dessous). Lorsque les deux sont définis, la propriété options a la priorité.

options Facultatif

Un objet contenant les propriétés suivantes, dans l'ordre où elles sont récupérées (toutes sont optionnelles) :

usage

Indique si la comparaison sert à trier une liste de chaînes de caractères ou à filtrer de façon approximative (pour l'écriture latine, insensible aux diacritiques et à la casse) une liste de chaînes de caractères par clé. Les valeurs possibles sont :

"sort" (par défaut)

Pour trier une liste de chaînes de caractères.

"search"

Pour filtrer une liste de chaînes de caractères en testant chaque élément de la liste pour une correspondance complète avec une clé. Avec "search", il faut seulement vérifier si compare() retourne zéro ou une valeur différente de zéro et peut ne pas distinguer les valeurs non nulles entre elles. Il n'est donc pas approprié d'utiliser "search" pour trier/ordonner.

localeMatcher

L'algorithme de correspondance des locales à utiliser. Les valeurs possibles sont "lookup" et "best fit" ; la valeur par défaut est "best fit". Pour plus d'informations sur cette option, voir Identification et négociation de la locale.

collation

Variantes de collations pour certaines locales, telles que "emoji", "pinyin", "stroke", etc. N'a d'effet que lorsque usage vaut "sort" (car "search" utilise son propre type de collation). Pour la liste des types de collations pris en charge, voir Intl.supportedValuesOf() ; la valeur par défaut est "default". Cette option peut aussi être définie via la clé d'extension Unicode co ; si les deux sont fournies, la propriété options a la priorité.

numeric

Indique si une collation numérique doit être utilisée, de sorte que « 1 » < « 2 » < « 10 ». Les valeurs possibles sont true et false ; la valeur par défaut est false. Cette option peut aussi être définie via la clé d'extension Unicode kn ; si les deux sont fournies, la propriété options a la priorité.

caseFirst

Indique si les majuscules ou les minuscules doivent être triées en premier. Les valeurs possibles sont "upper", "lower" et "false" (utilise la valeur par défaut de la locale) ; la valeur par défaut est "false". Cette option peut aussi être définie via la clé d'extension Unicode kf ; si les deux sont fournies, la propriété options a la priorité.

sensitivity

Indique quelles différences dans les chaînes de caractères doivent entraîner des valeurs de résultat non nulles. Les valeurs possibles sont :

"base"

Seules les chaînes de caractères qui diffèrent par les lettres de base sont considérées comme différentes. Exemples : a ≠ b, a = á, a = A. Dans l'algorithme de collation Unicode, cela correspond au niveau de force primaire.

"accent"

Seules les chaînes de caractères qui diffèrent par les lettres de base ou les accents et autres marques diacritiques sont considérées comme différentes. Exemples : a ≠ b, a ≠ á, a = A. Dans l'algorithme de collation Unicode, cela correspond au niveau de force secondaire.

"case"

Seules les chaînes de caractères qui diffèrent par les lettres de base ou la casse sont considérées comme différentes. Exemples : a ≠ b, a = á, a ≠ A. Dans l'algorithme de collation Unicode, cela correspond au niveau de force primaire avec gestion de la casse.

"variant"

Les chaînes de caractères qui diffèrent par les lettres de base, les accents et autres marques diacritiques, ou la casse, sont considérées comme différentes. D'autres différences peuvent aussi être prises en compte. Exemples : a ≠ b, a ≠ á, a ≠ A. Dans l'algorithme de collation Unicode, cela correspond au niveau de force tertiaire.

La valeur par défaut est "variant" pour l'usage "sort" ; elle dépend de la locale pour l'usage "search" selon la spécification, mais est généralement aussi "variant". Comme la fonctionnalité principale de "search" est le filtrage insensible aux accents et à la casse, la valeur "base" est la plus logique (et peut-être "case").

ignorePunctuation

Indique si la ponctuation doit être ignorée. Les valeurs possibles sont true et false. La valeur par défaut est true pour le thaï (th) et false pour toutes les autres langues.

Exceptions

RangeError

Levée si locales ou options contiennent des valeurs invalides.

Exemples

Utiliser Collator()

Dans l'exemple suivant, on illustre la comparaison de deux chaînes de caractères et le résultat obtenu selon que l'une est située avant ou après, ou de façon équivalente selon l'ordre lexicographique de la langue :

console.log(new Intl.Collator().compare("a", "c")); // -1, ou une valeur négative
console.log(new Intl.Collator().compare("c", "a")); // 1, ou une valeur positive
console.log(new Intl.Collator().compare("a", "a")); // 0

On notera que les résultats obtenus avec les lignes précédentes peuvent varier d'un navigateur à l'autre et entre les différentes versions. En effet, les valeurs numériques obtenues sont spécifiques aux implémentations et la spécification n'impose que le signe de la valeur obtenue.

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'objet Intl.Collator
• L'objet Intl