String.prototype.localeCompare()

Определение и применение

localeCompare() сравнивает две строки по правилам языка. Это помогает упорядочить названия для читателя: операторы сравнения сравнивают строки по кодовым единицам, что не всегда соответствует алфавиту.

Поддержка браузерами

Спецификации: ecma262, ecma402

Поддерживается во всех основных браузерах с 2015 года.

Отдельные значения (2) поддерживаются не везде — смотрите таблицу.

Показать браузеры
Совместимостьjavascript.builtins.String.localeCompare
ВозможностьКомпьютерыМобильные
ChromeEdgeFirefoxOperaSafariChrome AndroidFirefox for AndroidOpera AndroidSafari on iOSSamsung BrowserWebView AndroidWebView on iOS
localeCompare✓1✓12✓1✓7✓3✓18✓4✓10.1✓1✓1.0✓4.4✓1
locales parameter✓24✓12✓29✓15✓10✓26✓56×✓10✓1.5×✓10
options parameter✓24✓12✓29✓15✓10✓26✓56×✓10✓1.5×✓10

поддерживаетсяс ограниченияминет поддержкинет данных≤31 — не позднее версии 31

Синтаксис

JavaScript
text.localeCompare(other);
text.localeCompare(other, locales);
text.localeCompare(other, locales, options);

text — исходная строка, other — строка для сравнения. Другой тип аргумента преобразуется в строку, поэтому пропущенное значение будет сравнением со строкой "undefined". Исходные строки не изменяются.

Параметры localeCompare()
Параметр Назначение
other Сравниваемый текст.
locales Языковая метка, например "ru", либо список предпочтений. Без неё используется язык среды.
options Настройки сравнения. sensitivity: "base" сравнивает базовые буквы с учётом выбранного языка; numeric: true учитывает числовые части; caseFirst задаёт порядок регистра.

Проверяйте знак результата

Отрицательное число означает, что text идёт раньше other; положительное — позже; ноль — равенство по выбранным правилам. Не проверяйте результат на точные -1 и 1: важен знак. Для порядка по русскому алфавиту явно передавайте "ru".

Результат 0 не заменяет ===: настройки могут считать равными разные по регистру или оформлению строки. Например, поиск названия без учёта регистра и проверка точного пароля требуют разных сравнений.

Сортировка названий

Метод array.sort() принимает функцию сравнения: её результатом может быть a.localeCompare(b, "ru"). Сам sort() меняет массив, хотя localeCompare() строки не меняет. В примере ниже перед сортировкой создаётся копия через [...names].

Исключения

Исключения localeCompare()
Тип исключения Условие
RangeError Некорректная языковая метка или недопустимое значение настройки сравнения.
TypeError Вызов с null или undefined в качестве исходной строки; недопустимый тип отдельных параметров.

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

ECMA-402: String.prototype.localeCompare.

Примеры, попробуйте сами

Русские названия в алфавитном порядке

Добавьте название в names. Сравните отсортированную копию с исходным массивом: его порядок сохраняется.

index.html
HTML
<!doctype html>
<html lang="ru">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Русские названия в алфавитном порядке</title>
  </head>
  <body>
    <p>Откройте консоль браузера, чтобы увидеть результат.</p>
    <script src="main.js"></script>
  </body>
</html>
main.js
JavaScript
const names = ['Яблоко', 'Банан', 'Абрикос']
const sorted = [...names].sort((a, b) => a.localeCompare(b, 'ru'))
console.log(sorted.join(', '))
console.log(names.join(', '))

Регистр и числа внутри текста

Измените номера товаров и настройку numeric. Проверки используют знак, а не конкретное число, возвращённое сравнением.

index.html
HTML
<!doctype html>
<html lang="ru">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Регистр и числа внутри текста</title>
  </head>
  <body>
    <p>Откройте консоль браузера, чтобы увидеть результат.</p>
    <script src="main.js"></script>
  </body>
</html>
main.js
JavaScript
console.log('Чай'.localeCompare('чай', 'ru', { sensitivity: 'base' }) === 0)
console.log('Чай' === 'чай')
console.log('товар 2'.localeCompare('товар 10', 'ru', { numeric: true }) < 0)
console.log('товар 2'.localeCompare('товар 10', 'ru', { numeric: false }) > 0)