String.prototype.localeCompare()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

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

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

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

Синтаксис

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

Параметры

Параметры 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 если строки одинаковы.

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

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

Примеры

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

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

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

// "а" и "а" одинаковы, поэтому результат будет равен нулю
"а".localeCompare("а"); // 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`

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

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

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

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

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

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

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

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

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

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

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

// По умолчанию, "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

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

Intl.Collator