Introducere
Acest ghid analizează cum Aspose.Words FOSS pentru .NET reprezintă un document Word în memorie și API-urile utilizate pentru a construi, naviga și modifica acea reprezentare: DocumentBuilder pentru autorarea secvențială, arborele de noduri (Node, CompositeNode, NodeCollection) pentru acces structural direct, DocumentVisitor pentru procesarea fiecărui tip de nod într-o singură trecere, căutarea-și-înlocuirea prin Range și FindReplaceOptions, și metodele pentru combinarea și clonarea documentelor. Unde postarea de anunț introduce biblioteca în ansamblu, acesta rămâne concentrat pe modelul de obiecte al documentului (DOM) — cea mai mare zonă a suprafeței API — și pe modul în care piesele sale se îmbină.
Aspose.Words FOSS pentru .NET este lansat sub licența MIT fără dependențe native; vizează .NET Standard 2.0, astfel că DOM-ul descris aici este disponibil pe .NET Framework 4.6.2+ și .NET 6, 8 și 10, pe Windows, Linux și macOS. Instalați-l prin NuGet sau compilați-l din sursă — vedeți Quick Start mai jos.
Fiecare sarcină descrisă mai jos — scrierea unui raport de la zero, restructurarea unui fișier .docx existent, parcurgerea conținutului său pentru analiză sau asamblarea mai multor documente într-unul singur — pornește de la același mic grup de tipuri de bază: Document, DocumentBuilder și ierarhia Node de sub ele.
Document Object Model
Construirea documentelor cu DocumentBuilder
DocumentBuilder este un scriitor bazat pe cursor care se situează deasupra unui Document și inserează conținut secvențial. Write(text) și Writeln(text) adaugă text la poziția curentă; InsertParagraph() și InsertBreak(breakType) adaugă paragrafe și întreruperi de pagină/coloană/secțiune. Formatarea este cu stare: proprietățile Font, ParagraphFormat, ListFormat și PageSetup ale builder-ului se aplică la tot ce este scris ulterior, iar PushFont() / PopFont() salvează și restabilesc starea fontului curent astfel încât o modificare temporară de stil să nu trebuiască anulată manual. Metodele de navigare repoziționează cursorul oriunde într-un document existent — MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName), MoveToParagraph(paragraphIndex, characterIndex) și MoveTo(node) de scop general — și DocumentBuilder.CurrentNode, DocumentBuilder.CurrentParagraph și DocumentBuilder.CurrentSection raportează unde se află builder-ul în prezent. Pentru extragerea textului în mod numai citire, când nu este necesar un DOM complet, PlainTextDocument oferă o cale mai ușoară: new PlainTextDocument(fileName) expune doar proprietatea PlainTextDocument.Text și proprietățile încorporate și personalizate ale documentului.
Arborele de Noduri: Secțiuni, Paragrafe, Run-uri și Tabele
Un Document este un arbore de obiecte Node cu rădăcina în documentul însuși: Section → Body → Paragraph → Run pentru textul corpului, cu Table → Row → Cell ramificându-se oriunde apare un tabel. CompositeNode, clasa de bază pentru fiecare nod container, expune CompositeNode.FirstChild, CompositeNode.LastChild, Node.NextSibling și Node.PreviousSibling pentru traversare directă, GetChildNodes(nodeType, isDeep) pentru a colecta fiecare nod de un anumit NodeType (Paragraph, Run, Table etc.) la orice adâncime, și GetChild(nodeType, index, isDeep) pentru căutări indexate. AppendChild(newChild), InsertBefore(newChild, refChild), InsertAfter(newChild, refChild) și RemoveChild(oldChild) modifică arborele direct. CompositeNode.SelectNodes(xpath) și SelectSingleNode(xpath) selectează noduri cu o expresie de tip XPath în loc să parcurgi manual arborele, iar pentru documente foarte mari, Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) trec prin fiecare nod unul câte unul fără recursivitate.
DocumentVisitor: Procesarea fiecărui tip de nod într-un singur pas
Derularea subclasei DocumentVisitor este modalitatea de a procesa un document fără a codifica rigid structura acestuia. Definește metode pereche Visit-Start / Visit-End pentru fiecare tip de nod compus, inclusiv DocumentVisitor.VisitSectionStart, DocumentVisitor.VisitParagraphStart, DocumentVisitor.VisitTableStart, DocumentVisitor.VisitRowStart, DocumentVisitor.VisitCellStart și DocumentVisitor.VisitBookmarkStart — fiecare având un callback corespunzător End — plus DocumentVisitor.VisitFieldStart, DocumentVisitor.VisitFieldSeparator, DocumentVisitor.VisitFieldEnd și DocumentVisitor.VisitRun pentru secvențe individuale de text. Apelă Accept(visitor) pe un Document, Section sau orice alt nod pentru a rula vizitatorul pe acel nod și pe tot ce se află sub el; AcceptStart(visitor) și AcceptEnd(visitor) invocă doar callback-urile de intrare și ieșire pentru un singur nod compus. Fiecare metodă Visit returnează o valoare VisitorAction care controlează cum continuă traversarea — Continue în subarbore, SkipThisNode pentru a-l omite sau Stop pentru a opri complet.
Găsirea și Înlocuirea Textului
Range.Replace(pattern, replacement) execută o căutare-și-înlocuire pe Range-ul care îl deține — un Document întreg, o Section sau proprietatea Range a oricărui nod — cu modelul de căutare acceptat ca șir literal sau expresie regulată. Suprasarcina Range.Replace(pattern, replacement, options) primește o instanță FindReplaceOptions pentru a controla FindReplaceOptions.MatchCase, FindReplaceOptions.FindWholeWordsOnly, căutarea FindReplaceOptions.Direction (o valoare FindReplaceDirection de Forward sau Backward), formatarea aplicată textului înlocuit (FindReplaceOptions.ApplyFont, FindReplaceOptions.ApplyParagraphFormat) și ce conținut înconjurător să fie lăsat neatins (FindReplaceOptions.IgnoreFields, FindReplaceOptions.IgnoreFootnotes, FindReplaceOptions.IgnoreFieldCodes și steagurile înrudite Ignore*). Pentru logică per-potrivire dincolo de o simplă substituție, implementează metoda Replacing(args) a IReplacingCallback și atribuie implementarea la FindReplaceOptions.ReplacingCallback; fiecare potrivire apelează înapoi cu un ReplacingArgs care descrie potrivirea, iar valoarea returnată de callback — o valoare ReplaceAction de Replace, Skip sau Stop — decide ce se întâmplă cu ea.
Combinarea și Clonarea Documentelor
Document.AppendDocument(srcDoc, importFormatMode) adaugă conținutul complet al unui Document la sfârșitul altuia. Argumentul său importFormatMode — o valoare ImportFormatMode de UseDestinationStyles, KeepSourceFormatting sau KeepDifferentStyles — stabilește cum sunt rezolvate conflictele de stil dintre sursă și destinație, iar suprasarcina Document.AppendDocument(srcDoc, importFormatMode, importFormatOptions) oferă un control mai fin prin ImportFormatOptions (ImportFormatOptions.KeepSourceNumbering, ImportFormatOptions.IgnoreHeaderFooter, ImportFormatOptions.MergePastedLists și altele similare). Pentru a insera conținutul unui alt document într-o poziție specifică în loc de sfârșit, DocumentBuilder.InsertDocument(srcDoc, importFormatMode, importFormatOptions) face echivalentul din poziția curentă a cursorului builder-ului, iar DocumentBuilder.InsertDocumentInline(srcDoc, importFormatMode, importFormatOptions) inserează același conținut fără a adăuga un paragraf sau o întrerupere de secțiune la punctul de inserare. Document.ImportNode(srcNode, isImportChildren) copiază un nod — opțional cu copiii săi — dintr-un document diferit pentru a putea fi adăugat în cel curent, iar metoda Node.Clone(isCloneChildren) disponibilă pe orice nod dublează structura în același document, de exemplu reutilizând un Section ca șablon pentru conținut repetat.
Marcaje și variabile de document
Proprietatea Range.Bookmarks expune o BookmarkCollection de ancore numite în interiorul acelui interval. DocumentBuilder.StartBookmark(bookmarkName) și EndBookmark(bookmarkName) marchează extinderea unui semn de carte în timpul construirii; indexatorul BookmarkCollection, bookmarks[name], recuperează unul mai târziu pentru navigarea cu DocumentBuilder.MoveToBookmark(bookmarkName) sau pentru citirea Bookmark.Text. Separat, Document.Variables — o VariableCollection — stochează perechi arbitrare de șiruri nume/valoare direct pe documentul în sine, fiind util pentru transportarea unor mici bucăți de stare printr-un lanț de generare a documentului fără a adăuga conținut vizibil.
Start rapid
Aspose.Words FOSS pentru .NET este disponibil prin NuGet:
dotnet add package Aspose.Words.FOSSPentru a construi din sursă în schimb:
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
Cu o referință de proiect la Aspose.Words.csproj în loc, calea cea mai scurtă către un document urmează același model folosit în tot acest articol: construiește un Document, înfășoară-l într-un DocumentBuilder, apelează Write() sau Writeln() pentru a adăuga text — formatarea setată pe proprietățile Font și ParagraphFormat ale builder-ului se propagă la fiecare scriere ulterioară — și apelează Document.Save(fileName) pentru a-l salva ca .docx, .docm, .dotx, .dotm, Flat OPC, Markdown sau text simplu. Pentru a edita un fișier existent în loc să începi de la zero, încarcă-l direct cu new Document(fileName), mută builder-ul la o locație specifică cu MoveToBookmark(), MoveToParagraph() sau MoveTo(node), și continuă să scrii de acolo.
Formate acceptate
| Format | Extensie | Citire | Scriere |
|---|---|---|---|
| DOCX | .docx | ✓ | ✓ |
| DOCM | .docm | ✓ | ✓ |
| DOTX | .dotx | ✓ | ✓ |
| DOTM | .dotm | ✓ | ✓ |
| Flat OPC (toate variantele) | (diverse) | ✓ | ✓ |
| Markdown | .md | ✓ | ✓ |
| Text | .txt | ✓ | ✓ |
Arborele de noduri descris mai sus este disponibil în același mod, indiferent de formatul din care a fost încărcat un document sau în care va fi salvat — DOM-ul este independent de format intern. Ceea ce nu este inclus în această ediție este tot ce depinde de aspectul paginii: nu există export PDF, XPS sau imagine și nu există tipărire, astfel încât valorile câmpurilor dependente de aspect, cum ar fi numerele de pagină, sunt evaluate ca substituenți în loc să fie calculate. Conversoarele de format suplimentare (DOC, RTF, ODT, HTML, EPUB, MHTML, MOBI, AZW3 și WordML) nu sunt citite sau scrise, iar execuția de fuziune de corespondență, raportarea LINQ și compararea documentelor nu sunt incluse. Dezvoltatorii care au nevoie de aceste capabilități pot trece la versiunea comercială Aspose.Words pentru .NET fără a rescrie codul DOM afișat aici, deoarece ambele ediții împărtășesc același API de bază.
Open Source & Licențiere
Aspose.Words FOSS pentru .NET este lansat sub licența MIT, gratuit pentru utilizare comercială și personală, fără redevențe sau restricții de redistribuire. Sursa, inclusiv Document, DocumentBuilder, și implementarea arborelui de noduri descrisă mai sus, este disponibilă în depozitul Aspose.Words FOSS pentru .NET pe GitHub.
