String.prototype.replaceAll()

Nota: A partir de Agosto de 2020, o método replaceAll() continuará sendo suportado pelo Firefox, mas não pelo Chrome. Ele estará disponível somente no Chrome 85.

O método replaceAll() retorna uma nova string com todas as ocorrências de um padrão substituídas por uma substituição. O padrão pode ser uma string ou uma RegExp, e a substituição pode ser uma string ou uma função a ser chamada para cada ocorrência.

A string original é mantida sem modificação.

Sintaxe

const newStr = str.replaceAll(regexp|substr, newSubstr|function)

Nota: quando usar uma `regexp`, você deve colocar o sinalizador (flag) global "g". Do contrário, será retornado um TypeError: "replaceAll must be called with a global RegExp".

Parâmetros

regexp (padrão)
Uma RegExp ou literal com o sinalizador (flag) global. As ocorrências serão substituídas por newSubstr ou pelo valor retornado da function (função) especificada.
substr (padrão)
Uma String que deve ser substituída por newSubstr. É tratada como uma string literal e não é interpretada como uma expressão regular (RegExp).
newSubstr (substituição)
É a String que substitui a substring especificada pelo parâmetro regexp ou substr. Um número de padrões especiais para substituição são suportados; veja a seção "Especificando uma string como parâmetro" abaixo.
function (substituição)
Uma função a ser chamada retornando a nova substring a ser usada para substituir as correspondências para a dada regexp ou substr. Os argumentos passados para esta função são descritos na seção "Especificando uma função como parâmetro" abaixo.

Valor de retorno

Um nova string, com todas as ocorrências de um padrão substituído por uma substituição.

Descrição

Este método não muda o objeto String original. Ele simplesmente retorna uma nova string.

Especificando uma string como parâmetro

A string de substituição pode incluir os seguimentos padrões especiais de substituição:

Padrão Insere
$$ Insere um "$".
$& Insere a substring correspondente.
$` Insere a porção da string que precede a substring correspondente.
$' Insere a porção da string que sucede a substring correspondente.
$n Onde n é um inteiro positivo menor que 100, insere a n-ésima string submatch entre parênteses, desde que o primeiro argumento seja um objeto RegExp. Note que isso é indexado começando pelo 1.

Especificando uma função como parâmetro

Você pode especificar uma função como segundo parâmetro. Neste caso, a função será chamada depois da ocorrência ter sido encontrada. O resultado da função (valor de retorno) será usado como uma string para substituição. (Nota: Os padrões especiais mencionados acima não se aplicam neste caso.)

Note que a função será chamada múltiplas vezes para cada ocorrência a ser substituída se a expressão regular no primeiro parâmetro for global "g".

Os argumentos para funções são os seguintes:

Nome possível Valor fornecido
match A substring correspondida. (Corresponde ao $& acima.)
p1, p2, ... A n-ésima string encontrada por um grupo de captura entre parênteses, desde que o primeiro argumento para replace() seja uma RegExp. (Corresponde a $1, $2, etc. acima.) Por exemplo, se /(\a+)(\b+)/, foi dado, p1 é a correspondência para \a+, e p2 para \b+.
offset O deslocamento da substring correspondente em toda a string sendo examinada. (Por exemplo, se toda a string for 'abcd' e a substring correspondente for 'bc', este argumento será 1.)
string A string inteira será examinada.

(O número exato de argumentos depende se o primeiro argumento é um objeto RegExp — e, se então, quantas subcorrespondências entre parênteses são especificadas.)

Exemplos

Usando replaceAll()

'aabbcc'.replaceAll('b', '.'); 
// 'aa..cc'

RegExp sem flag "g" retorando erro

Ao usar uma expressão regular para realizar uma pesquisa, a mesma deve conter a flag global "g". O código abaixo não irá funcionar:

'aabbcc'.replaceAll(/b/, '.');
TypeError: replaceAll must be called with a global RegExp

Já o código abaixo vai funcionar:

'aabbcc'.replaceAll(/b/g, '.');
"aa..cc"

Especificações

Especificação
ECMAScript (ECMA-262)
The definition of 'String.prototype.replaceAll' in that specification.
Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
replaceAllChrome Full support 85Edge Full support 85Firefox Full support 77IE No support NoOpera Full support 71Safari Full support 13.1WebView Android Full support 85Chrome Android Full support 85Firefox Android Full support 79Opera Android Full support 60Safari iOS Full support 13.4Samsung Internet Android No support Nonodejs No support No

Legend

Full support  
Full support
No support  
No support

Veja também