Localizar e Substituir

Aspose.Words FOSS for .NET fornece localizar e substituir baseado em expressões regulares através de Range.Replace(), configurável via FindReplaceOptions e, para cenários avançados, uma implementação personalizada de IReplacingCallback do namespace Aspose.Words.Replacing.

Localizar e Substituir Básico

Range.Replace(pattern, replacement) executa uma busca e substituição baseada em expressões regulares ao longo do intervalo — todo o documento, quando chamado em Document.Range. A sobrecarga Replace(pattern, replacement, options) aceita um objeto FindReplaceOptions para controle mais fino: MatchCase e FindWholeWordsOnly ajustam o comportamento da correspondência, Direction (um valor FindReplaceDirection, Forward ou Backward) controla a direção da busca, e ApplyFont / ApplyParagraphFormat permitem que a substituição carregue nova formatação em vez de apenas texto novo.

Opções Sensíveis à Formatação e Estruturais

FindReplaceOptions inclui várias flags que determinam quais construções do documento uma correspondência pode atravessar ou ignorar: IgnoreDeleted e IgnoreInserted controlam se o conteúdo de alterações rastreadas participa da correspondência, IgnoreFields e IgnoreFieldCodes controlam se o texto de resultado de campo e os códigos de campo são pesquisados, IgnoreFootnotes exclui conteúdo de nota de rodapé/final, e IgnoreStructuredDocumentTags e IgnoreShapes excluem, respectivamente, controles de conteúdo e texto de forma. UseSubstitutions habilita a sintaxe de substituição de expressão regular (como $1) na string de substituição. LegacyMode e UseLegacyOrder preservam o comportamento de correspondência mais antigo para compatibilidade com documentos processados por lógica anterior.

Lógica de Substituição Personalizada com IReplacingCallback

Para lógica de substituição que não pode ser expressa como uma string de substituição fixa, implemente IReplacingCallback e seu único método Replacing(args), então atribua a implementação a FindReplaceOptions.ReplacingCallback (ou passe-a diretamente ao construtor FindReplaceOptions(replacingCallback)). O callback recebe um objeto ReplacingArgs para cada correspondência, expondo Match (a correspondência de expressão regular subjacente), MatchNode / MatchEndNode (os nós do documento que contêm a correspondência), MatchOffset, e uma string Replacement configurável. Retornar um valor ReplaceAction do callback — Replace, Skip ou Stop — controla se aquela correspondência específica será substituída, deixada como está ou interromperá toda a operação de localizar/substituir.

Dicas e Melhores Práticas

Chame Replace() em Document.Range para substituição em todo o documento, ou em um Range mais restrito (como o intervalo de uma única seção) para delimitar a operação.
Defina FindWholeWordsOnly = true para evitar que um termo de pesquisa seja correspondido como substring de uma palavra maior.
Use IgnoreFieldCodes = true quando desejar que a substituição opere nos resultados do campo exibido, e não no texto da instrução de campo subjacente.
Prefira IReplacingCallback em vez de pós-processamento quando o texto de substituição depende do contexto da correspondência (nó circundante, formatação ou posição) em vez de ser uma string fixa.
Retorne ReplaceAction.Stop de um callback para encerrar antecipadamente uma operação de localizar/substituir assim que uma condição for atendida, em vez de processar todas as correspondências restantes.

Problemas Comuns

Problema	Causa	Correção
Substituição não aplica nova formatação	`ApplyFont`/`ApplyParagraphFormat` não definido em `FindReplaceOptions`	Defina as propriedades de formatação relevantes no objeto options
Correspondências encontradas dentro de exclusões de alterações rastreadas inesperadamente	`IgnoreDeleted` deixado em seu padrão	Defina `IgnoreDeleted = true` para ignorar o conteúdo da revisão excluída
Referências de grupos regex no texto de substituição não foram substituídas	`UseSubstitutions` não habilitado	Defina `UseSubstitutions = true` para habilitar substituição ao estilo `$1`
A substituição baseada em callback não para quando esperado	Callback retorna `Replace`/`Skip` em vez de `Stop`	Retorne `ReplaceAction.Stop` de `Replacing()` quando a operação deve terminar

FAQ

O `Range.Replace()` suporta expressões regulares?

Sim — o argumento pattern é uma expressão regular, comparado ao texto da faixa.

Como faço para substituir texto apenas dentro de uma seção específica, não em todo o documento?

Chame Replace() no Range dessa seção em vez de Document.Range.

Como faço para que o texto de substituição dependa do que foi correspondido?

Implemente IReplacingCallback, leia os detalhes da correspondência de ReplacingArgs, defina ReplacingArgs.Replacement como o texto calculado e retorne ReplaceAction.Replace.

É possível fazer a busca/substituição retroativamente no documento?

Sim — defina FindReplaceOptions.Direction como FindReplaceDirection.Backward.

API Reference Resumo

Classe / Método	Descrição
`Range.Replace()`	Localizar/substituir por expressão regular em um intervalo, com `FindReplaceOptions` opcional
`FindReplaceOptions`	Configura o comportamento de correspondência, formatação e escopo estrutural para operações de substituição
`FindReplaceDirection`	Enum: `Forward`, `Backward`
`IReplacingCallback`	Interface para lógica personalizada de substituição por correspondência
`ReplacingArgs`	Dados por correspondência passados para `IReplacingCallback.Replacing()`
`ReplaceAction`	Enum controlando o resultado por correspondência: `Replace`, `Skip`, `Stop`

Ver também

Aspose.Words for .NET — Enterprise Documentation

Localizar e Substituir