String.prototype.localeCompare()

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

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

Интерактивный пример

Синтаксис

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

Параметры

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

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

compareString

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

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

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

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

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

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

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

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

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

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

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

Описание

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

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

Предупреждение: Не полагайтесь на точные значения -1 и 1!

Отрицательные и положительные ответы отличаются в зависимости от браузера (и версии браузера), потому что спецификация ECMAScript определяет только то, что числа должны быть положительными и отрицательными. Некоторые браузеры могут возвращать -2 или 2 или другие значения.

Примеры

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

js
// Буква "а" идёт перед "в", поэтому результат будет отрицательным
"а".localeCompare("в"); // -2 или -1 (или другое отрицательное число)

// В алфавитном порядке слово "первый" идёт после "второй", поэтому результат будет положительным
"первый".localeCompare("второй"); // 2 или 1 (или другое положительное число)

// "а" и "а" одинаковы, поэтому результат будет равен нулю
"а".localeCompare("а"); // 0

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

localeCompare() даёт возможность регистронезависимой сортировки массивов.

js
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

Параметры locales и options поддерживаются ещё не всеми браузерами.

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

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

Использование параметра locales

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

js
console.log("ä".localeCompare("z", "de")); // отрицательное значение: в немецком буква ä идёт рядом с буквой a
console.log("ä".localeCompare("z", "sv")); // положительное значение: в шведском буква ä следует после буквы z

Использование параметра options

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

js
// В немецком буква a является базовой для буквы ä
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0

// В шведском буквы ä и a являются двумя разными базовыми буквами
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // положительное значение

Сортировка чисел

js
// По умолчанию, "2" > "10"
console.log("2".localeCompare("10")); // 1

// Сортировка чисел с использованием настроек:
console.log("2".localeCompare("10", undefined, { numeric: true })); // -1

// Сортировка чисел с использованием языковых меток:
console.log("2".localeCompare("10", "en-u-kn-true")); // -1

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

Specification
ECMAScript Language Specification
# sec-string.prototype.localecompare
ECMAScript Internationalization API Specification
# sup-String.prototype.localeCompare

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

BCD tables only load in the browser

Смотрите также