Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Grupos de captura com nome em RegExp e substituições no texto de substituição

Acede ao texto capturado pelo nome do grupo e reutiliza-o numa cadeia ou função de substituição, mesmo quando um grupo é opcional.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

/(?<name>pattern)/
/(?<name>pattern)\k<name>/
regexp.exec(text)?.groups?.name
text.replace(regexp, "$<name>")
text.replace(regexp, replacer)
text.replaceAll(globalRegexp, replacement)
Replacement string tokens: $$, $&, $`, $', $1 … $99, $<name>

(?<name>...) captura o texto que corresponde a um subpadrão. Os grupos com e sem nome são numerados em conjunto a partir de 1, pela ordem dos parênteses de abertura; (?:...) não captura. Após um exec() bem-sucedido, podes ler o valor com result.groups.name; se o grupo não participou na correspondência, o valor é undefined. No padrão, \k<name> é uma referência retroativa que procura uma correspondência com o texto capturado, em vez de o inserir no resultado da substituição.

Numa cadeia de substituição, $<name> insere uma captura com nome, $1 a primeira captura, $& a correspondência completa e $$ um cifrão. $` e $' inserem, respetivamente, o texto original antes e depois da correspondência. Se o padrão tiver grupos com nome, um nome desconhecido ou um grupo que não participou produz uma cadeia vazia. Sem grupos com nome, $<name> é mantido literalmente. Um grupo numerado que exista mas não tenha participado também produz uma cadeia vazia; se o grupo 12 não existir, $12 pode significar $1 seguido de um 2 literal, desde que o grupo 1 exista.

A função de substituição recebe a correspondência completa, os valores das capturas por ordem, a posição em unidades de código UTF-16, a cadeia de entrada e, só se houver grupos com nome no padrão, um objeto groups no fim. As capturas que não participaram têm o valor undefined. O resultado da função não é interpretado como um modelo de substituição: usa () => text para inserir literalmente texto que contenha $.

Com uma RegExp normal, replace() substitui apenas a primeira correspondência se não tiver g nem y, e todas as correspondências se tiver g sem y. Com y sem g, substitui no máximo uma correspondência, que tem de começar na posição indicada pelo valor atual de lastIndex. Com gy, começa na posição 0 e para assim que não houver correspondência na posição atual, sem procurar mais à frente. replaceAll() lança TypeError se a expressão regular não tiver g. Ambos os métodos devolvem uma cadeia resultante sem alterar a entrada.

Os nomes dos grupos seguem a sintaxe dos identificadores. Um nome inválido provoca um SyntaxError, tal como qualquer nome duplicado em ECMAScript 2024. ECMAScript 2025 permite nomes repetidos em ramos distintos da mesma disjunção |. Confirma o suporte no ambiente de execução de destino e usa nomes únicos para manter a compatibilidade com ECMAScript 2024.

Exemplos

const text = "AB-12 CD";
const token = /(?<code>[A-Z]{2})(?:-(?<number>\d+))?/g;

console.log(text.replace(token, "[$<code>:$<number>]"));
console.log(text.replace(token, (match, code, number, offset, input, groups) =>
  `[${groups.code}:${groups.number ?? "none"}]`
));

Resultado

[AB:12] [CD:]
[AB:12] [CD:none]

Em `CD`, o grupo `number` não participa. A cadeia de substituição deixa o campo vazio, enquanto a função insere `none`.

Lições relacionadas

  • JavaScript · Lição 25 · Intermédio · Versão: 3

Fontes