Lavorare con i tag di documento strutturati (controlli di contenuto)

Lavorare con i Tag di Documento Strutturato (Controlli di Contenuto)

Un tag di documento strutturato (SDT), noto nell’interfaccia di Word come controllo contenuto, avvolge un pezzo di contenuto del documento con un comportamento di modifica tipizzato e vincolato — una casella di controllo, un selettore di data, un elenco a discesa o un segnaposto di testo semplice o ricco. Aspose.Words FOSS per .NET modella questi attraverso il Aspose.Words.Markup namespace, introdotto da il StructuredDocumentTag classe. Questa pagina tratta l’inserimento dei controlli contenuto, la configurazione di ciascun tipo, la ricerca e la rimozione di essi, e il collegamento a dati XML personalizzati.

Il modello a oggetti dei Tag di documento strutturato

StructuredDocumentTag è un CompositeNode che implementa anche IMarkupNode, ITrackableNode e IStructuredDocumentTag. SdtType identifica che tipo di controllo è. Tag e Title contengono le stringhe identificative impostate dagli autori in Word; Placeholder (un BuildingBlock) e PlaceholderName forniscono il testo di suggerimento mostrato quando il controllo è vuoto, segnalato tramite IsShowingPlaceholderText. LockContentControl impedisce l’eliminazione del controllo, e LockContents impedisce la modifica del suo contenuto, indipendentemente l’uno dall’altro.

Inserimento dei controlli di contenuto

DocumentBuilder.InsertStructuredDocumentTag(SdtType) inserisce un nuovo controllo al cursore, ma solo per sette dei valori SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture e Date. RepeatingSection e RepeatingSectionItem non possono essere inseriti in questo modo a un cursore di testo — avvolgono interi paragrafi o righe di tabella invece. I restanti valori SdtType che compaiono nei file Word ma non sono presenti nell’interfaccia di Word come tipi inseribili — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group e EntityPicker — non sono supportati da questo metodo di inserimento.

Contenuto specifico per tipo

Lo stato di un controllo checkbox è StructuredDocumentTag.Checked; SetCheckedSymbol() e SetUncheckedSymbol() impostano i glifi mostrati per ogni stato. Un controllo data memorizza il suo valore in FullDate, con DateDisplayFormat e DateDisplayLocale che controllano come viene renderizzato, DateStorageFormat (un SdtDateStorageFormat) che controlla come viene memorizzato quando è collegato a dati XML, e CalendarType (un SdtCalendarType) che seleziona il sistema di calendario. Un elenco a discesa o una casella combinata espone le sue scelte tramite ListItems, un SdtListItemCollection di SdtListItem (DisplayText, Value) con un SelectedValue. La proprietà Multiline di un controllo di testo semplice consente o vieta interruzioni di riga al suo interno.

Aspetto e blocco

Appearance (SdtAppearance) controlla come il controllo è delimitato visivamente in Word. Color imposta il suo colore di evidenziazione, e ContentsFont / EndCharacterFont controllano il carattere applicato al suo contenuto e al carattere finale. LockContentControl e LockContents sono interruttori indipendenti — il primo impedisce l’eliminazione del controllo stesso, il secondo impedisce la modifica di ciò che contiene.

Ricerca e rimozione dei controlli di contenuto

Range.StructuredDocumentTags restituisce un StructuredDocumentTagCollection limitato a quell’intervallo, con GetById(), GetByTag() e GetByTitle() per la ricerca mirata insieme a Remove() e RemoveAt(). Su un singolo StructuredDocumentTag, Remove() elimina il controllo e i suoi contenuti insieme, RemoveSelfOnly() elimina solo il contenitore mantenendo i contenuti nel documento, e Clear() svuota i contenuti del controllo mantenendo il controllo stesso.

XML Associazione dati

StructuredDocumentTag.XmlMapping è un’istanza XmlMapping che descrive un’associazione a una parte XML personalizzata nel documento: CustomXmlPart, XPath, PrefixMappings, StoreItemId e IsMapped. SetMapping() stabilisce l’associazione a una parte XML personalizzata esistente e Delete() la rimuove.

Controlli di contenuto multisezione (intervallati)

Un controllo di contenuto che si estende su più di una sezione – segnalato da IsMultiSection – non è rappresentato da un unico nodo StructuredDocumentTag ma da una coppia di nodi StructuredDocumentTagRangeStart e StructuredDocumentTagRangeEnd, collegati tramite StructuredDocumentTagRangeStart.RangeEnd. Sia la forma a nodo singolo sia quella a intervallo implementano l’interfaccia comune IStructuredDocumentTag, così il codice che necessita solo di Tag, Title, SdtType, Placeholder e proprietà identificative simili può funzionare con entrambe le forme in modo uniforme.

Suggerimenti e migliori pratiche

• Controlla l’elenco dei tipi supportati da DocumentBuilder.InsertStructuredDocumentTag() prima di fare affidamento su di esso – solo PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture e Date possono essere inseriti al cursore; gli altri tipi generano un’eccezione.
• Usa RemoveSelfOnly() invece di Remove() quando vuoi “appiattire” un controllo di contenuto – mantieni il suo contenuto nel documento ma rimuovi il contenitore del controllo.
• Popola ListItems prima di attendere che un controllo DropDownList o ComboBox mostri le scelte, e imposta SelectedValue per selezionare quello attivo.
• Programa contro IStructuredDocumentTag invece di StructuredDocumentTag direttamente se il tuo codice deve gestire sia i controlli di contenuto ordinari sia quelli a più sezioni (intervallati) allo stesso modo.
• XmlMapping.SetMapping() si collega a una parte personalizzata XML che deve già esistere nel deposito dati personalizzato XML del documento – aggiungi o carica i dati XML prima di mappare un controllo su di essi.

Problemi comuni

FAQ

Quali tipi di controllo del contenuto posso inserire direttamente con DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture e Date. Altri valori SdtType non sono supportati da InsertStructuredDocumentTag().

Come posso trovare tutti i controlli del contenuto con un tag specifico?

Usa Range.StructuredDocumentTags.GetByTag(), oppure GetByTitle() / GetById() se invece stai facendo corrispondenza su quelli.

Come rimuovere un controllo del contenuto ma mantenere il suo contenuto?

Chiama StructuredDocumentTag.RemoveSelfOnly() invece di Remove().

Come associare un controllo del contenuto a dati XML personalizzati?

Chiama XmlMapping.SetMapping() sul controllo, puntandolo a una parte XML personalizzata esistente e a un’espressione XPath al suo interno.

Qual è la differenza tra un StructuredDocumentTag semplice e uno a intervallo?

Un controllo di contenuto che copre più di una sezione del documento è rappresentato come una coppia StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd invece di un singolo nodo; entrambe le forme implementano IStructuredDocumentTag.

API Reference Riepilogo

Vedi anche

• Aspose.Words for .NET — Enterprise Documentation