String.prototype.localeCompare()

Сводка

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

Новые аргументы locales и options позволяют приложениям определять язык, чей порядок сортировки оно хочет использовать и настраивать поведение этой функции. В старых реализациях, игнорирующих аргументы locales и options, используемая локаль и порядок сортировки целиком зависят от реализации.

Синтаксис

str.localeCompare(compareString[, locales[, options]])

Параметры

Проверьте раздел Совместимость с браузерами, чтобы увидеть, какие браузеры поддерживают аргументы locales и options, и Пример: проверка поддержки аргументов locales и options для определения этой возможности.

compareString
Строка, с которой сравнивается данная.
locales

Необязательный параметр. Строка с языковой меткой BCP 47, либо массив таких строк. Описание общей формы и интерпретации аргумента locales смотрите на странице, посвящённой объекту Intl. Разрешены следующие ключи расширения Unicode:

co
Варианты сортировки для конкретных локалей. Возможные значения включают в себя: "big5han", "dict", "direct", "ducet", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad" и "unihan". Значения "standard" и "search" игнорируются; они заменяются свойством usage аргумента options (смотрите ниже).
kn
Определяет, должно ли использоваться числовое сравнение, то есть, чтобы выполнялось условие "1" < "2" < "10". Возможными значениями являются "true" и "false". Эта опция может быть установлена через свойство аргумента options, либо через ключ расширения Unicode; если предоставлены оба значения, свойство аргумента options имеет приоритет.
kf
Определяет, буквы какого регистра должны идти первыми — верхнего или нижнего. Возможными значениями являются "upper", "lower" и "false" (используется значение по умолчанию из локали). Эта опция может быть установлена через свойство аргумента options, либо через ключ расширения Unicode; если предоставлены оба значения, свойство аргумента options имеет приоритет.
options

Необязательный параметр. Объект с некоторыми или всеми из следующих свойств:

localeMatcher
Используемый алгоритм сопоставления локалей. Возможными значениями являются "lookup" и "best fit"; значением по умолчанию является "best fit". Информацию по этой опции смотрите на странице, посвящённой объекту Intl.
usage
Определяет, используется ли сравнение для сортировки или для поиска совпадающих строк. Возможными значениями являются "sort" и "search"; значением по умолчанию является "sort".
sensitivity

Определяет, какие различия в строках должны приводить к ненулевому результату. Возможными значениями являются:

  • "base": считаются различными только строки, отличающиеся базовыми буквами. Примеры: a ≠ b, a = á, a = A.
  • "accent": считаются различными только строки, отличающиеся базовыми буквами или акцентами и другими диакритическими знаками. Примеры: a ≠ b, a ≠ á, a = A.
  • "case": считаются различными только строки, отличающиеся базовыми буквами или регистром букв. Примеры: a ≠ b, a = á, a ≠ A.
  • "variant": считаются различными строки, отличающиеся базовыми буквами, акцентами и другими диакритическими знаками или регистром букв. Также во внимание могут приниматься и другие различия. Примеры: a ≠ b, a ≠ á, a ≠ A.

Значением по умолчанию является "variant" при использовании свойства usage, равного "sort", и зависит от локали при использовании свойства usage, равного "search".

ignore­Punctua­tion
Определяет, должна ли игнорироваться пунктуация. Возможными значениями являются true и false; значением по умолчанию является false.
numeric
Определяет, должно ли использоваться числовое сравнение, то есть, чтобы выполнялось условие "1" < "2" < "10". Возможными значениями являются true и false; значением по умолчанию является false. Эта опция может быть установлена через свойство аргумента options, либо через ключ расширения Unicode; если предоставлены оба значения, свойство аргумента options имеет приоритет. Реализации не обязаны поддерживать это свойство.
caseFirst
Определяет, буквы какого регистра должны идти первыми — верхнего или нижнего. Возможными значениями являются "upper", "lower" и "false" (используется значение по умолчанию из локали); значением по умолчанию является "false". Эта опция может быть установлена через свойство аргумента options, либо через ключ расширения Unicode; если предоставлены оба значения, свойство аргумента options имеет приоритет. Реализации не обязаны поддерживать это свойство.

Описание

Возвращает число, указывающее, должна данная строка находится до, после или в том же самом месте, что и строка, переданная через параметр, при сортировке этих строк. Если данная строка предшествует строке compareString, возвращает отрицательное число, если она следует за строкой compareString, возвращает положительное значение и возвращает 0, если строки находятся на одном уровне.

Примеры

Пример: использование метода localeCompare()

Следующий пример демонстрирует различные потенциальные результаты для строки, находящейся до, после или на том же самом уровне, что и другая строка:

console.log(new Intl.Collator().compare('a', 'c')); // -2, -1 или другое отрицательное значение
console.log(new Intl.Collator().compare('c', 'a')); // 2, 1 или другое положительное значение
console.log(new Intl.Collator().compare('a', 'a')); // 0

Обратите внимание, что результат, показанный в коде выше, может сильно различаться в зависимости от браузера и его версии. Происходит это потому, что возвращаемые значения зависят от реализации. То есть, спецификация требует только того, чтобы значение было отрицательным, если строка данная следует до переданной, и положительным — если после.

Пример: проверка поддержки аргументов locales и options

Аргументы locales и options поддерживаются ещё не всеми браузерами. Для проверки того, поддерживает ли их уже реализация, можно затребовать несуществующую метку языка и проверить, будет ли выброшено исключение RangeError:

function localeCompareSupportsLocales() {
  try {
    'a'.localeCompare​('b', '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' })); // положительное значение

Производительность

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

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

Спецификация Статус Комментарии
ECMAScript 3-е издание. Стандарт Изначальное определение. Реализована в JavaScript 1.2.
ECMAScript 5.1 (ECMA-262)
Определение 'String.prototype.localeCompare' в этой спецификации.
Стандарт  
ECMAScript 2015 (6th Edition, ECMA-262)
Определение 'String.prototype.localeCompare' в этой спецификации.
Стандарт  
ECMAScript Internationalization API 1.0 (ECMA-402)
Определение 'String.prototype.localeCompare' в этой спецификации.
Стандарт Определение параметров locale и option.

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

Возможность Chrome Firefox (Gecko) Internet Explorer Opera Safari
Базовая поддержка (Да) (Да) (Да) (Да) (Да)
Аргументы locales и options 24 29 (29) 11 15 Нет
Возможность Android Chrome для Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Базовая поддержка (Да) (Да) (Да) (Да) (Да) (Да)
Аргументы locales и options Нет 26 Нет
баг 864843
Нет Нет Нет

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

Метки документа и участники

 Внесли вклад в эту страницу: ovvn, Mingun
 Обновлялась последний раз: ovvn,