Werken met aangepaste XML Markup

Werken met aangepaste XML opmaak

Deze gids laat zien hoe je de aangepaste XML gegevens die een Word-document naast de zichtbare inhoud kan bevatten, kunt lezen en beheren — gegevens die worden gebruikt om inhoudsbesturingselementen te binden, toepassingsspecifieke metadata op te slaan, of willekeurige pakketonderdelen in te sluiten. Document.CustomXmlParts maakt aangepaste XML gegevens op documentniveau toegankelijk, en Document.PackageCustomParts maakt aangepaste onderdelen op pakketteniveau toegankelijk die niet specifiek XML zijn.

Aangepaste XML onderdelen

CustomXmlPart vertegenwoordigt één aangepaste XML data-eiland dat aan het document is gekoppeld — hetzelfde mechanisme dat Word gebruikt om XML-gemapte inhoudsbesturingselementen te ondersteunen. Elk onderdeel heeft een Id, een Data byte-array die de ruwe XML bevat, een DataChecksum, en een Schemas eigenschap (een CustomXmlSchemaCollection) die de XML schema’s vermeldt die ermee geassocieerd zijn. Document.CustomXmlParts retourneert een CustomXmlPartCollection: Add(part) koppelt een bestaande CustomXmlPart, Add(id, xml) maakt er één direct aan vanuit een id en XML tekenreeks, GetById(id) haalt een specifiek onderdeel op, en RemoveAt(index)/Clear() verwijderen onderdelen. Zowel CustomXmlPart als CustomXmlPartCollection maken Clone() beschikbaar voor het dupliceren van aangepaste XML gegevens, bijvoorbeeld bij het kopiëren van inhoud tussen documenten.

Aangepaste XML schema’s

CustomXmlSchemaCollection, bereikt via CustomXmlPart.Schemas, geeft een lijst weer van de schema-URI’s die aan een aangepast XML onderdeel zijn gekoppeld. Het ondersteunt Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() en Clone(), naast een Count eigenschap — schema-URI’s worden bijgehouden als gewone tekenreeksen in plaats van geparseerde schema-objecten.

Aangepaste XML eigenschappen

Afzonderlijk van CustomXmlPart vertegenwoordigt CustomXmlProperty een enkele naam/waarde XML eigenschap, opgebouwd met CustomXmlProperty(name, uri, value) en die Name, Uri en Value blootlegt. CustomXmlPropertyCollection beheert een set hiervan: Add(property) voegt er één toe, de indexer (bijv. properties["MyProp"]) zoekt er één op basis van naam en Contains(name) test of deze aanwezig is, IndexOfKey(name) geeft de positie terug, en Remove(name)/RemoveAt(index)/Clear() verwijderen items. SmartTag.Properties retourneert een CustomXmlPropertyCollection, waarmee de gestructureerde gegevens van een legacy smart tag worden weergegeven (zie hieronder).

Aangepaste onderdelen op pakketteniveau

Document.PackageCustomParts retourneert een CustomPartCollection van CustomPart objecten — willekeurige onderdelen die zijn opgeslagen in het OOXML-pakket en geen aangepaste XML gegevens zijn, zoals onderdelen die door andere applicaties zijn toegevoegd die het bestand hebben bewerkt. Elk CustomPart heeft een Name, ContentType, RelationshipType, een Data byte-array en een IsExternal vlag die aangeeft of het onderdeel een externe referentie is in plaats van ingesloten inhoud. De collectie ondersteunt Add(part), RemoveAt(index), Clear() en Clone(), naast Count.

Legacy smart tags

SmartTag is een node-type (NodeType.SmartTag) dat een legacy Word smart tag vertegenwoordigt die rond herkende tekst is gewikkeld. Een SmartTag wordt geconstrueerd met SmartTag(doc) en maakt Element (de naam van het herkenner-element) en Uri (de namespace van de herkenner) bloot, naast Properties — een CustomXmlPropertyCollection dat de gestructureerde gegevens bevat die de herkenner aan de getagde tekst heeft toegevoegd. Omdat SmartTag een node is, neemt het ook deel in de documentboom zoals andere nodes, en ondersteunt het Accept(visitor), AcceptStart(visitor) en AcceptEnd(visitor) voor DocumentVisitor-gebaseerde traversie.

MarkupLevel

MarkupLevel is een enum — Unknown, Inline, Block, Row, Cell — die het structurele niveau beschrijft in de documentboom waarop een opmaak-element zoals een gestructureerde document-tag kan voorkomen.

Tips en best practices

• Gebruik CustomXmlPartCollection.GetById(id) in plaats van de collectie handmatig te itereren wanneer je de id van het onderdeel dat je nodig hebt kent.
• Lees CustomXmlPart.DataChecksum om te detecteren of de onderliggende XML-gegevens zijn gewijzigd zonder een volledige byte-vergelijking uit te voeren.
• Maak onderscheid tussen Document.CustomXmlParts (aangepaste XML-gegevens, vaak gekoppeld aan inhoudsbesturingselementen) en Document.PackageCustomParts (willekeurige niet-XML-pakketonderdelen) — ze dienen verschillende doeleinden en worden afzonderlijk opgeslagen.
• Wanneer je werkt met legacy-documenten die slimme tags gebruiken, controleer dan SmartTag.Element en Uri samen om te identificeren welke herkenner de tag heeft gemaakt voordat je vertrouwt op zijn Properties.
• Kloon aangepaste XML-onderdelen met CustomXmlPart.Clone() (of met de Clone() van de collectie) bij het kopiëren van gegevens tussen documenten in plaats van de ruwe XML opnieuw te lezen en toe te voegen.

Veelvoorkomende problemen

FAQ

Wat is het verschil tussen CustomXmlPart en CustomXmlProperty?

CustomXmlPart is een volledige XML data-eiland (met een byte-array payload en bijbehorende schema’s), bereikt via Document.CustomXmlParts. CustomXmlProperty is een enkel naam/waarde-paar, meestal bereikt via SmartTag.Properties in plaats van direct uit het document.

Hoe voeg ik aangepaste XML data toe aan een document?

Roep Document.CustomXmlParts.Add(id, xml) aan met een id-string en de XML inhoud, of bouw een CustomXmlPart apart en geef die door aan Add(part).

Wat zijn pakket-aangepaste onderdelen, en hoe verschillen ze van aangepaste XML onderdelen?

Document.PackageCustomParts (een CustomPartCollection van CustomPart objecten) bevat willekeurige OOXML-pakketonderdelen die geen aangepaste XML zijn — elk met een ContentType, RelationshipType, en ruwe Data. Document.CustomXmlParts is specifiek voor aangepaste XML data-eilanden.

Wat is een SmartTag?

SmartTag is een legacy Word-functie die tekst vertegenwoordigt die wordt herkend en omhuld door een smart-tag-herkenner. Het is een documentknooppunt (NodeType.SmartTag) met een Element en Uri die de herkenner identificeren, en een Properties verzameling van CustomXmlProperty waarden die de herkenner heeft toegevoegd.

Hoe kopieer ik aangepaste XML data tussen documenten?

Gebruik CustomXmlPart.Clone() op het brononderdeel, voeg vervolgens de kloon toe aan de Document.CustomXmlParts van het doeldocument met Add(part).

API Reference Samenvatting

Zie ook

• Aspose.Words for .NET — Enterprise Documentation