Pular para o conteúdo
FrAIFlow

Soluções / Texto & Código

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.

Um valor, duas interpretações
Explicação criada pelos autores com base no exemplo preservado; não é uma captura de aplicativo.

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.

Mantenha os dois modos explícitos
Explicação criada pelos autores com base no exemplo preservado; não é uma captura de aplicativo.

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.

A substituição por string interpreta tokens com cifrão; o callback preserva exatamente o texto digitado com cifrões.
Explicação autoral de antes e depois do exemplo sintético exato de Node.js acima. Não é uma captura de editor de texto. Abra a imagem para ver os detalhes em tamanho original.
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.

Substituição medida: o argumento string produz saída vazia; a função retorna o cifrão e o apóstrofo literais.
Explicação original preservada.
Saída registrada do teste sintético sobre cifrões no texto de substituição em JavaScript
Saída registrada de substituição de strings no Node.js com texto literal contendo cifrões. É uma captura da saída de teste registrada, não do aplicativo do autor do relato. Abrir a imagem de evidência em tamanho original.

Fontes e leituras relacionadas