String.prototype.localeCompare()

O método localeCompare() retorna um número que indica se uma string de referência vem antes ou depois, ou é a mesma que a string fornecida na ordem de classificação.

Os novos argumentos locales e options permitem que os aplicativos especifiquem o idioma cuja ordem da ordenação deve ser usada e personalizem o comportamento da função. Em implementações mais antigas, que ignoram os argumentos locales e options, a localidade e a ordem de classificação usadas são totalmente dependentes da implementação.

Sintaxe

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

Parâmetros

compareString
A string com a qual a referenceStr é comparada.
locales e options

Esses argumentos personalizam o comportamento da função e permitem que os aplicativos especifiquem o idioma cujas convenções de formatação devem ser usadas. Em implementações que ignoram os argumentos locales e options, a localidade usada e a forma da string retornada são inteiramente dependentes da implementação.

Consulte o construtor Intl.Collator() para obter detalhes sobre esses parâmetros e como usá-los.

Valor retornado

Um número negativo se referenceStr ocorrer antes de compareString. Um número positivo se o referenceStr ocorrer após compareString. 0 se eles forem equivalentes.

Descrição

Retorna um inteiro indicando se referenceStr vem antes, depois ou é equivalente a compareString.

  • Negativo quando o referenceStr ocorre antes de compareString
  • Positivo quando o referenceStr ocorre após compareString
  • Retorna 0 se eles forem equivalentes

NÃO confie em valores de retorno exatos de -1 ou 1!

Os resultados de números inteiros negativos e positivos variam entre os navegadores (bem como entre as versões dos navegadores) porque a especificação W3C exige apenas valores negativos e positivos. Alguns navegadores podem retornar -2 ou 2, ou mesmo algum outro valor negativo ou positivo.

Performance

Ao comparar um grande número de strings, como na classificação de grandes arrays, é melhor criar um objeto Intl.Collator e usar a função fornecida por sua propriedade compare.

Exemplos

Usando localeCompare()

// A letra "a" está antes de "c" produzindo um valor negativo
'a'.localeCompare('c'); // -2 ou -1 (ou algum outro valor negativo)

// Alfabeticamente, a palavra "verificar" vem depois de "contra", produzindo um valor positivo
'verificar'.localeCompare('contra'); // 2 ou 1 (ou algum outro valor negativo)

// "a" e "a" são equivalentes, resultando em um valor neutro de zero
'a'.localeCompare('a'); // 0

Ordenar um array

localeCompare() permite a ordenação sem distinção entre maiúsculas e minúsculas em um array.

let 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é']

Verifique o suporte do navegador para os novos argumentos

Os argumentos locales e options ainda não são suportados em todos os navegadores.

Para verificar se uma implementação os suporta, use o argumento "i" (um requisito de rejeição das tags de linguagem ilegal) e procure uma exceção RangeError:

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

Usando locales

Os resultados fornecidos por localeCompare() variam entre os idiomas. Para obter a ordem de classificação do idioma usado na interface do usuário de seu aplicativo, certifique-se de especificar esse idioma (e possivelmente alguns idiomas substitutos) usando o argumento locales:

console.log('ä'.localeCompare('z', 'de')); // um valor negativo: em alemão, ä é classificado antes de z
console.log('ä'.localeCompare('z', 'sv')); // um valor positivo: em sueco, ä é classificado após z

Usando options

Os resultados fornecidos por localeCompare() podem ser personalizados usando o argumento options:

// em alemão, ä tem a como letra base
console.log('ä'.localeCompare('a', 'de', { sensitivity: 'base' })); // 0

// em sueco, ä e a são letras de base separadas
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // um valor positivo

Ordenação numérica

// por padrão, "2" > "10"
console.log("2".localeCompare("10")); // 1

// numeric using options:
console.log("2".localeCompare("10", undefined, {numeric: true})); // -1

// numeric using locales tag:
console.log("2".localeCompare("10", "en-u-kn-true")); // -1

Especificações

Especificação
ECMAScript (ECMA-262)
The definition of 'String.prototype.localeCompare' in that specification.
ECMAScript Internationalization API (ECMA-402)
The definition of 'String.prototype.localeCompare' in that specification.

Compatibilidade de navegador

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
localeCompareChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 5.5Opera Full support 7Safari Full support 3WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support 10.1Safari iOS Full support 1Samsung Internet Android Full support 1.0nodejs Full support 0.1.100
localesChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android No support NoOpera Android No support NoSafari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support 13.0.0
Full support 13.0.0
Partial support 0.12
Notes
Notes Before version 13.0.0, only the locale data for en-US is available by default. When other locales are specified, the function silently falls back to en-US. To make full ICU (locale) data available for versions prior to 13, see Node.js documentation on the --with-intl option and how to provide the data.
optionsChrome Full support 24Edge Full support 12Firefox Full support 29IE Full support 11Opera Full support 15Safari Full support 10WebView Android No support NoChrome Android Full support 26Firefox Android No support NoOpera Android No support NoSafari iOS Full support 10Samsung Internet Android Full support 1.5nodejs Full support 0.12

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Veja também