String.prototype.replaceAll()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since August 2020.

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.

Experimente

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()

js
"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:

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

Já o código abaixo vai funcionar:

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

Especificações

Specification
ECMAScript Language Specification
# sec-string.prototype.replaceall

Compatibilidade com navegadores

BCD tables only load in the browser

Veja também