Dokumentumok kezelése

Aspose.Words FOSS for .NET minden Word fájlt egy memóriában tárolt objektummodellként ábrázol, melynek gyökere a Document osztály, a DocumentBuilder pedig magas szintű, kurzor-alapú API-t biztosít a tartalom szerkesztéséhez. Ez az útmutató a dokumentumok létrehozásával és betöltésével, a DocumentBuilder használatával, a szakasz/törzs struktúrával, a csomópontfa bejárásával, a dokumentumok egyesítésével és azok védelmével foglalkozik.

Dokumentumok létrehozása és betöltése

Hozzon létre egy üres dokumentumot a new Document() segítségével, vagy nyisson meg egy meglévő fájlt úgy, hogy egy útvonalat vagy Stream-t ad át a Document(fileName) vagy Document(stream) konstruktorának. Azok a túlterhelések, amelyek LoadOptions argumentumot fogadnak, lehetővé teszik a betöltési viselkedés szabályozását, például jelszó megadását egy titkosított fájlhoz.

Ismeretlen vagy megbízhatatlan forrásból történő fájl betöltése előtt a FileFormatUtil.DetectFileFormat(fileName) (vagy a Stream túlterhelés) egy FileFormatInfo objektumot ad vissza, amely leírja a felismert LoadFormat-t, és azt, hogy a fájl IsEncrypted, HasDigitalSignature vagy HasMacros.

Szerkesztés a DocumentBuilder segítségével

DocumentBuilder egy Document-t csomagol, és egy kurzort tesz elérhetővé, amelyet a dokumentumon belül mozgat, miközben tartalmat szúr be. A Write(text) és a Writeln(text) szöveget illesztenek be a kurzorhoz; a InsertParagraph() új bekezdést kezd. A builder formázási tulajdonságai — Font, ParagraphFormat, ListFormat, PageSetup — a következő írásra vonatkoznak.

Mozgassa a kurzort a MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) vagy MoveToParagraph(paragraphIndex, characterIndex) segítségével. A builder CurrentNode, CurrentParagraph és CurrentSection tulajdonságai jelentik a jelenlegi pozícióját a fában.

Dokumentum szerkezete: Szakaszok és törzs

Egy Document tartalmaz egy SectionCollection (Document.Sections, plusz FirstSection / LastSection); minden Section egy Body elemmel, egy opcionális fejléc/lábléc gyűjteménnyel és a saját PageSetup értékkel rendelkezik. A Section.AppendContent(sourceSection) és a PrependContent(sourceSection) átmásolja a tartalmat a szakaszok között, a ClearContent() pedig visszaállít egy szakaszt anélkül, hogy eltávolítaná azt a dokumentumból.

Egy Body belsejében a tartalom a Body.Paragraphs (egy ParagraphCollection) és a Body.Tables segítségével érhető el. Egy Range — amely a Document, Section, Paragraph és más csomópontokból elérhető — a fa folytonos területét képviseli; a Range.Text kiolvassa a tiszta szöveget, a Range.Replace(pattern, replacement) pedig csak azon a területen hajt végre keresés-cserét.

A csomópontfa bejárása a DocumentVisitor segítségével

A dokumentum minden része — szakaszok, bekezdések, run, táblázatok, field, shape, comment, footnote — egy Node egy összetett fában, amelynek gyökere a Document. Egy adott típusú összes csomópont feldolgozásához anélkül, hogy kézzel rekurzívan járnánk, származtassa le az absztrakt DocumentVisitor osztályt, és felülírja a szükséges Visit*Start / Visit*End visszahívásokat, például a VisitParagraphStart(paragraph) vagy VisitRun(run) -t, majd hívja meg a document.Accept(visitor) -t. Minden visszahívás visszaadhat egy VisitorAction (Continue, SkipThisNode vagy Stop) értéket, amely szabályozza, hogyan folytatódik a bejárás.

Klónozás, importálás és tartalom hozzáfűzése

Document.Clone() mély másolatot készít egy teljes dokumentumról. Tartalom áthelyezéséhez két különböző Document példány között, hívja a ImportNode(srcNode, isImportChildren)-t a cél dokumentumon, hogy egy csomópontot hozzon be egy idegen fából, vagy hívja a Document.AppendDocument(srcDoc, importFormatMode)-t, hogy egy dokumentum szakaszait egy másikra fűzze egy kiválasztott ImportFormatMode segítségével — KeepSourceFormatting, UseDestinationStyles vagy KeepDifferentStyles. A DocumentBuilder.InsertDocument(srcDoc, importFormatMode) a forrás dokumentum tartalmát a builder kurzoránál helyezi el, nem a cél dokumentum végén.

Dokumentumok védelme

Document.Protect(type, password) korlátozza a szerkesztést egy ProtectionType érték alapján — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields vagy NoProtection a védelem eltávolításához. Unprotect() (jelszóval vagy anélkül) visszavonja ezt. Ez egy Word által kikényszerített szerkesztési korlátozás, amely különbözik az OOXML jelszóval védett titkosítástól, amelyet a OoxmlSaveOptions.Password alkalmaz a fájl mentésekor.

Tippek és bevált gyakorlatok

Előnyben részesítsd a DocumentBuilder használatát új tartalom létrehozásához; válts közvetlen csomópontmanipulációra (AppendChild, InsertAfter, Clone), ha finomabb irányításra van szükséged egy meglévő fa felett.
Hívd meg a FileFormatUtil.DetectFileFormat függvényt a fájl betöltése előtt egy nem megbízható vagy felhasználó által megadott forrásból, hogy ellenőrizhesd a LoadFormat értékét, és időben elutasítsd a nem támogatott vagy titkosított bemenetet.
Dokumentumok összevonásakor a AppendDocument vagy a InsertDocument segítségével válaszd meg tudatosan a ImportFormatMode beállítást — a KeepSourceFormatting megőrzi a forrás megjelenését, a UseDestinationStyles pedig a cél dokumentum stíluskészletéhez igazítja.
Használj DocumentVisitor alosztályt a manuális rekurzív fa bejárás helyett, ha konzisztensen kell feldolgoznod egy csomóponttípus minden példányát.
A Document.Protect egy szerkesztési korlátozás, nem titkosítás — párosítsd a OoxmlSaveOptions.Password elemmel, ha a mentett fájlt magától is jelszóval kell megnyitni.

Gyakori problémák

Probléma	Ok	Javítás
`Document(fileName)` hibát dob egy olyan fájlra, amely Wordben rendben megnyílik	A fájl formátuma nem támogatott ebben a kiadásban a betöltéshez	Először hívd meg a `FileFormatUtil.DetectFileFormat` függvényt, és ellenőrizd a visszakapott `LoadFormat` értéket a betöltés előtt
A hozzáfűzött tartalom rossz betűtípusokat vagy stílusokat vesz fel	`ImportFormatMode` eltérés a forrás és a cél stíluskészletek között	Adj meg `KeepSourceFormatting` vagy `UseDestinationStyles` kifejezetten az alapértelmezett használata helyett
`DocumentVisitor` bejárása korán leáll vagy kihagy tartalmat	Egy `VisitStart` / `VisitEnd` felülbírálás `SkipThisNode` vagy `Stop` értéket ad vissza szándék nélkül	Minden felülbírálásból térj vissza `VisitorAction.Continue` értékkel, kivéve ha kifejezetten a kihagyást vagy leállítást akarod
`Unprotect()` nem jár hatással	A dokumentum nem volt jelszóval védve, vagy helytelen jelszót adtak meg	Hívd meg a(z) `Unprotect()` függvényt argumentumok nélkül, ha a(z) `Protect` jelszó nélkül lett meghívva, egyébként add át a megfelelő jelszót

FAQ

Mi a különbség a `Document.Clone()` és a `ImportNode` között?

Clone() egy teljes dokumentumot másol egy új Document példányba. ImportNode(srcNode, isImportChildren) egyetlen csomópontot (és opcionálisan annak gyermekeit) visz át egy dokumentum fastruktúrájából egy másikba, ami akkor hasznos, ha konkrét tartalmat szeretnél összevonni, nem pedig teljes dokumentumokat.

Milyen fájlformátumokat tud betölteni a `Document(fileName)`?

Document(fileName) betölti a DOCX, DOCM, DOTX, DOTM, Flat OPC (plusz a makróval ellátott és sablonváltozatai) formátumokat, a Markdown-t és az egyszerű szöveget. A régebbi szövegszerkesztő és webes formátumok ki vannak zárva ebből a kiadásból.

Hogyan találhatom meg, hogy egy `DocumentBuilder` jelenleg hol helyezkedik el?

Olvasd a CurrentNode, CurrentParagraph vagy CurrentSection értékét a builder példányban.

A `Document.Protect` titkosítja a mentett fájlt?

Nem — ez a Word által a fájl megnyitásakor érvényesített szerkesztési korlátozás. Ahhoz, hogy csak a megnyitáshoz legyen szükség jelszóra, állítsa be a OoxmlSaveOptions.Password mentéskor.

Hogyan olvashatom csak a dokumentum törzsének bekezdéseit?

Használja a Body.Paragraphs gyűjteményt, vagy Body.GetChildNodes(nodeType, isDeep) más csomóponttípusokhoz.

API Reference összegzés

Osztály/Módszer	Leírás
`Document`	A dokumentumobjektum-modell gyökere; a konstruktorok betöltenek egy fájlból vagy adatfolyamból, vagy üres dokumentumot hoznak létre.
`Document.Save`	A dokumentumot fájlba, adatfolyamba vagy HTTP válaszba írja a kiválasztott formátumban.
`Document.Clone()`	A teljes dokumentum mélymásolatát állítja elő.
`Document.Protect(type, password)` / `Unprotect()`	Szerkesztési korlátozást alkalmaz vagy eltávolít.
`Document.AppendDocument(srcDoc, importFormatMode)`	Hozzáfűzi egy másik dokumentum szakaszait ehhez.
`DocumentBuilder`	Kurzor alapú API a szöveg írásához és a tartalom egy dokumentumba szúrásához.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	A forrásdokumentum tartalmát a kurzorhoz illeszti.
`Section` / `SectionCollection`	Egy dokumentum egyetlen szakasza, valamint az összes szakasz gyűjteménye.
`Body`	A szakasz fő szövegének (bekezdések és táblázatok) tárolója.
`Range`	A dokumentumfa egy összefüggő területe; támogatja a `Text` és a `Replace` elemeket.
`DocumentVisitor`	Absztrakt alaposztály a dokumentumfa minden csomópontjának bejárásához.
`ProtectionType`	Enum a dokumentumszintű szerkesztési korlátozásokhoz.
`FileFormatUtil.DetectFileFormat`	Detektálja a fájl vagy adatfolyam formátumát a betöltés előtt.

Lásd még:

Aspose.Words for .NET — Enterprise Documentation

Dokumentumok kezelése