Trabalhando com Texto

Texto em um documento Word é organizado em nós Run (caracteres contíguos que compartilham a mesma formatação de fonte) agrupados dentro de nós Paragraph. Aspose.Words FOSS para .NET expõe ambos diretamente, junto com Font para formatação de caracteres, ParagraphFormat para formatação ao nível de parágrafo e Range para ler ou substituir texto em qualquer parte da árvore. Este guia cobre runs e fontes, formatação de parágrafos, leitura e substituição de texto, comentários e formatação de listas ao nível de parágrafo.

Runs e Formatação de Caracteres

Um Run representa um trecho de texto que compartilha um conjunto de formatação; sua propriedade Text contém o conteúdo em texto simples e sua propriedade Font (um objeto Font) contém a formatação ao nível de caractere — Name, Size, Bold, Italic, Underline, Color, HighlightColor, Subscript/Superscript, StrikeThrough, e muitos mais. Font.ClearFormatting() redefine a fonte de um run para os padrões. Os runs de um parágrafo estão disponíveis através da sua propriedade Runs, um RunCollection.

Parágrafos e Formatação de Parágrafos

Paragraph é um nó composto que contém os runs (e outros conteúdos inline) de um parágrafo; os parágrafos de um documento ou corpo são expostos como um ParagraphCollection (Body.Paragraphs). Paragraph.ParagraphFormat (um objeto ParagraphFormat) controla o layout ao nível de parágrafo — Alignment, recuos (LeftIndent, RightIndent, FirstLineIndent), espaçamento (SpaceBefore, SpaceAfter, LineSpacing, LineSpacingRule) e comportamento de paginação (KeepTogether, KeepWithNext, PageBreakBefore, WidowControl). ParagraphFormat.ClearFormatting() redefine esses valores para os padrões, e Paragraph.JoinRunsWithSameFormatting() mescla runs adjacentes que possuem formatação idêntica.

Lendo e Substituindo Texto com Range

Todo nó que contém conteúdo — um Document, Section, Paragraph ou Run — expõe um Range. Range.Text retorna o texto simples de tudo dentro desse intervalo, e Range.Replace(pattern, replacement) realiza uma busca e substituição limitada a esse intervalo, de modo que você pode, por exemplo, substituir texto dentro de um parágrafo sem tocar no resto do documento. Range.Delete() remove o conteúdo do intervalo completamente.

Comments

Um nó Comment ancora um comentário a uma localização no texto; construa um com new Comment(doc, author, initial, dateTime) e defina seu texto de corpo com SetText(text), então insira-o no documento como qualquer outro nó. Comment.AddReply(author, initial, dateTime, text) anexa uma resposta em thread, e RemoveReply(reply) / RemoveAllReplies() as removem. Os comentários de um documento são coletados em um CommentCollection.

Formatação de Lista ao Nível de Parágrafo

Paragraph.ListFormat (um objeto ListFormat) relata e controla se um parágrafo faz parte de uma lista: IsListItem e ListLevelNumber relatam seu estado atual, ApplyBulletDefault() e ApplyNumberDefault() transformam um parágrafo em um item de lista padrão com marcadores ou numerado, ListIndent() / ListOutdent() alteram seu nível de aninhamento na lista, e RemoveNumbers() o devolve a um parágrafo normal.

Dicas e Melhores Práticas

Defina as propriedades da fonte em DocumentBuilder.Font antes de escrever texto com o construtor, em vez de escrever o texto primeiro e reformatar objetos Run individuais depois.
Limite o escopo de Range.Replace ao menor intervalo que cobre o que você realmente deseja alterar — chame-o no intervalo de um Paragraph ou Section em vez de todo o documento quando a alteração não deve ser aplicada a nível de documento.
Chame Paragraph.JoinRunsWithSameFormatting() após uma série de edições programáticas para evitar uma estrutura de execução desnecessariamente fragmentada.
Use ListFormat.ApplyBulletDefault() / ApplyNumberDefault() para uma lista padrão rápida ao invés de construir definições de lista manualmente quando os padrões incorporados são suficientes.
Leia os resultados de Comment.AddReply como nós Comment — as respostas são objetos de comentário completos, não strings simples.

Problemas Comuns

Problema	Causa	Correção
Formatando o `Run`’s `Font` não altera visualmente o texto adjacente	O texto adjacente está em um `Run` diferente com sua própria instância de `Font`	Localize e formate cada `Run` afetado, ou defina a formatação via `DocumentBuilder.Font` antes de escrever
`Range.Replace` altera o texto fora da área pretendida	`Replace` foi chamado em `Document.Range` em vez de um intervalo de nó mais estreito	Chame `Replace` no `Paragraph` específico, `Section`, ou no `Range` de outro nó
Um parágrafo parece um item de lista, mas `IsListItem` é falso	A marcação/numeração é texto manual, não formatação real de lista	Aplique formatação real de lista com `ListFormat.ApplyBulletDefault()` ou `ApplyNumberDefault()` em vez de caracteres digitados
O documento tem muito mais nós `Run` do que o esperado	Edições pequenas repetidas dividem sequências sem juntá-las	Chame `Paragraph.JoinRunsWithSameFormatting()` após lotes de edições

FAQ

Qual é a diferença entre `Run` e `Paragraph`?

Um Run é um trecho de texto que compartilha um conjunto de formatação de caracteres (Font); um Paragraph é o nó composto que contém uma ou mais runs (e outro conteúdo em linha) além da formatação ao nível de parágrafo (ParagraphFormat).

Como leio todo o texto em um documento ou seção?

Leia a propriedade Text do Range desse nó — por exemplo, document.Range.Text ou section.Range.Text.

Como faço para encontrar e substituir texto em apenas um parágrafo?

Chame Replace(pattern, replacement) no Range desse Paragraph em vez de em Document.Range.

Como adiciono um comentário a um documento?

Crie-o com new Comment(doc, author, initial, dateTime), defina seu texto com SetText(text) e insira-o na árvore; responda a ele com Comment.AddReply(author, initial, dateTime, text).

Como converto um parágrafo em um item de lista com marcadores?

Chame ApplyBulletDefault() no ListFormat desse parágrafo; use ApplyNumberDefault() para uma lista numerada em vez disso.

API Reference Resumo

Classe/Método	Descrição
`Run`	Um trecho de texto que compartilha um conjunto de formatação de caracteres.
`Font`	Formatação ao nível de caractere — nome, tamanho, negrito, itálico, cor e mais.
`Paragraph`	Nó composto contendo os runs e a formatação de um parágrafo.
`ParagraphFormat`	Formatação ao nível de parágrafo — alinhamento, recuos, espaçamento, paginação.
`ParagraphCollection`	Coleção tipada de nós `Paragraph`, por exemplo `Body.Paragraphs`.
`Range`	Uma área contígua do documento; suporta `Text`, `Replace` e `Delete`.
`Comment`	Um comentário em thread ancorado a uma localização no texto.
`CommentCollection`	A coleção de comentários do documento.
`ListFormat`	Controla se e de que forma um parágrafo participa de uma lista.

Ver também

Aspose.Words for .NET — Enterprise Documentation

Trabalhando com Texto