String.prototype.localeCompare()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.
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.
Experimente
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
eoptions
, 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 decompareString
- Positivo quando o
referenceStr
ocorre apóscompareString
- Retorna
0
se eles forem equivalentes
Aviso: 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 positivo)
// "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
Specification |
---|
ECMAScript Language Specification # sec-string.prototype.localecompare |
ECMAScript Internationalization API Specification # sup-String.prototype.localeCompare |
Compatibilidade com navegadores
BCD tables only load in the browser