Come lavorare con i tag di documento strutturato in .NET

Passo 1: Installa il pacchetto

Aspose.Words FOSS for .NET non pubblica ancora un pacchetto NuGet – costruisci invece la libreria dal sorgente. Clona https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, quindi compila Aspose.Words.sln in configurazione Release con l’SDK .NET e fai riferimento all’assembly Aspose.Words risultante dal tuo progetto. La libreria punta a .NET Standard 2.0, quindi funziona su .NET Framework 4.6.2+ e .NET 6/8/10.

Passo 2: Importa le classi richieste

Aggiungi una direttiva using Aspose.Words; per Document e DocumentBuilder, e una direttiva using Aspose.Words.Markup; per StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, e le altre classi di controllo di contenuto trattate in questa guida.

Passo 3: Controlla quali tipi di Content-Control puoi inserire

Prima di inserire, verifica se il SdtType di destinazione è uno dei sette tipi accettati da DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture e Date. RepeatingSection e RepeatingSectionItem non possono essere inseriti in un cursore di testo con questo metodo – avvolgono interi paragrafi o righe di tabella invece. I restanti valori SdtType che possono comparire in un file Word ma non sono presenti nell’interfaccia Word come tipi inseribili – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group e EntityPicker – non sono accettati da questo metodo di inserimento in assoluto.

Passo 4: Inserisci un Content Control al cursore

Chiama DocumentBuilder.InsertStructuredDocumentTag(SdtType) con uno dei sette tipi supportati per inserire un nuovo controllo nella posizione corrente del cursore del builder; la chiamata restituisce il nuovo StructuredDocumentTag. Imposta Tag e Title sul controllo restituito per assegnargli le stringhe identificative che gli autori vedono in Word, e imposta PlaceholderName (supportato da un Placeholder BuildingBlock) per il testo di suggerimento che Word mostra quando il controllo è vuoto – IsShowingPlaceholderText indica se quel suggerimento è attualmente visualizzato.

Passo 5: Configura il contenuto specifico del tipo

Per un controllo checkbox, leggi o imposta StructuredDocumentTag.Checked, e chiama SetCheckedSymbol() / SetUncheckedSymbol() per personalizzare le icone visualizzate per ogni stato. Per un controllo data, imposta FullDate, con DateDisplayFormat e DateDisplayLocale che controllano il rendering, DateStorageFormat (SdtDateStorageFormat) che controlla come viene memorizzato quando è collegato ai dati XML, e CalendarType (SdtCalendarType) che seleziona il sistema di calendario. Per un elenco a discesa o una casella combinata, popola ListItems – un SdtListItemCollection di SdtListItem (DisplayText, Value) – prima di impostare SelectedValue per scegliere l’opzione attiva. Per un controllo di testo semplice, Multiline è una proprietà bool su StructuredDocumentTag che può essere impostata per configurare il controllo.

Passo 6: Controlla l’aspetto e il blocco

Imposta Appearance (SdtAppearance) per controllare come il controllo è delimitato visivamente in Word, e Color per impostare il suo colore di evidenziazione. ContentsFont e EndCharacterFont controllano il carattere applicato al contenuto del controllo e il suo carattere finale di chiusura. LockContentControl e LockContents sono interruttori indipendenti – imposta LockContentControl per bloccare l’eliminazione del controllo stesso, e LockContents per bloccare la modifica di ciò che contiene, senza influire sull’altro.

Passo 7: Trova e rimuovi i controlli di contenuto

Leggi Range.StructuredDocumentTags – un StructuredDocumentTagCollection limitato a quell’intervallo – e chiama GetById(), GetByTag() o GetByTitle() per individuare un controllo specifico, oppure Remove() / RemoveAt() sulla collezione per rimuoverne uno per riferimento o indice. Su un singolo controllo, chiama Remove() per eliminare il controllo insieme ai suoi contenuti, RemoveSelfOnly() per eliminare solo il contenitore mantenendo i contenuti nel documento, o Clear() per svuotare i contenuti mantenendo il controllo stesso al suo posto.

Passo 8: Associa un controllo a dati XML personalizzati

Leggi StructuredDocumentTag.XmlMapping – un’istanza XmlMapping – e chiama SetMapping(customXmlPart, xPath, prefixMapping) per associare il controllo a una parte XML personalizzata già presente nel repository di dati XML personalizzato del documento, usando un’espressione XPath per selezionare l’elemento associato. XmlMapping.IsMapped indica se un’associazione è attualmente attiva, CustomXmlPart e StoreItemId identificano la parte di dati associata, e Delete() rimuove la mappatura.

Passo 9: Gestisci i controlli di contenuto che si estendono su più sezioni

Un controllo di contenuto che si estende su più di una sezione del documento – segnalato da IsMultiSection – non è rappresentato da un singolo nodo StructuredDocumentTag ma da una coppia StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, collegata tramite StructuredDocumentTagRangeStart.RangeEnd. Programma contro l’interfaccia condivisa IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) quando il codice deve gestire sia le forme a nodo singolo sia quelle a intervallo in modo uniforme, invece di ramificare sul tipo concreto.