CKTIS / JavaScript
String.prototype.replace — substituir texto
replace() devolve um texto com as correspondências substituídas, sem alterar o original. Aprende a diferença entre pesquisar com cadeias de caracteres e expressões regulares, e entre modelos de substituição e funções de substituição.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
text.replace(searchValue, replaceValue)String.prototype.replace devolve uma nova cadeia de caracteres quando é usado com uma cadeia simples ou um RegExp padrão; o original mantém-se inalterado. Se não houver correspondências, o conteúdo é devolvido sem alterações. É uma API da linguagem ECMAScript, não uma API do navegador.
Um searchValue do tipo cadeia de caracteres é interpretado literalmente e substitui apenas a primeira ocorrência; uma cadeia vazia corresponde ao início. Um RegExp padrão sem g substitui, no máximo, uma correspondência; com g, substitui todas as correspondências encontradas. Um objeto com um método [Symbol.replace] pode definir um comportamento personalizado, incluindo o resultado.
Um replaceValue do tipo cadeia de caracteres interpreta $$ como $, $& como a correspondência completa e $1 como o primeiro grupo de captura existente. Uma função de substituição recebe a correspondência, depois os grupos capturados, o índice e a cadeia de entrada; se houver grupos com nome, é acrescentado no fim um objeto groups. O índice conta unidades de código UTF-16. O resultado da função é convertido numa cadeia de caracteres, mas as sequências $ não são interpretadas.
O exemplo compara a substituição da primeira correspondência, a substituição global, uma referência a um grupo de captura e o resultado literal de uma função. Apresentar text também permite confirmar que o original não se altera.
Exemplos
const text = "cat cat";
console.log(text.replace("cat", "dog"));
console.log(text.replace(/cat/g, "dog"));
console.log(text.replace(/(cat)/g, "[$1]"));
console.log(text.replace(/cat/g, () => "$&"));
console.log(text);Resultado
dog cat dog dog [cat] [cat] $& $& cat cat
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.