Arbeiten mit Dokumenten

Aspose.Words FOSS für .NET stellt jede Word-Datei als ein im Speicher befindliches Objektmodell dar, das in der Document-Klasse verwurzelt ist, wobei DocumentBuilder ein hochrangiges, cursorbasiertes API zum Erstellen von Inhalten bereitstellt. Dieser Leitfaden behandelt das Erstellen und Laden von Dokumenten, das Autorisieren mit DocumentBuilder, die Abschnitt-/Körperstruktur, das Durchlaufen des Knotensbaums, das Kombinieren von Dokumenten und deren Schutz.

Erstellen und Laden von Dokumenten

Erstellen Sie ein leeres Dokument mit new Document() oder öffnen Sie eine vorhandene Datei, indem Sie einen Pfad oder Stream an den Konstruktor von Document(fileName) bzw. Document(stream) übergeben. Überladungen, die ein LoadOptions-Argument akzeptieren, ermöglichen die Steuerung des Ladevorgangs, z.B. das Bereitstellen eines Passworts für eine verschlüsselte Datei.

Bevor Sie eine Datei aus einer unbekannten oder nicht vertrauenswürdigen Quelle laden, gibt FileFormatUtil.DetectFileFormat(fileName) (oder die Stream-Überladung) ein FileFormatInfo zurück, das die erkannte LoadFormat beschreibt und angibt, ob die Datei IsEncrypted, HasDigitalSignature oder HasMacros ist.

Erstellung mit DocumentBuilder

DocumentBuilder umschließt ein Document und stellt einen Cursor bereit, den Sie durch das Dokument bewegen, während Sie Inhalte einfügen. Write(text) und Writeln(text) fügen Text am Cursor ein; InsertParagraph() startet einen neuen Absatz. Formatierungseigenschaften am Builder — Font, ParagraphFormat, ListFormat, PageSetup — gelten für alles, was anschließend geschrieben wird.

Bewegen Sie den Cursor mit MoveToDocumentStart(), MoveToDocumentEnd(), MoveToSection(sectionIndex), MoveToBookmark(bookmarkName) oder MoveToParagraph(paragraphIndex, characterIndex). Die CurrentNode, CurrentParagraph und CurrentSection Eigenschaften des Builders geben seine aktuelle Position im Baum an.

Dokumentstruktur: Abschnitte und Body

Ein Document enthält ein SectionCollection (Document.Sections, plus FirstSection / LastSection); jeder Section hat ein Body, eine optionale Kopf-/Fußzeilen-Sammlung und sein eigenes PageSetup. Section.AppendContent(sourceSection) und PrependContent(sourceSection) kopieren Inhalte zwischen Abschnitten, und ClearContent() setzt einen Abschnitt zurück, ohne ihn aus dem Dokument zu entfernen.

Innerhalb eines Body wird Inhalt über Body.Paragraphs (ein ParagraphCollection) und Body.Tables bereitgestellt. Ein Range – verfügbar von Document, Section, Paragraph und anderen Knoten – stellt einen zusammenhängenden Bereich des Baumes dar; Range.Text liest dessen Klartext und Range.Replace(pattern, replacement) führt eine Suchen-und-Ersetzen-Operation ausschließlich in diesem Bereich aus.

Durchlaufen des Knotenbaums mit DocumentVisitor

Jeder Teil eines Dokuments — Abschnitte, Absätze, Runs, Tabellen, Felder, Formen, Kommentare, Fußnoten — ist ein Node in einem zusammengesetzten Baum, dessen Wurzel Document ist. Um jeden Knoten eines bestimmten Typs zu verarbeiten, ohne manuell zu rekursieren, leiten Sie die abstrakte DocumentVisitor ab und überschreiben die Visit*Start/Visit*End Callback-Funktionen, die Sie benötigen, z.B. VisitParagraphStart(paragraph) oder VisitRun(run), und rufen dann document.Accept(visitor) auf. Jeder Callback kann ein VisitorAction (Continue, SkipThisNode oder Stop) zurückgeben, um zu steuern, wie die Traversierung fortschreitet.

Klonen, Importieren und Anhängen von Inhalten

Document.Clone() erzeugt eine tiefe Kopie eines gesamten Dokuments. Um Inhalte zwischen zwei verschiedenen Document-Instanzen zu verschieben, rufen Sie ImportNode(srcNode, isImportChildren) im Ziel-Dokument auf, um einen Knoten aus einem fremden Baum einzufügen, oder rufen Sie Document.AppendDocument(srcDoc, importFormatMode) auf, um die Abschnitte eines Dokuments an ein anderes anzuhängen, wobei ein gewähltes ImportFormatMode – KeepSourceFormatting, UseDestinationStyles oder KeepDifferentStyles – verwendet wird. DocumentBuilder.InsertDocument(srcDoc, importFormatMode) fügt den Inhalt des Quelldokuments an der Position des Builders-Cursors ein, anstatt am Ende des Ziels.

Dokumente schützen

Document.Protect(type, password) schränkt die Bearbeitung gemäß einem ProtectionType-Wert ein — ReadOnly, AllowOnlyComments, AllowOnlyRevisions, AllowOnlyFormFields oder NoProtection, um den Schutz zu entfernen. Unprotect() (mit oder ohne Passwort) hebt dies auf. Dies ist eine von Word erzwungene Bearbeitungseinschränkung, die von der OOXML-Passwortverschlüsselung getrennt ist, die OoxmlSaveOptions.Password beim Speichern einer Datei anwendet.

Tipps und bewährte Vorgehensweisen

Bevorzuge DocumentBuilder zum Erstellen neuer Inhalte; greife auf direkte Knotenmanipulation (AppendChild, InsertAfter, Clone) zurück, wenn du feine Kontrolle über einen bestehenden Baum benötigst.
Rufe FileFormatUtil.DetectFileFormat auf, bevor du eine Datei aus einer nicht vertrauenswürdigen oder benutzergenerierten Quelle lädst, damit du LoadFormat prüfen und nicht unterstützte oder verschlüsselte Eingaben frühzeitig ablehnen kannst.
Beim Kombinieren von Dokumenten mit AppendDocument oder InsertDocument wähle das ImportFormatMode bewusst — KeepSourceFormatting bewahrt das Aussehen der Quelle, UseDestinationStyles passt den Stil des Zieldokuments an.
Verwende eine DocumentVisitor-Unterklasse anstelle von manuellem rekursivem Durchlaufen des Baums, wenn du jede Instanz eines Knotentyps konsistent verarbeiten musst.
Document.Protect ist eine Bearbeitungseinschränkung, keine Verschlüsselung — kombiniere es mit OoxmlSaveOptions.Password, wenn die gespeicherte Datei selbst ein Passwort zum Öffnen erfordern soll.

Häufige Probleme

Problem	Ursache	Lösung
`Document(fileName)` wirft bei einer Datei, die in Word einwandfrei geöffnet wird	Das Dateiformat wird von dieser Edition zum Laden nicht unterstützt	Rufen Sie zuerst `FileFormatUtil.DetectFileFormat` auf und prüfen Sie das zurückgegebene `LoadFormat`, bevor Sie laden
Angefügter Inhalt übernimmt die falschen Schriftarten oder Stile	`ImportFormatMode` Diskrepanz zwischen den Quell- und Ziel-Style-Sets	Geben Sie `KeepSourceFormatting` oder `UseDestinationStyles` explizit an, anstatt sich auf einen Standardwert zu verlassen
`DocumentVisitor`-Durchlauf stoppt frühzeitig oder überspringt Inhalt	Ein `VisitStart` / `VisitEnd`-Override gibt `SkipThisNode` oder `Stop` unbeabsichtigt zurück	Geben Sie `VisitorAction.Continue` von jedem Override zurück, es sei denn, Sie beabsichtigen ausdrücklich zu überspringen oder zu stoppen
`Unprotect()` hat keine Wirkung	Das Dokument war nicht mit einem Passwort geschützt, oder das falsche Passwort wurde angegeben	Rufen Sie `Unprotect()` ohne Argumente auf, wenn `Protect` ohne Passwort aufgerufen wurde, andernfalls übergeben Sie das passende Passwort

FAQ

Was ist der Unterschied zwischen `Document.Clone()` und `ImportNode`?

Clone() kopiert ein ganzes Dokument in eine neue Document-Instanz. ImportNode(srcNode, isImportChildren) bringt einen einzelnen Knoten (und optional dessen Kinder) vom Baum eines Dokuments in ein anderes, was Sie verwenden, wenn Sie spezifische Inhalte statt ganzer Dokumente kombinieren.

Welche Dateiformate kann `Document(fileName)` laden?

Document(fileName) lädt DOCX, DOCM, DOTX, DOTM, Flat OPC (plus die makroaktivierten und Vorlagen-Varianten), Markdown und Klartext. Ältere Textverarbeitungs- und Webformate sind in den Loadern dieser Ausgabe ausgeschlossen.

Wie finde ich heraus, wo ein `DocumentBuilder` gerade positioniert ist?

Lesen Sie CurrentNode, CurrentParagraph oder CurrentSection in der Builder-Instanz.

Verschlüsselt `Document.Protect` die gespeicherte Datei?

Nein — es ist eine Bearbeitungseinschränkung, die von Word beim Öffnen der Datei durchgesetzt wird. Um ein Passwort nur zum Öffnen der Datei zu verlangen, setzen Sie OoxmlSaveOptions.Password beim Speichern.

Wie lese ich nur die Absätze im Dokumentkörper?

Verwenden Sie die Body.Paragraphs-Sammlung oder Body.GetChildNodes(nodeType, isDeep) für andere Knotentypen.

API Reference Zusammenfassung

Klasse/Methode	Beschreibung
`Document`	Wurzel des Document Object Model; Konstruktoren laden aus einer Datei oder einem Stream oder erstellen ein leeres Dokument.
`Document.Save`	Schreibt das Dokument in eine Datei, einen Stream oder eine HTTP-Antwort im gewählten Format.
`Document.Clone()`	Erzeugt eine tiefe Kopie des gesamten Dokuments.
`Document.Protect(type, password)` / `Unprotect()`	Wendet eine Bearbeitungsbeschränkung an oder entfernt sie.
`Document.AppendDocument(srcDoc, importFormatMode)`	Fügt die Abschnitte eines anderen Dokuments zu diesem hinzu.
`DocumentBuilder`	Cursor-basierte API zum Schreiben von Text und Einfügen von Inhalten in ein Dokument.
`DocumentBuilder.InsertDocument(srcDoc, importFormatMode)`	Fügt den Inhalt eines Quelldokuments am Cursor ein.
`Section` / `SectionCollection`	Ein einzelner Abschnitt eines Dokuments und die Sammlung aller Abschnitte.
`Body`	Container für den Haupttext (Absätze und Tabellen) eines Abschnitts.
`Range`	Ein zusammenhängender Bereich des Dokumentbaums; unterstützt `Text` und `Replace`.
`DocumentVisitor`	Abstrakte Basisklasse zum Durchlaufen jedes Knotens im Dokumentbaum.
`ProtectionType`	Enum der bearbeitungsbezogenen Einschränkungen auf Dokumentebene.
`FileFormatUtil.DetectFileFormat`	Ermittelt das Format einer Datei oder eines Streams, bevor sie geladen wird.

Siehe auch

Aspose.Words for .NET — Enterprise Documentation

Arbeiten mit Dokumenten