Práce s dokumenty

Aspose.Words FOSS pro .NET představuje každý soubor Word jako model objektů v paměti, jehož kořenovou třídou je Document, přičemž DocumentBuilder poskytuje vysoceúrovňové, kurzorové API pro tvorbu obsahu. Tento průvodce pokrývá vytváření a načítání dokumentů, tvorbu pomocí DocumentBuilder, strukturu sekce/těla, procházení stromu uzlů, kombinování dokumentů a jejich ochranu.

Vytváření a načítání dokumentů

Vytvořte prázdný dokument pomocí new Document() nebo otevřete existující soubor předáním cesty nebo Stream do konstruktoru Document(fileName) nebo Document(stream). Přetížení, která přijímají argument LoadOptions, vám umožní řídit chování načítání, například zadáním hesla pro šifrovaný soubor.

Před načtením souboru z neznámého nebo nedůvěryhodného zdroje FileFormatUtil.DetectFileFormat(fileName) (nebo přetížení Stream) vrací FileFormatInfo popisující detekovaný LoadFormat a zda je soubor IsEncrypted, HasDigitalSignature nebo HasMacros.

Tvorba pomocí DocumentBuilder

DocumentBuilder obaluje Document a zveřejňuje kurzor, který přesouváte dokumentem při vkládání obsahu. Write(text) a Writeln(text) vkládají text na kurzor; InsertParagraph() zahajuje nový odstavec. Formátovací vlastnosti na builderu — Font, ParagraphFormat, ListFormat, PageSetup — se vztahují na vše, co je následně napsáno.

Posuňte kurzor pomocí MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) nebo MoveToParagraph(paragraphIndex, characterIndex). Vlastnosti CurrentNode, CurrentParagraph a CurrentSection builderu uvádějí jeho aktuální pozici ve stromu.

Struktura dokumentu: sekce a tělo

Document obsahuje SectionCollection (Document.Sections, plus FirstSection / LastSection); každý Section má jeden Body, volitelnou kolekci záhlaví/patiček a svůj vlastní PageSetup. Section.AppendContent(sourceSection) a PrependContent(sourceSection) kopírují obsah mezi sekcemi a ClearContent() resetuje sekci, aniž by ji odstranil z dokumentu.

V rámci Body je obsah zpřístupněn přes Body.Paragraphs (a ParagraphCollection) a Body.Tables. Range — dostupný z Document, Section, Paragraph a dalších uzlů — představuje souvislou oblast stromu; Range.Text načte jeho prostý text a Range.Replace(pattern, replacement) provede najdi-a-nahraď jen v této oblasti.

Procházení stromu uzlů pomocí DocumentVisitor

Každá část dokumentu — sekce, odstavce, běhy, tabulky, pole, tvary, komentáře, poznámky pod čarou — je Node v kompozitním stromu s kořenem v Document. Chcete-li zpracovat každý uzel daného typu bez ruční rekurze, vytvořte podtřídu abstraktního DocumentVisitor a přepište potřebné callbacky Visit*Start / Visit*End, jako například VisitParagraphStart(paragraph) nebo VisitRun(run), a pak zavolejte document.Accept(visitor). Každý callback může vrátit VisitorAction (Continue, SkipThisNode nebo Stop) pro řízení průběhu procházení.

Klonování, importování a připojování obsahu

Document.Clone() vytváří hlubokou kopii celého dokumentu. Pro přesunutí obsahu mezi dvěma různými instancemi Document zavolejte ImportNode(srcNode, isImportChildren) na cílovém dokumentu, aby se přinesl uzel ze cizího stromu, nebo zavolejte Document.AppendDocument(srcDoc, importFormatMode) k připojení sekcí jednoho dokumentu k druhému pomocí zvoleného ImportFormatMode — KeepSourceFormatting, UseDestinationStyles nebo KeepDifferentStyles. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) vloží obsah zdrojového dokumentu na kurzor builderu místo na konec cílového.

Ochrana dokumentů

Document.Protect(type, password) omezuje úpravy podle hodnoty ProtectionType — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields nebo NoProtection pro odebrání ochrany. Unprotect() (s nebo bez hesla) to vrátí zpět. Jedná se o omezení úprav vynucené aplikací Word, oddělené od šifrování heslem OOXML, které OoxmlSaveOptions.Password použije při ukládání souboru.

Tipy a osvědčené postupy

Upřednostněte DocumentBuilder při vytváření nového obsahu; přejděte na přímou manipulaci s uzly (AppendChild, InsertAfter, Clone), když potřebujete jemnou kontrolu nad existujícím stromem.
Zavolejte FileFormatUtil.DetectFileFormat před načtením souboru z nedůvěryhodného nebo uživatelem dodaného zdroje, abyste mohli zkontrolovat LoadFormat a včas odmítnout nepodporovaný nebo šifrovaný vstup.
Při kombinování dokumentů pomocí AppendDocument nebo InsertDocument vyberte ImportFormatMode úmyslně — KeepSourceFormatting zachovává vzhled zdroje, UseDestinationStyles odpovídá sadě stylů cílového dokumentu.
Použijte podtřídu DocumentVisitor místo ručního rekurzivního procházení stromu, pokud potřebujete konzistentně zpracovat každou instanci typu uzlu.
Document.Protect je omezení úprav, nikoli šifrování — kombinujte ho s OoxmlSaveOptions.Password, pokud samotný uložený soubor musí vyžadovat heslo pro otevření.

Časté problémy

Problém	Příčina	Oprava
`Document(fileName)` vyhodí výjimku u souboru, který se v aplikaci Word otevře v pořádku	Formát souboru není podporován touto edicí pro načítání	Nejprve zavolejte `FileFormatUtil.DetectFileFormat` a před načtením zkontrolujte vrácený `LoadFormat`
Připojený obsah převzal nesprávná písma nebo styly	`ImportFormatMode` neshoda mezi zdrojovými a cílovými sadami stylů	Předávejte `KeepSourceFormatting` nebo `UseDestinationStyles` explicitně místo spoléhaní se na výchozí
`DocumentVisitor` průchod se zastaví předčasně nebo přeskočí obsah	Přepsání `VisitStart` / `VisitEnd` vrací `SkipThisNode` nebo `Stop` neúmyslně	Vraťte `VisitorAction.Continue` z každého přepsání, pokud výslovně neplánujete přeskočit nebo zastavit
`Unprotect()` nemá žádný efekt	Dokument nebyl chráněn heslem, nebo bylo zadáno nesprávné heslo	Zavolejte `Unprotect()` bez argumentů, pokud bylo `Protect` voláno bez hesla, jinak předávejte odpovídající heslo

FAQ

Jaký je rozdíl mezi `Document.Clone()` a `ImportNode`?

Clone() zkopíruje celý dokument do nové instance Document. ImportNode(srcNode, isImportChildren) přenese jeden uzel (a volitelně i jeho podřízené) ze stromu jednoho dokumentu do druhého, což je to, co použijete při kombinování konkrétního obsahu místo celých dokumentů.

Jaké souborové formáty může `Document(fileName)` načíst?

Document(fileName) načítá DOCX, DOCM, DOTX, DOTM, Flat OPC (včetně jeho variant s makry a šablon), Markdown a prostý text. Starší formáty pro zpracování textu a webové formáty jsou z této verze načítačů vyloučeny.

Jak zjistím, kde je `DocumentBuilder` aktuálně umístěn?

Přečtěte CurrentNode, CurrentParagraph nebo CurrentSection na instanci builderu.

Šifruje `Document.Protect` uložený soubor?

Ne — jedná se o omezení úprav vynucované aplikací Word při otevření souboru. Chcete-li vyžadovat heslo jen pro otevření souboru, nastavte OoxmlSaveOptions.Password při ukládání.

Jak mohu přečíst jen odstavce v těle dokumentu?

Použijte kolekci Body.Paragraphs nebo Body.GetChildNodes(nodeType, isDeep) pro jiné typy uzlů.

API Reference Shrnutí

Třída/Metoda	Popis:
`Document`	Kořen modelu objektů dokumentu; konstruktory načítají ze souboru nebo proudu, nebo vytvoří prázdný dokument.
`Document.Save`	Zapíše dokument do souboru, proudu nebo HTTP odpovědi ve zvoleném formátu.
`Document.Clone()`	Vytvoří hlubokou kopii celého dokumentu.
`Document.Protect(type, password)` / `Unprotect()`	Použije nebo odstraní omezení úprav.
`Document.AppendDocument(srcDoc, importFormatMode)`	Připojí sekce jiného dokumentu k tomuto.
`DocumentBuilder`	Kurzorové API pro psaní textu a vkládání obsahu do dokumentu.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Vloží obsah zdrojového dokumentu na pozici kurzoru.
`Section` / `SectionCollection`	Jedna sekce dokumentu a sbírka všech sekcí.
`Body`	Kontejner pro hlavní text (odstavce a tabulky) sekce.
`Range`	Souvislá oblast stromu dokumentu; podporuje `Text` a `Replace`.
`DocumentVisitor`	Abstraktní základní třída pro procházení každého uzlu ve stromu dokumentu.
`ProtectionType`	Výčet omezení úprav na úrovni dokumentu.
`FileFormatUtil.DetectFileFormat`	Detekuje formát souboru nebo proudu před jeho načtením.

Viz také:

Aspose.Words for .NET — Enterprise Documentation

Práce s dokumenty