Por que cifrões mudam o texto de substituição em JavaScript
Uma ferramenta de localizar e substituir altera o próprio texto de substituição. Mesmo com uma busca por string simples, o JavaScript interpreta sequências com cifrão no argumento de substituição. Se o usuário quer texto literal, retorne esse texto por uma função.
Identifique os modelos de substituição antes de mudar a entrada
Imagine substituir um marcador por uma explicação de preço que contém $&. O usuário espera esses dois caracteres, mas o marcador antigo reaparece. Isso não é necessariamente um problema de codificação. O argumento de substituição tem sua própria pequena linguagem de modelos, mesmo quando a busca é uma string simples, não uma expressão regular.
Comece com uma cópia do texto e uma correspondência. Se uma sequência com cifrão mudar, troque o argumento de substituição por um callback e compare os resultados. Mantenha a busca igual nessa comparação. Mudar as duas entradas ao mesmo tempo dificulta identificar a regra responsável pela surpresa.
Um relato público de 2012 substituiu uma string inteira por $' e obteve um resultado vazio. Esse token significa o sufixo depois da correspondência. Como a correspondência consumiu tudo, não havia sufixo.
const input = "as";
const replacement = "$'";
input.replace("as", replacement); // ""
input.replace("as", () => replacement); // "$'"
O teste preservado com Node.js v24.19.0 reproduziu os dois resultados. Outros tokens de substituição incluem $$ para um cifrão, $& para a correspondência e referências de captura como $1 quando o padrão contém o grupo correspondente. Existem também formas de prefixo e captura nomeada. Nem todo cifrão isolado é especial.
Use um callback quando o usuário quiser texto literal
const draft = "Price: TOKEN. Repeat: TOKEN.";
const typedReplacement = "$& costs $$";
console.log(draft.replaceAll("TOKEN", typedReplacement));
// Price: TOKEN costs $. Repeat: TOKEN costs $.
console.log(draft.replaceAll("TOKEN", () => typedReplacement));
// Price: $& costs $$. Repeat: $& costs $$.
Na primeira chamada, a string de substituição é interpretada. Na segunda, a função retorna o valor literal do usuário para cada correspondência. Esse valor é inserido sem uma nova interpretação como modelo de substituição. Isso é útil em ferramentas que prometem localizar e substituir de forma comum: o usuário não deveria precisar aprender escapes de cifrão só para colar texto.
Não resolva isso criando automaticamente uma expressão regular a partir da busca do usuário. Uma busca como a.b normalmente deve localizar um ponto literal no modo literal, não qualquer caractere. Se você também oferece capturas regex e modelos de substituição, mantenha um modo avançado separado e claramente identificado. Um modelo como $1 é útil nesse modo e não deve se tornar literal de repente, sem explicação.
function replaceLiteralOnce(text, search, value) {
return text.replace(search, () => value);
}
function replaceLiteralAll(text, search, value) {
if (search === "") throw new Error("Search must not be empty");
return text.replaceAll(search, () => value);
}
Estas funções esperam strings fornecidas pelo aplicativo. Uma substitui a primeira ocorrência; a outra, todas as correspondências. Somente replaceLiteralAll rejeita uma busca vazia para evitar inserções entre unidades de código. Com uma busca vazia, replaceLiteralOnce insere o texto de substituição no início da string. Se o produto oferece modelos de captura intencionalmente, preserve esse modo e identifique-o claramente em vez de mudar seu significado silenciosamente.
Confira a edição completa no contexto final
Mostre o texto original e o alterado, especialmente em Substituir tudo. Teste substituições com um cifrão isolado, dois cifrões, um token de correspondência e uma string vazia. Confira o que acontece quando não há correspondência. Uma substituição vazia é uma exclusão legítima; uma busca vazia exige uma decisão explícita de produto, pois pode inserir texto entre posições em toda a string.
Por fim, confira como o resultado é exibido. Retornar texto literal de um callback de substituição não torna HTML seguro. A prévia deve usar um textarea ou textContent para texto não confiável, de modo que uma tag colada seja exibida, não executada. Salve ou envie somente quando a prévia corresponder à intenção do usuário e mantenha uma forma de desfazer edições em massa.
As amostras registradas preservaram $&, $', $$ e $1 exatamente quando retornados pelo callback. Acrescente exemplos semelhantes aos seus testes de regressão, incluindo correspondências repetidas e substituição vazia. Preserve a origem; confira as edições em massa antes de aplicá-las.
