String.prototype.localeCompare()

Метод localeCompare() значений String возвращает число, указывающее, предшествует ли данная строка, следует ли за ней или совпадает с заданной строкой в порядке сортировки. В реализациях с поддержкой Intl.Collator API этот метод делегирует Intl.Collator.

При сравнении большого количества строк, например при сортировке больших массивов, лучше создать объект Intl.Collator и использовать функцию, предоставляемую его методом compare().

Попробуйте

const a = "réservé"; // With accents, lowercase
const b = "RESERVE"; // No accents, uppercase

console.log(a.localeCompare(b));
// Expected output: 1
console.log(a.localeCompare(b, "en", { sensitivity: "base" }));
// Expected output: 0

Синтаксис

localeCompare(compareString)
localeCompare(compareString, locales)
localeCompare(compareString, locales, options)

Параметры

Параметры locales и options настраивают поведение функции и позволяют приложениям указать язык, чьи правила форматирования должны использоваться.

В реализациях, поддерживающих Intl.Collator API, эти параметры точно соответствуют параметрам конструктора Intl.Collator(). Реализации без поддержки Intl.Collator должны игнорировать оба параметра, что делает возвращаемый результат сравнения полностью зависящим от реализации — требуется лишь, чтобы он был согласованным.

compareString

Строка, с которой сравнивается referenceStr. Все значения преобразуются в строки, поэтому опущение или передача undefined приводит к тому, что localeCompare() сравнивается со строкой "undefined", что редко является желаемым результатом.

locales Необязательно

Строка с языковым тегом BCP 47 или массив таких строк. Соответствует параметру locales конструктора Intl.Collator().

В реализациях без поддержки Intl.Collator этот параметр игнорируется, и обычно используется локаль хоста.

options Необязательно

Объект, настраивающий формат вывода. Соответствует параметру options конструктора Intl.Collator().

В реализациях без поддержки Intl.Collator этот параметр игнорируется.

См. конструктор Intl.Collator() для получения подробной информации о параметрах locales и options и способах их использования.

Возвращаемое значение

Отрицательное число, если referenceStr предшествует compareString; положительное, если referenceStr следует за compareString; 0, если они эквивалентны.

В реализациях с Intl.Collator это эквивалентно new Intl.Collator(locales, options).compare(referenceStr, compareString).

Описание

Возвращает целое число, указывающее, предшествует ли referenceStr, следует ли за ним или эквивалентно compareString.

• Отрицательное, когда referenceStr предшествует compareString
• Положительное, когда referenceStr следует за compareString
• Возвращает 0, если они эквивалентны

Примеры

Использование localeCompare()

// The letter "a" is before "c" yielding a negative value
"a".localeCompare("c"); // -2 or -1 (or some other negative value)

// Alphabetically the word "check" comes after "against" yielding a positive value
"check".localeCompare("against"); // 2 or 1 (or some other positive value)

// "a" and "a" are equivalent yielding a neutral value of zero
"a".localeCompare("a"); // 0

Сортировка массива

localeCompare() включает сортировку массива без учета регистра.

const items = ["réservé", "Premier", "Cliché", "communiqué", "café", "Adieu"];
items.sort((a, b) => a.localeCompare(b, "fr", { ignorePunctuation: true }));
// ['Adieu', 'café', 'Cliché', 'communiqué', 'Premier', 'réservé']

Проверка поддержки расширенных аргументов в браузере

Аргументы locales и options пока поддерживаются не во всех браузерах.

Чтобы проверить, поддерживает ли их реализация, используйте аргумент "i" (требование, согласно которому недопустимые языковые теги отклоняются) и ищите исключение RangeError:

function localeCompareSupportsLocales() {
  try {
    "foo".localeCompare("bar", "i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}

Использование локалей

Результаты, предоставляемые localeCompare(), различаются в зависимости от языка. Чтобы получить порядок сортировки языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, некоторые резервные языки), используя аргумент locales:

console.log("ä".localeCompare("z", "de")); // a negative value: in German, ä sorts before z
console.log("ä".localeCompare("z", "sv")); // a positive value: in Swedish, ä sorts after z

Использование опций

Результаты, предоставляемые localeCompare(), могут быть настроены с помощью аргумента options:

// in German, ä has a as the base letter
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0

// in Swedish, ä and a are separate base letters
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // a positive value

Числовая сортировка

// by default, "2" > "10"
console.log("2".localeCompare("10")); // 1

// numeric using options:
console.log("2".localeCompare("10", undefined, { numeric: true })); // -1

// numeric using locales tag:
console.log("2".localeCompare("10", "en-u-kn-true")); // -1

Спецификации

Совместимость с браузерами

См. также

• Intl.Collator