Lavorare con il markup personalizzato XML

Lavorare con markup personalizzato XML

Questa guida mostra come leggere e gestire i dati personalizzati XML che un documento Word può contenere insieme al suo contenuto visibile — dati usati per collegare i controlli di contenuto, memorizzare metadati specifici dell’applicazione o incorporare parti di pacchetto arbitrarie. Document.CustomXmlParts espone i dati personalizzati XML a livello di documento, e Document.PackageCustomParts espone le parti personalizzate a livello di pacchetto che non sono specificamente XML personalizzati.

Parti personalizzate XML

CustomXmlPart rappresenta un’isola di dati personalizzati XML collegata al documento — lo stesso meccanismo che Word usa per supportare i controlli di contenuto mappati a XML. Ogni parte ha un Id, un array di byte Data che contiene il XML grezzo, un DataChecksum e una proprietà Schemas (un CustomXmlSchemaCollection) che elenca gli schemi XML associati. Document.CustomXmlParts restituisce un CustomXmlPartCollection: Add(part) collega un CustomXmlPart esistente, Add(id, xml) ne crea uno direttamente da un ID e da una stringa XML, GetById(id) recupera una parte specifica, e RemoveAt(index)/Clear() rimuovono le parti. Sia CustomXmlPart che CustomXmlPartCollection espongono Clone() per duplicare i dati personalizzati XML, ad esempio quando si copia contenuto tra documenti.

Schemi personalizzati XML

CustomXmlSchemaCollection, raggiunto attraverso CustomXmlPart.Schemas, elenca gli URI degli schemi associati a una parte personalizzata XML. Supporta Add(value), Remove(name), RemoveAt(index), IndexOf(value), Clear() e Clone(), insieme a una proprietà Count — gli URI degli schemi sono tracciati come semplici stringhe anziché come oggetti schema analizzati.

Proprietà personalizzate XML

Separatamente da CustomXmlPart, CustomXmlProperty rappresenta una singola proprietà XML nome/valore, costruita con CustomXmlProperty(name, uri, value) e che espone Name, Uri e Value. CustomXmlPropertyCollection gestisce un insieme di questi: Add(property) ne aggiunge uno, l’indicizzatore (ad es. properties["MyProp"]) lo ricerca per nome e Contains(name) verifica se è presente, IndexOfKey(name) restituisce la sua posizione, e Remove(name)/RemoveAt(index)/Clear() rimuovono le voci. SmartTag.Properties restituisce un CustomXmlPropertyCollection, che è il modo in cui i dati strutturati di un smart tag legacy sono rappresentati (vedi sotto).

Parti personalizzate a livello di pacchetto

Document.PackageCustomParts restituisce un CustomPartCollection di oggetti CustomPart — parti arbitrarie memorizzate nel pacchetto OOXML che non sono dati XML personalizzati, come le parti aggiunte da altre applicazioni che hanno modificato il file. Ogni CustomPart ha un Name, ContentType, RelationshipType, un array di byte Data e un flag IsExternal che indica se la parte è un riferimento esterno anziché contenuto incorporato. La collezione supporta Add(part), RemoveAt(index), Clear() e Clone(), insieme a Count.

Smart Tag Legacy

SmartTag è un tipo di nodo (NodeType.SmartTag) che rappresenta uno smart tag legacy di Word avvolto attorno al testo riconosciuto. Un SmartTag viene costruito con SmartTag(doc) e espone Element (il nome dell’elemento riconoscitore) e Uri (lo spazio dei nomi del riconoscitore), insieme a Properties — un CustomXmlPropertyCollection che contiene i dati strutturati che il riconoscitore ha allegato al testo taggato. Poiché SmartTag è un nodo, partecipa anche all’albero del documento come gli altri nodi, supportando Accept(visitor), AcceptStart(visitor) e AcceptEnd(visitor) per l’attraversamento basato su DocumentVisitor.

MarkupLevel

MarkupLevel è un enum — Unknown, Inline, Block, Row, Cell — che descrive il livello strutturale nell’albero del documento in cui può comparire un elemento di markup come un tag di documento strutturato.

Suggerimenti e buone pratiche

• Usa CustomXmlPartCollection.GetById(id) invece di iterare manualmente la raccolta quando conosci l’ID della parte di cui hai bisogno.
• Leggi CustomXmlPart.DataChecksum per rilevare se i dati XML sottostanti sono cambiati senza eseguire un confronto completo a livello di byte.
• Distinguere Document.CustomXmlParts (dati XML personalizzati, spesso associati a controlli di contenuto) da Document.PackageCustomParts (parti di pacchetto arbitrarie non-XML) — hanno scopi diversi e vengono archiviati separatamente.
• Quando si lavora con documenti legacy che utilizzano smart tag, verifica SmartTag.Element e Uri insieme per identificare quale riconoscitore ha creato il tag prima di fare affidamento sul suo Properties.
• Clona le parti XML personalizzate con CustomXmlPart.Clone() (oppure con il Clone() della collezione) quando copi i dati tra documenti, invece di rileggerli e riaggiungere il XML grezzo.

Problemi comuni

FAQ

Qual è la differenza tra CustomXmlPart e CustomXmlProperty?

CustomXmlPart è un’intera isola di dati XML (con un payload byte-array e schemi associati), raggiungibile tramite Document.CustomXmlParts. CustomXmlProperty è una singola coppia nome/valore, tipicamente raggiunta tramite SmartTag.Properties piuttosto che direttamente dal documento.

Come posso aggiungere dati XML personalizzati a un documento?

Chiama Document.CustomXmlParts.Add(id, xml) con una stringa ID e il contenuto XML, oppure costruisci un CustomXmlPart separatamente e passalo a Add(part).

Cosa sono le parti personalizzate del pacchetto e in che modo differiscono dalle parti personalizzate XML?

Document.PackageCustomParts (un CustomPartCollection di oggetti CustomPart) contiene parti arbitrari del pacchetto OOXML che non sono XML personalizzate — ognuna con un ContentType, RelationshipType e raw Data. Document.CustomXmlParts è specificamente per isole di dati XML personalizzate.

Che cos’è un SmartTag?

SmartTag è una funzionalità legacy di Word che rappresenta testo riconosciuto e avvolto da un riconoscitore di smart-tag. È un nodo del documento (NodeType.SmartTag) con un Element e Uri che identificano il riconoscitore, e una collezione Properties di valori CustomXmlProperty allegati dal riconoscitore.

Come copio i dati XML personalizzati tra documenti?

Usa CustomXmlPart.Clone() sulla parte di origine, poi aggiungi il clone al Document.CustomXmlParts del documento di destinazione con Add(part).

API Reference Riepilogo

Vedi anche

• Aspose.Words for .NET — Enterprise Documentation