Introdução
Aspose.Words FOSS para .NET inclui o mesmo modelo de objeto de formatação de texto que o motor comercial Aspose.Words: Font para atributos de nível de execução, ParagraphFormat para atributos de nível de parágrafo, ListFormat para listas numeradas e com marcadores, FrameFormat para quadros de texto posicionados e Range.Replace para localizar e substituir. Este guia foca especificamente nessa camada — formatação e reescrita de texto que já existe em um documento — em vez de construir a estrutura de um documento do zero (veja o post de introdução para uma visão geral da versão).
A biblioteca tem licença MIT, sem dependências nativas, e tem como alvo o .NET Standard 2.0, portanto funciona no .NET Framework 4.6.2+ e no .NET 6, 8 e 10. Instale-a via NuGet, ou compile-a a partir do código-fonte (veja o Início Rápido abaixo). Tudo descrito aqui funciona com .docx, .docm, .dotx, .dotm e arquivos Flat OPC carregados com new Document(fileName), ou com documentos construídos na memória com DocumentBuilder.
Como Aspose.Words FOSS para .NET é a verdadeira base de código Aspose.Words reduzida a um núcleo gratuito em vez de uma reescrita, o modelo de objeto Font, ParagraphFormat, ListFormat e FrameFormat é transferido diretamente para o comercial Aspose.Words para .NET caso um projeto mais tarde precise de layout de página, renderização ou dos conversores de formato adicionais que esta edição exclui.
Recursos Principais
Formatação de Nível de Execução com Fonte
Cada Run expõe uma propriedade Font, e DocumentBuilder.Font define a fonte que será aplicada ao texto escrito a seguir. Além dos óbvios Bold, Italic e Underline (um enum Underline com valores incluindo Single, Double, Dotted, Dash, Wavy e suas variantes *Heavy), Font cobre StrikeThrough, DoubleStrikeThrough, Superscript, Subscript, SmallCaps, AllCaps, Hidden, Shadow, Outline, Emboss, Engrave, Color, HighlightColor, Spacing, Position, Kerning, Scaling e EmphasisMark. Font.Style, Font.StyleName e Font.StyleIdentifier vinculam uma execução a um estilo de caractere, e Font.ClearFormatting() redefinem a formatação direta de uma execução para os padrões do estilo. DocumentBuilder também expõe Bold, Italic e Underline diretamente como atalhos, além de PushFont() e PopFont() para salvar e restaurar o estado da fonte atual do construtor ao redor de uma alteração temporária de formatação.
Formatação de Parágrafo com ParagraphFormat
ParagraphFormat (acessível via Paragraph.ParagraphFormat ou DocumentBuilder.ParagraphFormat) controla o alinhamento através do enum ParagraphAlignment (Left, Center, Right, Justify, Distributed, além das variantes árabes kashida e tailandesas distribuídas), a indentação através de LeftIndent, RightIndent e FirstLineIndent (com equivalentes CharacterUnit* para layouts da Ásia Oriental), e o espaçamento através de SpaceBefore, SpaceAfter e LineSpacingRule/LineSpacing. O comportamento de paginação é controlado por KeepTogether, KeepWithNext, PageBreakBefore e WidowControl, e Bidi marca um parágrafo como da direita para a esquerda. Paradas de tabulação personalizadas vivem em ParagraphFormat.TabStops, um TabStopCollection de objetos TabStop, cada um com um Position, um TabAlignment (Left, Center, Right, Decimal, Bar), e um TabLeader (None, Dots, Dashes, Line, Heavy, MiddleDot). Assim como Font, ParagraphFormat.Style e StyleName vinculam o parágrafo a um Style nomeado, e ClearFormatting() limpa a formatação direta do parágrafo.
Listas com ListFormat
ListFormat (em Paragraph.ListFormat ou DocumentBuilder.ListFormat) aplica formatação de lista a um parágrafo: ApplyBulletDefault() e ApplyNumberDefault() o convertem em uma lista padrão com marcadores ou numerada, RemoveNumbers() remove totalmente a formatação de lista, e ListIndent()/ListOutdent() o movem entre níveis de lista. ListFormat.List devolve a definição subjacente de List, e ListFormat.ListLevel devolve o ListLevel em vigor para esse parágrafo, que contém configurações por nível como NumberStyle, NumberFormat, Alignment (um ListLevelAlignment de Left, Center ou Right), StartAt, RestartAfterLevel, um Font específico de nível, e TrailingCharacter (um ListTrailingCharacter de Tab, Space ou Nothing) que controla o espaço entre o rótulo da lista e o texto do parágrafo. Novas definições de lista vêm de ListCollection.Add(listTemplate) usando um dos presets integrados ListTemplate (BulletDefault, NumberArabicDot, NumberUppercaseRomanDot e similares), ou AddSingleLevelList para uma lista de nível único; as listas de um documento são enumeradas através de Document.Lists.
Quadros de Texto com FrameFormat
Paragraph.FrameFormat é um objeto de relatório somente leitura: cada propriedade nele reflete o parágrafo atual estado da moldura em vez de permitir que você o defina diretamente. IsFrame relata se o parágrafo está atualmente em um quadro; Width, Height, e HeightRule relata seu tamanho; HorizontalPosition e VerticalPosition, juntamente com RelativeHorizontalPosition e RelativeVerticalPosition, relatar onde está ancorado em relação à página, margem, coluna ou parágrafo; e HorizontalDistanceFromText/VerticalDistanceFromText relatar o espaço entre a moldura e o texto do corpo circundante. HorizontalAlignment e VerticalAlignment relate como o conteúdo se alinha dentro da moldura.
Localizar e Substituir com Intervalo e IReplacingCallback
Range.Replace — disponível em Document.Range para uma passagem em todo o documento, ou no Range de qualquer nó — possui sobrecargas para um par padrão/substituição simples e para um par padrão/substituição combinado com uma instância FindReplaceOptions, suportando correspondência baseada em regex. FindReplaceOptions.MatchCase e FindWholeWordsOnly restringem o que conta como correspondência; Direction (FindReplaceDirection.Forward ou Backward) define a ordem de varredura; ApplyFont e ApplyParagraphFormat permitem que uma passagem de substituição carregue a formatação para o texto de substituição; e um conjunto de flags Ignore* (IgnoreDeleted, IgnoreInserted, IgnoreFields, IgnoreFieldCodes, IgnoreFootnotes, IgnoreStructuredDocumentTags, IgnoreShapes, IgnoreOfficeMath) exclui categorias específicas de conteúdo da correspondência. Para lógica de substituição que uma string fixa não pode expressar, implemente IReplacingCallback.Replacing(args) e defina-a como FindReplaceOptions.ReplacingCallback (ou passe-a para um dos construtores FindReplaceOptions que aceita um callback diretamente); o parâmetro args é um ReplacingArgs que expõe Match, MatchNode, MatchOffset e uma string Replacement configurável para que o callback possa calcular um valor por correspondência. Um enum ReplaceAction relacionado (Replace, Skip, Stop) descreve os possíveis resultados para uma única correspondência durante a operação.
Início Rápido
Aspose.Words FOSS para .NET está disponível via NuGet:
dotnet add package Aspose.Words.FOSSPara compilar a partir do código-fonte:
git clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git
cd Aspose.Words-FOSS-for-.NET
dotnet build Aspose.Words.sln -c Release
Em seguida, adicione uma referência de projeto a Aspose.Words.csproj. Para formatar o texto enquanto o cria, defina as propriedades de DocumentBuilder.Font (Bold, Italic, Underline), as propriedades de DocumentBuilder.ParagraphFormat (Alignment, recuos, espaçamento) e DocumentBuilder.ListFormat (ApplyBulletDefault(), ApplyNumberDefault()) antes de chamar Write(), Writeln() ou InsertParagraph() — o construtor aplica seu estado de formatação atual a tudo o que for escrito até que você o altere novamente, ou envolva uma alteração temporária em PushFont()/PopFont(). Para reformatar ou reescrever texto já presente em um documento, abra-o com new Document(fileName) e chame Range.Replace() em doc.Range — seja a sobrecarga simples de padrão/substituição, ou a sobrecarga que aceita um FindReplaceOptions com MatchCase, FindWholeWordsOnly ou um IReplacingCallback personalizado — então Save() o resultado.
Formatos suportados
| Formato | Extensão | Ler | Escrever |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (todas as variantes) | (diversos) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
As classes de formatação acima se aplicam da mesma forma, independentemente de qual desses formatos um documento seja carregado ou salvo. Esta edição não oferece suporte a DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 ou WordML para leitura ou escrita, e não suporta PDF, XPS ou exportação de imagens, pois o layout de página e a renderização estão fora de seu escopo.
Código Aberto & Licenciamento
Aspose.Words FOSS para .NET é lançado sob a licença MIT, gratuito para uso comercial e pessoal sem royalties ou restrições de redistribuição. O código-fonte completo, incluindo as implementações de Font, ParagraphFormat, ListFormat, FrameFormat e Range descritas acima, está disponível em GitHub no Aspose.Words FOSS para .NET repositório.
