Introduzione
Aspose.Words FOSS per .NET include lo stesso modello di oggetto per la formattazione del testo del motore commerciale Aspose.Words: Font per attributi a livello di run, ParagraphFormat per attributi a livello di paragrafo, ListFormat per elenchi numerati e puntati, FrameFormat per riquadri di testo posizionati e Range.Replace per trova e sostituisci. Questa guida si concentra specificamente su quel livello — la formattazione e la riscrittura del testo già presente in un documento — piuttosto che sulla costruzione della struttura del documento da zero (vedi il post introduttivo per una panoramica del rilascio).
La libreria è rilasciata sotto licenza MIT senza dipendenze native e mira a .NET Standard 2.0, quindi funziona su .NET Framework 4.6.2+ e .NET 6, 8 e 10. Installala tramite NuGet, o compilala dal sorgente (vedi Avvio rapido di seguito). Tutto ciò che è descritto qui funziona con .docx, .docm, .dotx, .dotm e file Flat OPC caricati con new Document(fileName), o con documenti costruiti in memoria con DocumentBuilder.
Poiché Aspose.Words FOSS per .NET è il vero codice sorgente Aspose.Words ridotto a un core gratuito anziché una riscrittura, il modello di oggetto Font, ParagraphFormat, ListFormat e FrameFormat viene trasferito direttamente al commerciale Aspose.Words per .NET se in seguito un progetto necessita di layout di pagina, rendering o dei convertitori di formato aggiuntivi che questa edizione esclude.
Caratteristiche principali
Formattazione a livello di run con carattere
Ogni Run espone una proprietà Font, e DocumentBuilder.Font imposta il carattere che verrà applicato al testo scritto successivamente. Oltre ai consueti Bold, Italic e Underline (un enum Underline con valori tra cui Single, Double, Dotted, Dash, Wavy e le loro varianti *Heavy), Font copre 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 collegano un run a uno stile di carattere, e Font.ClearFormatting() ripristina la formattazione diretta di un run ai valori predefiniti dello stile. DocumentBuilder espone anche Bold, Italic e Underline direttamente come scorciatoie, più PushFont() e PopFont() per salvare e ripristinare lo stato del carattere corrente del builder attorno a una modifica di formattazione temporanea.
Formattazione dei paragrafi con ParagraphFormat
ParagraphFormat (raggiungibile tramite Paragraph.ParagraphFormat o DocumentBuilder.ParagraphFormat) controlla l’allineamento tramite l’enumerazione ParagraphAlignment (Left, Center, Right, Justify, Distributed, più le varianti arabe kashida e thailandesi distribuite), l’indentazione tramite LeftIndent, RightIndent e FirstLineIndent (con equivalenti CharacterUnit* per layout dell’Est asiatico), e la spaziatura tramite SpaceBefore, SpaceAfter e LineSpacingRule/LineSpacing. Il comportamento di impaginazione è controllato con KeepTogether, KeepWithNext, PageBreakBefore e WidowControl, e Bidi segna un paragrafo come da destra a sinistra. Le tabulazioni personalizzate risiedono in ParagraphFormat.TabStops, un TabStopCollection di oggetti TabStop, ciascuno con un Position, un TabAlignment (Left, Center, Right, Decimal, Bar), e un TabLeader (None, Dots, Dashes, Line, Heavy, MiddleDot). Come con Font, ParagraphFormat.Style e StyleName collegano il paragrafo a un Style denominato, e ClearFormatting() cancella la formattazione diretta del paragrafo.
Elenchi con ListFormat
ListFormat (su Paragraph.ListFormat o DocumentBuilder.ListFormat) applica la formattazione dell’elenco a un paragrafo: ApplyBulletDefault() e ApplyNumberDefault() lo convertono in un elenco puntato o numerato predefinito, RemoveNumbers() rimuove completamente la formattazione dell’elenco, e ListIndent()/ListOutdent() lo spostano tra i livelli dell’elenco. ListFormat.List restituisce la definizione List sottostante, e ListFormat.ListLevel restituisce il ListLevel in vigore per quel paragrafo, che contiene impostazioni per livello come NumberStyle, NumberFormat, Alignment (un ListLevelAlignment di Left, Center o Right), StartAt, RestartAfterLevel, un Font specifico per livello, e TrailingCharacter (un ListTrailingCharacter di Tab, Space o Nothing) che controlla lo spazio tra l’etichetta dell’elenco e il testo del paragrafo. Nuove definizioni di elenco provengono da ListCollection.Add(listTemplate) utilizzando uno dei preset ListTemplate incorporati (BulletDefault, NumberArabicDot, NumberUppercaseRomanDot e simili), o AddSingleLevelList per un elenco a livello singolo; gli elenchi di un documento sono elencati tramite Document.Lists.
Riquadri di testo con FrameFormat
Paragraph.FrameFormat è un oggetto di reportistica in sola lettura: ogni proprietà su di esso riflette il corrente stato del frame anziché consentirti di impostarlo direttamente. IsFrame segnala se il paragrafo è attualmente un frame; Width, Height, e HeightRule segnala la sua dimensione; HorizontalPosition e VerticalPosition, insieme a RelativeHorizontalPosition e RelativeVerticalPosition, segnare dove è ancorato rispetto alla pagina, al margine, alla colonna o al paragrafo; e HorizontalDistanceFromText/VerticalDistanceFromText segnare lo spazio tra il riquadro e il testo circostante. HorizontalAlignment e VerticalAlignment segnare come il contenuto è allineato all’interno del riquadro.
Trova e sostituisci con Range e IReplacingCallback
Range.Replace — disponibile su Document.Range per un passaggio su tutto il documento, o sul Range di qualsiasi nodo — offre overload per una semplice coppia modello/sostituzione e per una coppia modello/sostituzione combinata con un’istanza FindReplaceOptions, supportando il matching basato su regex. FindReplaceOptions.MatchCase e FindWholeWordsOnly restringono ciò che conta come corrispondenza; Direction (FindReplaceDirection.Forward o Backward) imposta l’ordine di scansione; ApplyFont e ApplyParagraphFormat consentono a un passaggio di sostituzione di trasferire la formattazione al testo di sostituzione; e un insieme di flag Ignore* (IgnoreDeleted, IgnoreInserted, IgnoreFields, IgnoreFieldCodes, IgnoreFootnotes, IgnoreStructuredDocumentTags, IgnoreShapes, IgnoreOfficeMath) escludono categorie di contenuto specifiche dalla corrispondenza. Per una logica di sostituzione che una stringa fissa non può esprimere, implementare IReplacingCallback.Replacing(args) e impostarla come FindReplaceOptions.ReplacingCallback (o passarla a uno dei costruttori FindReplaceOptions che accetta direttamente un callback); il parametro args è un ReplacingArgs che espone Match, MatchNode, MatchOffset e una stringa Replacement impostabile così il callback può calcolare un valore per corrispondenza. Un enum ReplaceAction correlato (Replace, Skip, Stop) descrive i possibili risultati per una singola corrispondenza durante l’operazione.
Avvio rapido
Aspose.Words FOSS per .NET è disponibile tramite NuGet:
dotnet add package Aspose.Words.FOSSPer compilare dal sorgente invece:
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
Quindi aggiungi un riferimento al progetto Aspose.Words.csproj. Per formattare il testo mentre lo scrivi, imposta le proprietà DocumentBuilder.Font (Bold, Italic, Underline), le proprietà DocumentBuilder.ParagraphFormat (Alignment, rientri, spaziatura) e DocumentBuilder.ListFormat (ApplyBulletDefault(), ApplyNumberDefault()) prima di chiamare Write(), Writeln() o InsertParagraph() — il costruttore applica lo stato di formattazione corrente a tutto ciò che viene scritto finché non lo cambi nuovamente, o avvolgi una modifica temporanea in PushFont()/PopFont(). Per riformattare o riscrivere il testo già presente in un documento, aprilo con new Document(fileName) e chiama Range.Replace() su doc.Range — sia la sovraccarico semplice pattern/sostituzione, sia la sovraccarico che accetta un FindReplaceOptions con MatchCase, FindWholeWordsOnly, o un IReplacingCallback personalizzato — quindi Save() il risultato.
Formati supportati
| Formato | Estensione | Leggi | Scrivi |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (tutte le varianti) | (vari) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Le classi di formattazione sopra si applicano allo stesso modo indipendentemente dal formato da cui un documento è caricato o in cui è salvato. Questa edizione non supporta DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 o WordML per la lettura o la scrittura, e non supporta PDF, XPS o l’esportazione di immagini, poiché il layout di pagina e il rendering sono al di fuori del suo ambito.
Open Source e Licenze
Aspose.Words FOSS per .NET è rilasciato sotto licenza MIT, gratuito per uso commerciale e personale senza royalty o restrizioni di ridistribuzione. Il codice sorgente completo, incluse le implementazioni Font, ParagraphFormat, ListFormat, FrameFormat e Range descritte sopra, è disponibile su GitHub nel Aspose.Words FOSS per .NET repository.
