String.prototype.localeCompare()

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

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Параметры 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()

// Буква "а" идёт перед "в", поэтому результат будет отрицательным
"а".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

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

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

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

• Intl.Collator