Arbeiten mit benutzerdefiniertem XML Markup

Arbeiten mit benutzerdefiniertem XML Markup

Dieser Leitfaden zeigt, wie man die benutzerdefinierten XML-Daten, die ein Word-Dokument neben seinem sichtbaren Inhalt tragen kann, liest und verwaltet — Daten, die verwendet werden, um Inhaltssteuerelemente zu binden, anwendungsspezifische Metadaten zu speichern oder beliebige Paketteile einzubetten. Document.CustomXmlParts stellt dokumentenbezogene benutzerdefinierte XML-Daten bereit, und Document.PackageCustomParts stellt paketbezogene benutzerdefinierte Teile bereit, die nicht speziell XML sind.

Benutzerdefinierte XML-Teile

CustomXmlPart repräsentiert eine benutzerdefinierte XML-Dateninsel, die dem Dokument angehängt ist – derselbe Mechanismus, den Word verwendet, um XML-zugeordnete Inhaltssteuerelemente zu unterstützen. Jeder Teil hat ein Id, ein Data-Byte-Array, das das rohe XML enthält, ein DataChecksum und eine Schemas-Eigenschaft (ein CustomXmlSchemaCollection), die die mit ihm verbundenen XML-Schemata auflistet. Document.CustomXmlParts liefert ein CustomXmlPartCollection: Add(part) fügt ein vorhandenes CustomXmlPart hinzu, Add(id, xml) erstellt eines direkt aus einer ID und einem XML-String, GetById(id) ruft ein bestimmtes Teil ab, und RemoveAt(index)/Clear() entfernen Teile. Sowohl CustomXmlPart als auch CustomXmlPartCollection stellen Clone() zum Duplizieren benutzerdefinierter XML-Daten bereit, zum Beispiel beim Kopieren von Inhalten zwischen Dokumenten.

Benutzerdefinierte XML-Schemata

CustomXmlSchemaCollection, erreicht über CustomXmlPart.Schemas, listet die Schema-URIs auf, die mit einem benutzerdefinierten XML-Teil verbunden sind. Es unterstützt Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() und Clone(), zusammen mit einer Count-Eigenschaft – Schema-URIs werden als einfache Zeichenketten und nicht als geparste Schemaobjekte verfolgt.

Benutzerdefinierte XML-Eigenschaften

Separat von CustomXmlPart stellt CustomXmlProperty eine einzelne Namens/Wert-XML-Eigenschaft dar, die mit CustomXmlProperty(name, uri, value) erstellt wird und Name, Uri und Value bereitstellt. CustomXmlPropertyCollection verwaltet eine Menge davon: Add(property) fügt ein hinzu, der Indexer (z.B. properties["MyProp"]) sucht ein nach Namen und Contains(name) prüft, ob es vorhanden ist, IndexOfKey(name) liefert seine Position, und Remove(name)/RemoveAt(index)/Clear() entfernen Einträge. SmartTag.Properties gibt ein CustomXmlPropertyCollection zurück, was die Darstellung der strukturierten Daten eines Legacy-Smart-Tags ist (siehe unten).

Benutzerdefinierte Teile auf Paketebene

Document.PackageCustomParts gibt ein CustomPartCollection von CustomPart-Objekten zurück – beliebige Teile, die im OOXML-Paket gespeichert sind und keine benutzerdefinierten XML-Daten sind, z.B. Teile, die von anderen Anwendungen hinzugefügt wurden, die die Datei berührt haben. Jeder CustomPart hat ein Name, ContentType, RelationshipType, ein Data-Byte-Array und ein IsExternal-Flag, das angibt, ob das Teil eine externe Referenz statt eingebetteten Inhalts ist. Die Sammlung unterstützt Add(part), RemoveAt(index), Clear() und Clone() sowie Count.

Legacy-Smart-Tags

SmartTag ist ein Knotentyp (NodeType.SmartTag), der einen Legacy-Word-Smart-Tag darstellt, der um erkannten Text gewickelt ist. Ein SmartTag wird mit SmartTag(doc) erstellt und stellt Element (den Namen des Erkennerelements) und Uri (den Namensraum des Erkenners) sowie Properties bereit – ein CustomXmlPropertyCollection, das die strukturierten Daten enthält, die der Erkenner dem markierten Text angehängt hat. Da SmartTag ein Knoten ist, nimmt er ebenfalls am Dokumentbaum wie andere Knoten teil und unterstützt Accept(visitor), AcceptStart(visitor) und AcceptEnd(visitor) für eine DocumentVisitor-basierte Traversierung.

MarkupLevel

MarkupLevel ist ein Enum— Unknown, Inline, Block, Row, Cell— das die strukturelle Ebene im Dokumentbaum beschreibt, auf der ein Markup-Element wie ein strukturierter Dokument-Tag auftreten kann.

Tipps und bewährte Vorgehensweisen

• Verwenden Sie CustomXmlPartCollection.GetById(id) anstelle der manuellen Durchiteration der Sammlung, wenn Sie die ID des benötigten Teils kennen.
• Lesen Sie CustomXmlPart.DataChecksum, um zu erkennen, ob sich die zugrunde liegenden XML-Daten geändert haben, ohne einen vollständigen Byte-Vergleich durchzuführen.
• Unterscheiden Sie Document.CustomXmlParts (benutzerdefinierte XML-Daten, häufig an Inhaltssteuerelemente gebunden) von Document.PackageCustomParts (beliebige nicht-XML-Paketteile) — sie dienen unterschiedlichen Zwecken und werden separat gespeichert.
• Wenn Sie mit Legacy-Dokumenten arbeiten, die Smart-Tags verwenden, prüfen Sie SmartTag.Element und Uri gemeinsam, um zu ermitteln, welcher Erkenner die Tag erstellt hat, bevor Sie sich auf dessen Properties verlassen.
• Klone benutzerdefinierte XML-Teile mit CustomXmlPart.Clone() (oder dem Clone() der Sammlung), wenn Sie Daten zwischen Dokumenten kopieren, anstatt das rohe XML erneut zu lesen und hinzuzufügen.

Häufige Probleme

FAQ

Was ist der Unterschied zwischen CustomXmlPart und CustomXmlProperty?

CustomXmlPart ist eine komplette XML-Dateninsel (mit einer Byte-Array-Payload und zugehörigen Schemata), erreichbar über Document.CustomXmlParts. CustomXmlProperty ist ein einzelnes Namens-/Wert-Paar, typischerweise erreichbar über SmartTag.Properties statt direkt aus dem Dokument.

Wie füge ich benutzerdefinierte XML-Daten zu einem Dokument hinzu?

Rufen Sie Document.CustomXmlParts.Add(id, xml) mit einer ID-Zeichenkette und dem XML-Inhalt auf, oder erstellen Sie ein CustomXmlPart separat und übergeben Sie es an Add(part).

Was sind paketbezogene benutzerdefinierte Teile und wie unterscheiden sie sich von benutzerdefinierten XML-Teilen?

Document.PackageCustomParts (ein CustomPartCollection von CustomPart-Objekten) enthält beliebige OOXML-Paketteile, die keine benutzerdefinierten XML sind — jeweils mit einem ContentType, RelationshipType und rohem Data. Document.CustomXmlParts ist speziell für benutzerdefinierte XML-Dateninseln vorgesehen.

Was ist ein SmartTag?

SmartTag ist eine veraltete Word-Funktion, die Text darstellt, der von einem Smart-Tag-Erkenner erkannt und umschlossen wird. Es ist ein Dokumentknoten (NodeType.SmartTag) mit einem Element und Uri, die den Erkenner identifizieren, sowie einer Properties-Sammlung von CustomXmlProperty-Werten, die der Erkenner angehängt hat.

Wie kopiere ich benutzerdefinierte XML-Daten zwischen Dokumenten?

Verwenden Sie CustomXmlPart.Clone() im Quellteil, dann fügen Sie die Kopie zum Document.CustomXmlParts des Zieldokuments mit Add(part) hinzu.

API Reference Zusammenfassung

Siehe auch

• Aspose.Words for .NET — Enterprise Documentation