Lucrul cu documente

Aspose.Words FOSS pentru .NET reprezintă fiecare fișier Word ca un model de obiect în memorie cu rădăcina în clasa Document, cu DocumentBuilder oferind un API de nivel înalt, bazat pe cursor, pentru crearea de conținut. Acest ghid acoperă crearea și încărcarea documentelor, crearea de conținut cu DocumentBuilder, structura secțiune/corp, parcurgerea arborelui de noduri, combinarea documentelor și protejarea lor.

Crearea și încărcarea documentelor

Creează un document gol cu new Document(), sau deschide un fișier existent furnizând o cale sau Stream la constructorul Document(fileName) sau Document(stream). Suprasarcinile care acceptă un argument LoadOptions îți permit să controlezi comportamentul de încărcare, cum ar fi furnizarea unei parole pentru un fișier criptat.

Înainte de a încărca un fișier dintr-o sursă necunoscută sau neîncredere, FileFormatUtil.DetectFileFormat(fileName) (sau suprasarcina Stream) returnează un FileFormatInfo care descrie LoadFormat detectat și dacă fișierul este IsEncrypted, HasDigitalSignature sau HasMacros.

Crearea de conținut cu DocumentBuilder

DocumentBuilder învelește un Document și expune un cursor pe care îl miști prin document în timp ce inserezi conținut. Write(text) și Writeln(text) inserează text la cursor; InsertParagraph() începe un paragraf nou. Proprietățile de formatare ale constructorului — Font, ParagraphFormat, ListFormat, PageSetup — se aplică la tot ce este scris în continuare.

Mutați cursorul cu MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) sau MoveToParagraph(paragraphIndex, characterIndex). Proprietățile CurrentNode, CurrentParagraph și CurrentSection ale constructorului raportează poziția curentă în arbore.

Structura documentului: Secțiuni și Corp

Un Document conține un SectionCollection (Document.Sections, plus FirstSection / LastSection); fiecare Section are un Body, o colecție opțională de antete/subsoluri și propriul său PageSetup. Section.AppendContent(sourceSection) și PrependContent(sourceSection) copiază conținutul între secțiuni, iar ClearContent() reinițializează o secțiune fără să o elimine din document.

Într-un Body, conținutul este expus prin Body.Paragraphs (un ParagraphCollection) și Body.Tables. Un Range — disponibil din Document, Section, Paragraph și alte noduri — reprezintă o zonă contiguă a arborelui; Range.Text citește textul său simplu și Range.Replace(pattern, replacement) efectuează o căutare-și-înlocuire doar în acea zonă.

Parcurgerea arborelui de noduri cu DocumentVisitor

Fiecare parte a unui document — secțiuni, paragrafe, rulări, tabele, câmpuri, forme, comentarii, note de subsol — este un Node într-un arbore compozit cu rădăcina la Document. Pentru a procesa fiecare nod de un anumit tip fără a recurge manual, creați o subclasă a clasei abstracte DocumentVisitor și suprascrieți callback-urile Visit*Start / Visit*End de care aveți nevoie, cum ar fi VisitParagraphStart(paragraph) sau VisitRun(run), apoi apelați document.Accept(visitor). Fiecare callback poate returna un VisitorAction (Continue, SkipThisNode sau Stop) pentru a controla modul în care continuă traversarea.

Clonarea, importarea și adăugarea de conținut

Document.Clone() produce o copie profundă a întregului document. Pentru a muta conținutul între două instanțe Document diferite, apelați ImportNode(srcNode, isImportChildren) pe documentul destinație pentru a aduce un nod dintr-un arbore străin, sau apelați Document.AppendDocument(srcDoc, importFormatMode) pentru a adăuga secțiunile unui document la altul folosind un ImportFormatMode ales — KeepSourceFormatting, UseDestinationStyles sau KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) inserează conținutul documentului sursă la cursorul constructorului în loc de la sfârșitul destinației.

Protejarea documentelor

Document.Protect(type, password) restricționează editarea conform unei valori ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields sau NoProtection pentru a elimina protecția. Unprotect() (cu sau fără parolă) o inversează. Aceasta este o restricție de editare impusă de Word, separată de criptarea cu parolă OOXML pe care OoxmlSaveOptions.Password o aplică la salvarea unui fișier.

Sfaturi și bune practici

Preferă DocumentBuilder pentru construirea de conținut nou; treci la manipularea directă a nodurilor (AppendChild, InsertAfter, Clone) când ai nevoie de un control fin asupra unui arbore existent.
Apelează FileFormatUtil.DetectFileFormat înainte de a încărca un fișier dintr-o sursă neîncrezătoare sau furnizată de utilizator, astfel încât să poți verifica LoadFormat și să respingi rapid intrările nesuportate sau criptate.
Când combini documente cu AppendDocument sau InsertDocument, alege ImportFormatMode în mod deliberat — KeepSourceFormatting păstrează aspectul sursei, UseDestinationStyles se potrivește cu setul de stiluri al documentului țintă.
Folosește o subclasă DocumentVisitor în loc de parcurgerea recursivă manuală a arborelui când trebuie să procesezi fiecare instanță a unui tip de nod în mod consistent.
Document.Protect este o restricție de editare, nu o criptare — combină-l cu OoxmlSaveOptions.Password dacă fișierul salvat trebuie să solicite o parolă pentru a fi deschis.

Probleme comune

Problemă	Cauză	Remediere
`Document(fileName)` aruncă pentru un fișier care se deschide fără probleme în Word	Formatul fișierului nu este unul pe care această ediție îl suportă pentru încărcare	Apelă mai întâi `FileFormatUtil.DetectFileFormat` și verifică `LoadFormat` returnat înainte de încărcare
Conținutul adăugat preia fonturile sau stilurile greșite	Neconcordanță `ImportFormatMode` între seturile de stiluri sursă și destinație	Transmite `KeepSourceFormatting` sau `UseDestinationStyles` explicit în loc să te bazezi pe o valoare implicită
Parcurgerea `DocumentVisitor` se oprește prematur sau sare conținutul	O suprascriere `VisitStart` / `VisitEnd` returnează `SkipThisNode` sau `Stop` neintenționat	Returnează `VisitorAction.Continue` din fiecare suprascriere, cu excepția cazului în care intenționezi în mod explicit să sari sau să oprești
`Unprotect()` nu are niciun efect	Documentul nu a fost protejat cu o parolă, sau parola greșită a fost furnizată	Apelează `Unprotect()` fără argumente dacă `Protect` a fost apelat fără parolă, altfel transmite parola corespunzătoare

FAQ

Care este diferența dintre `Document.Clone()` și `ImportNode`?

Clone() copiază un document întreg într-o nouă instanță Document. ImportNode(srcNode, isImportChildren) aduce un singur nod (și opțional copiii săi) din arborele unui document în altul, ceea ce utilizați când combinați conținut specific în loc de documente întregi.

Ce formate de fișiere poate încărca `Document(fileName)`?

Document(fileName) încarcă DOCX, DOCM, DOTX, DOTM, Flat OPC (plus variantele sale cu macrocomenzi și de șablon), Markdown și text simplu. Formatele vechi de procesare a textului și web sunt excluse din încărcătoarele acestei ediții.

Cum pot afla unde este poziționat în prezent un `DocumentBuilder`?

Citește CurrentNode, CurrentParagraph sau CurrentSection pe instanța builderului.

Criptează `Document.Protect` fișierul salvat?

Nu — este o restricție de editare impusă de Word când fișierul este deschis. Pentru a cere o parolă doar pentru a deschide fișierul, setează OoxmlSaveOptions.Password la salvare.

Cum pot citi doar paragrafele din corpul documentului?

Folosește colecția Body.Paragraphs, sau Body.GetChildNodes(nodeType, isDeep) pentru alte tipuri de noduri.

API Reference Rezumat

Clasă/Metodă	Descriere:
`Document`	Rădăcina modelului de obiecte al documentului; constructorii încarcă dintr-un fișier sau flux, sau creează un document gol.
`Document.Save`	Scrie documentul într-un fișier, flux sau răspuns HTTP într-un format ales.
`Document.Clone()`	Produce o copie profundă a întregului document.
`Document.Protect(type, password)` / `Unprotect()`	Aplică sau elimină o restricție de editare.
`Document.AppendDocument(srcDoc, importFormatMode)`	Adaugă secțiunile altui document la acesta.
`DocumentBuilder`	Funcție API bazată pe cursor pentru scrierea textului și inserarea conținutului într-un document.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Inserează conținutul unui document sursă la cursor.
`Section` / `SectionCollection`	O singură secțiune a unui document și colecția tuturor secțiunilor.
`Body`	Container pentru textul principal (paragrafe și tabele) al unei secțiuni.
`Range`	O zonă contiguă a arborelui de documente; suportă `Text` și `Replace`.
`DocumentVisitor`	Clasă de bază abstractă pentru parcurgerea fiecărui nod din arborele de documente.
`ProtectionType`	Enum al restricţiilor de editare la nivel de document.
`FileFormatUtil.DetectFileFormat`	Detectează formatul unui fişier sau flux înainte de a-l încărca.

Vezi și:

Aspose.Words for .NET — Enterprise Documentation

Lucrul cu documente