Arbeiten mit dem Dokumentknotenbaum

Arbeiten mit dem Dokumentknotenbaum

Arbeiten mit dem Dokumenten-Knotenbaum

Dieser Leitfaden zeigt, wie man die Struktur eines Dokuments direkt über seinen Knotenbaum navigiert und manipuliert – das Objektmodell, auf dem Document, Section, Paragraph, Run, Table und jedes andere Dokumentenelement aufgebaut sind. Jedes Element in einem Dokument leitet sich von Node ab, und jedes Element, das Kinder enthalten kann, leitet sich von CompositeNode ab, sodass das Verstehen dieser beiden Basisklassen erklärt, wie man mit Inhalten arbeitet, die kein dedizierter Helfer API bereits abdeckt.


Die Node- und CompositeNode-Basisklassen

Node ist die abstrakte Basisklasse für jedes Objekt in einem Dokumentenbaum. Sie stellt NodeType (einen Enum-Wert, der die Art des Knotens identifiziert), ParentNode (das umschließende CompositeNode), Document (das zugehörige Dokument) sowie PreviousSibling/NextSibling zum Navigieren zwischen Knoten auf derselben Ebene bereit. Node.IsComposite gibt an, ob ein gegebener Knoten Kinder enthalten kann. CompositeNode erweitert Node für Containerelemente – FirstChild, LastChild und Count beschreiben seine unmittelbaren Kinder, und HasChildNodes meldet, ob welche existieren. CompositeNode.GetChildNodes(nodeType, isDeep) ruft alle Kinder eines angegebenen NodeType ab, optional die gesamte Teilbaumstruktur (isDeep) statt nur direkte Kinder durchsuchen, und CompositeNode.GetChild(nodeType, index, isDeep) ruft ein einzelnes Kind nach Index ab.

Das NodeType-Enum

NodeType enumeriert jede Art von Knoten, die das Dokumentenmodell definiert – strukturelle Typen wie Document, Section, Body, Paragraph, Table, Row und Cell; Inline-Inhaltstypen wie Run, Shape und Comment; und Feld-Maschinen-Typen wie FieldStart, FieldSeparator und FieldEnd, die die Grenzen und den Umschalttest eines Word-Feldes im Laufstrom markieren. Die Übergabe eines NodeType-Wertes an GetChildNodes oder GetChild beschränkt die Suche auf Knoten genau dieses Typs, oder übergeben Sie NodeType.Any, um jeden Knotentyp zu treffen.

Durchlaufen und Modifizieren des Baums

CompositeNode.GetEnumerator() ermöglicht das Durchlaufen der direkten Kinder eines Knotens, und CompositeNode implementiert außerdem SelectNodes(xpath) und SelectSingleNode(xpath) für XPath-basierte Abfragen über den gesamten Teilbaum. Um den Baum zu verändern, fügen AppendChild(newChild) und PrependChild(newChild) einen Knoten am Anfang bzw. Ende der Kindknoten hinzu, InsertBefore(newChild, refChild) und InsertAfter(newChild, refChild) fügen relativ zu einem bestehenden Kind ein, und RemoveChild(oldChild) oder RemoveAllChildren() entfernen Knoten. CompositeNode.IndexOf(child) gibt die Position eines Kindes zurück. Auf Node selbst erzeugt Clone(isCloneChildren) eine Kopie – optional tiefgehend – und Remove() löst den Knoten von seinem Elternteil. Node.NextPreOrder(rootNode) und PreviousPreOrder(rootNode) durchlaufen den Baum in Dokumentenreihenfolge, begrenzt durch einen angegebenen Wurzelknoten, was eine gängige Methode ist, einen gesamten Teilbaum Knoten für Knoten ohne rekursiven Code zu scannen.

Knoten-Sammlungen und Änderungsbenachrichtigungen

NodeCollection ist eine konkrete, veränderbare Sammlung von Knoten, die Add(node), Insert(index, node), Remove(node), RemoveAt(index), Clear(), Contains(node), IndexOf(node) und ToArray() unterstützt, zusammen mit einer Count-Eigenschaft. NodeList und NodeEnumerator unterstützen ein lesendes Iterieren über Abfrageergebnisse, wie die von SelectNodes zurückgegebenen Knoten. Um strukturelle Änderungen in Echtzeit zu beobachten, implementieren Sie INodeChangingCallback – seine NodeInserting(args), NodeInserted(args), NodeRemoving(args) und NodeRemoved(args) Methoden erhalten jeweils ein NodeChangingArgs, das den betroffenen Node, dessen OldParent/NewParent und das aufgetretene NodeChangingAction beschreibt.

Knoten besuchen mit DocumentVisitor

Um jeden Knotentyp auf strukturierte Weise zu verarbeiten, ohne den Baum manuell zu durchlaufen, leiten Sie von DocumentVisitor ab und überschreiben die Visit*Start/Visit*End-Methoden für die Knotentypen, die Sie benötigen – VisitParagraphStart/VisitParagraphEnd, VisitTableStart/VisitTableEnd, VisitRun usw. – und rufen anschließend Node.Accept(visitor) an der Wurzel des Teilbaums auf, um ihn auszuführen. Dies ist das Standardmuster zum Exportieren, Transformieren oder Inspizieren eines Dokuments, ohne für jeden Anwendungsfall benutzerdefinierte rekursive Traversierung zu schreiben.


Tipps und bewährte Vorgehensweisen

  • Verwenden Sie NodeType.Any zusammen mit GetChildNodes(NodeType.Any, true), wenn Sie jeden Nachkommen unabhängig vom Typ benötigen, anstatt GetChildNodes einmal pro Typ aufzurufen.
  • Bevorzugen Sie Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode) für einen flachen, nicht-rekursiven Scan eines Teilbaums, anstatt manuell rekursiven Abstieg zu programmieren.
  • Implementieren Sie DocumentVisitor anstelle von ad-hoc-Baumdurchlauf-Code, wenn dieselbe Verarbeitung für viele verschiedene Knotentypen ausgeführt werden muss.
  • Überprüfen Sie Node.IsComposite, bevor Sie zu CompositeNode casten, wenn Sie mit einem Knoten unbekannten Typs arbeiten.
  • Registrieren Sie ein INodeChangingCallback, wenn Sie auf Einfügungen oder Entfernungen reagieren müssen, die von anderem Code (einschließlich eingebauter Operationen) vorgenommen werden, und nicht nur auf Änderungen, die Ihr eigener Code direkt vornimmt.

Häufige Probleme

ProblemUrsacheLösung
Das Casten eines Node zu CompositeNode wirft einen invalid-cast errorDer Knoten ist ein Blatttyp (zum Beispiel Run oder FieldStart), der keine Kinder enthalten kann.Prüfen Sie zuerst Node.IsComposite oder verwenden Sie NodeType, um zu bestätigen, dass der Knoten ein Containertyp ist, bevor Sie casten.
GetChildNodes gibt nur direkte Kinder zurück.isDeep wurde false gelassen (oder weggelassen, wo die Überladung standardmäßig flach ist)Übergeben Sie isDeep: true, um den gesamten Teilbaum zu durchsuchen
Das Ändern einer Sammlung während der Iteration darüber löst einen Fehler aus.Knoten wurden innerhalb eines foreach über NodeCollection oder dem Ergebnis von GetChildNodes hinzugefügt oder entfernt.Materialisieren Sie zuerst die zu ändernden Knoten mit ToArray(), und iterieren Sie dann über das Array, während Sie den Baum verändern.
Eine DocumentVisitor-Unterklasse wird für einige Inhalte nicht aufgerufen.Der Besucher wurde über Accept() an einem Knoten aufgerufen, der den Zielinhalt nicht enthält, oder die entsprechende Visit*-Methode wurde nicht überschrieben.Rufen Sie Accept() an einem Vorfahren auf, der den Inhalt enthält, und überschreiben Sie jedes Visit*Start/Visit*End-Paar, das für die zu verarbeitenden Knotentypen relevant ist.

FAQ

Was ist der Unterschied zwischen Node und CompositeNode?

Node ist die Basisklasse, von der jedes Dokumentelement abgeleitet wird. CompositeNode erweitert Node für Elemente, die Kinder enthalten können (wie Body, Paragraph und Table); Blatt-Elemente (wie Run) leiten direkt von Node ab und können keine Kinder halten.

Wie finde ich alle Knoten eines bestimmten Typs in einem Dokument?

Rufen Sie CompositeNode.GetChildNodes(nodeType, isDeep) auf dem Knoten auf, der Ihre Suche verankert (oft das Document selbst), und übergeben Sie das gewünschte NodeType sowie isDeep: true, um den gesamten Unterbaum zu durchsuchen, nicht nur direkte Kinder.

Wie entferne ich Knoten sicher beim Durchlaufen?

Sammeln Sie die zu entfernenden Knoten zuerst in einem Array – zum Beispiel mit NodeCollection.ToArray() – und iterieren Sie dann über dieses Array und rufen Remove() für jeden Knoten auf, anstatt die aktive Sammlung zu verändern, während ein foreach sie durchläuft.

Was sind FieldStart, FieldSeparator und FieldEnd Knoten?

Sie sind NodeType-Werte, die die Funktionsweise eines in den Laufstrom eingebetteten Word-Feldes kennzeichnen: FieldStart und FieldEnd begrenzen das Feld, und FieldSeparator trennt den Feldcode von seinem derzeit angezeigten Ergebnis.

Wie verarbeite ich jeden Absatz, jede Tabelle und jeden Lauf in einem Dokument?

Erstellen Sie eine Unterklasse von DocumentVisitor, überschreiben Sie VisitParagraphStart/VisitParagraphEnd, VisitTableStart/VisitTableEnd und VisitRun für die benötigten Knotentypen und rufen Sie anschließend Accept(visitor) auf dem Document (oder irgendeinem Unterbaum-Wurzelknoten) auf, um ihn auszuführen.


API Reference Zusammenfassung

Klasse/MethodeBeschreibung
NodeAbstrakte Basisklasse für jeden Knoten in einem Dokumentbaum
CompositeNodeBasisklasse für Knoten, die Kinder enthalten können
CompositeNode.GetChildNodes(nodeType, isDeep)Alle Kinder eines bestimmten Typs abrufen, optional über den gesamten Unterbaum hinweg
CompositeNode.AppendChild(newChild) / InsertBefore(newChild, refChild)Einen Knoten an das Ende eines Containers hinzufügen oder vor/nach einem bestehenden Kind
NodeTypeEnum, das die Art eines Knotens identifiziert (Paragraph, Table, Run, FieldStart und so weiter)
NodeCollectionKonkrete, veränderliche Sammlung von Node-Objekten
Node.Clone(isCloneChildren)Kopiere einen Knoten, optional einschließlich seiner Kinder
Node.NextPreOrder(rootNode) / PreviousPreOrder(rootNode)Durchlaufe einen Teilbaum in Dokumentreihenfolge
INodeChangingCallbackCallback-Schnittstelle, die benachrichtigt wird, wenn Knoten eingefügt oder entfernt werden
DocumentVisitorBasisklasse für strukturierte, typgesteuerte Traversierung über Node.Accept(visitor)

Siehe auch

 Deutsch