Lucrul cu markup XML personalizat

Lucrul cu markup personalizat XML

Acest ghid arată cum să citești și să gestionezi datele personalizate XML pe care un document Word le poate transporta alături de conținutul său vizibil — date utilizate pentru a lega controalele de conținut, pentru a stoca metadate specifice aplicației sau pentru a încorpora părți arbitrare ale pachetului. Document.CustomXmlParts expune datele personalizate XML la nivel de document, iar Document.PackageCustomParts expune părțile personalizate la nivel de pachet care nu sunt în mod specific XML.

Părți personalizate XML

CustomXmlPart reprezintă o insulă de date XML personalizată atașată documentului — același mecanism pe care Word îl folosește pentru a susține controalele de conținut mapate la XML. Fiecare parte are un Id, un tablou de octeți Data care conține XML brut, un DataChecksum, și o proprietate Schemas (un CustomXmlSchemaCollection) care enumeră schemele XML asociate. Document.CustomXmlParts returnează un CustomXmlPartCollection: Add(part) atașează un CustomXmlPart existent, Add(id, xml) creează unul direct dintr-un id și un șir XML, GetById(id) recuperează o parte specifică, iar RemoveAt(index)/Clear() elimină părțile. Atât CustomXmlPart, cât și CustomXmlPartCollection expun Clone() pentru duplicarea datelor XML personalizate, de exemplu când se copiază conținut între documente.

Scheme personalizate XML

CustomXmlSchemaCollection, accesat prin CustomXmlPart.Schemas, enumeră URI-urile schemelor asociate unei părți XML personalizate. Acesta suportă Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() și Clone(), alături de o proprietate Count — URI-urile schemelor sunt urmărite ca șiruri simple în loc de obiecte schemă parsate.

Proprietăți personalizate XML

Separat de CustomXmlPart, CustomXmlProperty reprezintă o singură proprietate XML de tip nume/valoare, construită cu CustomXmlProperty(name, uri, value) și expune Name, Uri și Value. CustomXmlPropertyCollection administrează un set de astfel de elemente: Add(property) adaugă una, indexatorul (de ex. properties["MyProp"]) caută una după nume și Contains(name) verifică dacă este prezentă, IndexOfKey(name) returnează poziția ei, iar Remove(name)/RemoveAt(index)/Clear() elimină intrările. SmartTag.Properties returnează un CustomXmlPropertyCollection, care este modul în care datele structurate ale unui smart tag legacy sunt reprezentate (vezi mai jos).

Părți personalizate la nivel de pachet

Document.PackageCustomParts returnează un CustomPartCollection de obiecte CustomPart — părți arbitrare stocate în pachetul OOXML care nu sunt date XML personalizate, cum ar fi părți adăugate de alte aplicații care au modificat fișierul. Fiecare CustomPart are un Name, ContentType, RelationshipType, un tablou de octeți Data și un indicator IsExternal care indică dacă partea este o referință externă în loc de conținut încorporat. Colecția suportă Add(part), RemoveAt(index), Clear() și Clone(), alături de Count.

Etichete inteligente moștenite

SmartTag este un tip de nod (NodeType.SmartTag) care reprezintă o etichetă inteligentă Word moștenită învelită în jurul textului recunoscut. Un SmartTag este construit cu SmartTag(doc) și expune Element (numele elementului recunoaștor) și Uri (spațiul de nume al recunoaștorului), alături de Properties — un CustomXmlPropertyCollection care conține datele structurate pe care recunoaștorul le-a atașat textului etichetat. Deoarece SmartTag este un nod, participă și el în arborele documentului ca și celelalte noduri, suportând Accept(visitor), AcceptStart(visitor) și AcceptEnd(visitor) pentru traversare bazată pe DocumentVisitor.

MarkupLevel

MarkupLevel este o enumerare — Unknown, Inline, Block, Row, Cell — care descrie nivelul structural din arborele documentului la care poate apărea un element de marcare, cum ar fi o etichetă de document structurat.

Sfaturi și practici recomandate

• Folosește CustomXmlPartCollection.GetById(id) în loc să iterezi manual colecția când știi id-ul părții de care ai nevoie.
• Citește CustomXmlPart.DataChecksum pentru a detecta dacă datele XML subiacente s-au modificat fără a efectua o comparație completă pe octeți.
• Distinge Document.CustomXmlParts (date XML personalizate, adesea legate de controalele de conținut) de Document.PackageCustomParts (părți de pachet arbitrare, ne-XML) — ele servesc scopuri diferite și sunt stocate separat.
• Când lucrezi cu documente vechi care utilizează etichete inteligente, verifică SmartTag.Element și Uri împreună pentru a identifica care recunoaștere a creat eticheta înainte de a te baza pe Properties.
• Clonează părțile XML personalizate cu CustomXmlPart.Clone() (sau cu Clone() al colecției) când copiezi date între documente în loc să citești din nou și să adaugi datele brute XML.

Probleme comune

FAQ

Care este diferența dintre CustomXmlPart și CustomXmlProperty?

CustomXmlPart este o insulă de date XML completă (cu un payload sub formă de tablou de octeţi şi scheme asociate), accesată prin Document.CustomXmlParts. CustomXmlProperty este o pereche nume/valoare unică, de obicei accesată prin SmartTag.Properties mai degrabă decât direct din document.

Cum pot adăuga date XML personalizate într-un document?

Apelă Document.CustomXmlParts.Add(id, xml) cu un şir de identificare şi conținutul XML, sau construiește un CustomXmlPart separat şi transmite-l lui Add(part).

Ce sunt părțile personalizate ale pachetului și cum diferă de părțile personalizate XML?

Document.PackageCustomParts (un CustomPartCollection de obiecte CustomPart) conține părţi arbitrare ale pachetului OOXML care nu sunt XML personalizate — fiecare având un ContentType, RelationshipType şi un Data brut. Document.CustomXmlParts este destinat în mod specific insulelor de date XML personalizate.

Ce este un SmartTag?

SmartTag este o funcționalitate legacy Word care reprezintă text recunoscut şi încadrat de un recunoaștor de etichete inteligente. Este un nod de document (NodeType.SmartTag) cu un Element şi Uri care identifică recunoaștorul, şi o colecție Properties de valori CustomXmlProperty atașate de recunoaștor.

Cum pot copia datele XML personalizate între documente?

Utilizați CustomXmlPart.Clone() pe partea sursă, apoi adăugați clonul la Document.CustomXmlParts documentului țintă cu Add(part).

API Reference Rezumat

Vezi și:

• Aspose.Words for .NET — Enterprise Documentation