MDN will be in maintenance mode on Wednesday September 20th, starting at 10 AM Pacific / 5 PM UTC, for about 1 hour.

Метод localeCompare() вертає число, що вказує, як має розташуватись рядок відносно вказаного (того, що передано як параметр) у відсортованій за зростанням послідовності: перед, після, чи вони однакові.

Нові арґументи locales та options дають можливість вказати мову, абетковий порядок сортування якої має бути застосовано, та налаштувати механізм порівняння рядків. Раніше, коли цих арґументів ще не було, механізм порівняння рядків та порядок їх сортування цілковито залежав від реалізації.

Синтаксис

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

Параметри

Перевіряйте в таблиці сумісності наявність підтримки арґументів locales та options, а також подивіться на код для перевірки наявності такої підтримки.

compareString
Рядок, з яким буде здійснено порівняння.
locales

Optional. A string with a BCP 47 language tag, or an array of such strings. For the general form and interpretation of the locales argument, see the Intl page. The following Unicode extension keys are allowed:

co
Variant collations for certain locales. Possible values include: "big5han", "dict", "direct", "ducet", "gb2312", "phonebk", "phonetic", "pinyin", "reformed", "searchjl", "stroke", "trad", "unihan". The "standard" and "search" values are ignored; they are replaced by the options property usage (see below).
kn
Whether numeric collation should be used, such that "1" < "2" < "10". Possible values are "true" and "false". This option can be set through an options property or through a Unicode extension key; if both are provided, the options property takes precedence.
kf
Whether upper case or lower case should sort first. Possible values are "upper", "lower", or "false" (use the locale's default). This option can be set through an options property or through a Unicode extension key; if both are provided, the options property takes precedence.
options

Optional. An object with some or all of the following properties:

localeMatcher
The locale matching algorithm to use. Possible values are "lookup" and "best fit"; the default is "best fit". For information about this option, see the Intl page.
usage
Whether the comparison is for sorting or for searching for matching strings. Possible values are "sort" and "search"; the default is "sort".
sensitivity

Which differences in the strings should lead to non-zero result values. Possible values are:

  • "base": Only strings that differ in base letters compare as unequal. Examples: a ≠ b, a = á, a = A.
  • "accent": Only strings that differ in base letters or accents and other diacritic marks compare as unequal. Examples: a ≠ b, a ≠ á, a = A.
  • "case": Only strings that differ in base letters or case compare as unequal. Examples: a ≠ b, a = á, a ≠ A.
  • "variant": Strings that differ in base letters, accents and other diacritic marks, or case compare as unequal. Other differences may also be taken into consideration. Examples: a ≠ b, a ≠ á, a ≠ A.

The default is "variant" for usage "sort"; it's locale dependent for usage "search".

ignorePunctuation
Whether punctuation should be ignored. Possible values are true and false; the default is false.
numeric
Whether numeric collation should be used, such that "1" < "2" < "10". Possible values are true and false; the default is false. This option can be set through an options property or through a Unicode extension key; if both are provided, the options property takes precedence. Implementations are not required to support this property.
caseFirst
Whether upper case or lower case should sort first. Possible values are "upper", "lower", or "false" (use the locale's default); the default is "false". This option can be set through an options property or through a Unicode extension key; if both are provided, the options property takes precedence. Implementations are not required to support this property.

Вертає

  • Від'ємне число, якщо рядок має розташуватись перед compareString;
  • Додатне число, якщо рядок має розташуватись після compareString;
  • Нуль, якщо рядки тотожні.

Опис

Метод призначено для лексикографічного порівняння рядків, тобто для встановлення їх належного порядку у відсортованій за абеткою послідовності рядків. Якщо метод повертає від'ємне значення, рядок referenceStr, для якого було здійснено виклик методу, слід розташувати перед compareString, що його було передано як параметр. Якщо метод повертає додатне значення, порядок зворотний — referenceStr має йти після compareString. Якщо метод повертає нуль, то рядки є тотожними.

// виводить 0
console.log('абв'.localeCompare('абв'));

// виводить від'ємне число
console.log('абвг'.localeCompare('абвґ'));

// виводить додатне число
console.log('абг'.localeCompare('абв'));

Зауважте, що слід послуговуватися саме поняттями додатний та від'ємний та відповідними порівняннями, як це зазначає специфікація W3C. На значення -1 та 1 покладатися не можна, бо кожна реалізація може відрізнятися. Наприклад, деякі переглядачі повертають -2 та 2 або інші числа.

Приклади

Використання localeCompare()

// Вертає від'ємне значення, позаяк літера «a» розташована раніше за «b»
'a'.localeCompare('c');  // -2 чи -1 (або інше від'ємне значення)

// Вертає додатне значення, позаяк за абеткою слово "check" слід розташувати після "against"
'check'.localeCompare('against');  // 2 чи 1 (або інше додатне значення)

// Вертає нуль, позаяк рядки однакові
'a'.localeCompare('a');  // 0

Сортування масиву

Метод localeCompare() надає можливість регістронезалежного сортування масивів:

var unsorted = ['update', 'Link', 'Add, 'feature', 'improve', 'Report'];

// вертає ["Add", "feature", "improve", "Link", "Report", "update"]
unsorted.sort((a, b) => a.localeCompare(b));

Перевірка наявності підтримки додаткових арґументів

Арґументи locales та options досі не підтримуються всіма переглядачами. Тож з метою з'ясування наявності підтримки, можна скористатися тим, що метод викидає (лише за наявності такої підтримки згаданих арґументів) виняток RangeError, якщо параметр locales не вказує належного мовного коду. Наприклад, вкажемо напевне відсутній код "i":

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

Використання locales

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

// виводить від'ємне значення (у німецькій абетці літера «ä» розташована раніше «z»)
console.log('ä'.localeCompare('z', 'de'));

// виводить додатне значення (у шведській абетці літера «ä» розташована пізніше «z»)
console.log('ä'.localeCompare('z', 'sv'));

Використання options

Арґумент options надає можливість додаткового налаштування способу порівняння рядків методом localeCompare():

// Вжиток наголосу звичайно впливає на сортування рядків
// виводить 1
console.log('за́сновок'.localeCompare('засновок', 'uk'));

// Проте опція sensitivity дозволяє це змінити
// виводить 0
console.log('за́сновок'.localeCompare('засновок', 'uk', {sensitivity: 'base'}));

// У німецькій мові літера «ä» є похідною від «a»
// виводить 0
console.log('ä'.localeCompare('a', 'de', {sensitivity: 'base'}));

// У шведській мові «ä» та «a» є окремими первісними літерами
// виводить додатне значення
console.log('ä'.localeCompare('a', 'sv', {sensitivity: 'base'}));

Швидкодія

З огляду на швидкодію, для порівняння величезної кількості рядків (наприклад, під час сортування великих масивів) ліпше створювати об'єкт Intl.Collator та використовувати функцію, надану його властивістю compare:

function sortLargeStringArray(array, locale) {
  var collator = new Intl.Collator(locale);
  array.sort(collator.compare);
}

// sortLargeStringArray([ … ], 'uk');

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

Специфікація Статус Коментар
ECMAScript 3rd Edition (ECMA-262) Standard Первинне визначення. Реалізовано у JavaScript 1.2.
ECMAScript 5.1 (ECMA-262)
The definition of 'String.prototype.localeCompare' in that specification.
Standard  
ECMAScript 2015 (6th Edition, ECMA-262)
The definition of 'String.prototype.localeCompare' in that specification.
Standard  
ECMAScript Latest Draft (ECMA-262)
The definition of 'String.prototype.localeCompare' in that specification.
Living Standard  
ECMAScript Internationalization API 1.0 (ECMA-402)
The definition of 'String.prototype.localeCompare' in that specification.
Standard Визначення параметрів locale та option.
ECMAScript Internationalization API 2.0 (ECMA-402)
The definition of 'String.prototype.localeCompare' in that specification.
Standard  
ECMAScript Internationalization API 4.0 (ECMA-402)
The definition of 'String.prototype.localeCompare' in that specification.
Draft  

Підтримка веб-переглядачами

FeatureChromeEdgeFirefoxInternet ExplorerOperaSafari
Basic Support (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)
locales24 (Yes)29111510
options24 (Yes)29111510
FeatureAndroidChrome for AndroidEdge mobileFirefox for AndroidIE mobileOpera AndroidiOS Safari
Basic Support (Yes) (Yes) (Yes) (Yes) (Yes) (Yes) (Yes)
locales No26 ? No No No10
options No26 ? No No No10

Див. також

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

 Зробили внесок у цю сторінку: asmforce
 Востаннє оновлена: asmforce,