Hur man arbetar med strukturerade dokumenttaggar i .NET

Steg 1: Installera paketet

Aspose.Words FOSS för .NET har ännu inte publicerat ett NuGet-paket – bygg biblioteket från källkoden istället. Klona https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, bygg sedan Aspose.Words.sln i Release-konfiguration med .NET-SDK:n och referera den resulterande Aspose.Words-assemblyn i ditt projekt. Biblioteket riktar sig mot .NET Standard 2.0, så det körs på .NET Framework 4.6.2+ och .NET 6/8/10.

Steg 2: Importera erforderliga klasser

Lägg till en using Aspose.Words;-direktiv för Document och DocumentBuilder, samt en using Aspose.Words.Markup;-direktiv för StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping och de andra innehållskontrollklasser som den här guiden täcker.

Steg 3: Kontrollera vilka innehållskontrolltyper du kan infoga

Innan du infogar, kontrollera om mål-SdtType är en av de sju typer som accepteras av DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture och Date. RepeatingSection och RepeatingSectionItem kan inte infogas vid en textmarkör med denna metod – de omsluter hela stycken eller tabellrader istället. De återstående SdtType-värdena som kan förekomma i en Word-fil men som inte finns i Word-gränssnittet som infogbara typer – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group och EntityPicker – accepteras inte alls av denna infogningsmetod.

Steg 4: Infoga en innehållskontroll vid markören

Anropa DocumentBuilder.InsertStructuredDocumentTag(SdtType) med en av de sju stödda typerna för att infoga en ny kontroll vid byggarens aktuella markörposition; anropet returnerar den nya StructuredDocumentTag. Ställ in Tag och Title på den returnerade kontrollen för att ge den identifierande strängar som författare ser i Word, och ange PlaceholderName (stödd av en Placeholder BuildingBlock) för den uppmaningstext som Word visar medan kontrollen är tom – IsShowingPlaceholderText rapporterar om den uppmaningen för närvarande visas.

Steg 5: Konfigurera typ-specifikt innehåll

För en kryssrutan-kontroll, läs eller ange StructuredDocumentTag.Checked, och anropa SetCheckedSymbol() / SetUncheckedSymbol() för att anpassa de symboler som visas för varje tillstånd. För en datumkontroll, ange FullDate, med DateDisplayFormat och DateDisplayLocale som styr hur den renderas, DateStorageFormat (SdtDateStorageFormat) som styr hur den lagras när den är bunden till XML-data, och CalendarType (SdtCalendarType) som väljer kalendersystemet. För en rullgardinslista eller kombinationsruta, fyll i ListItems – ett SdtListItemCollection av SdtListItem (DisplayText, Value) – innan du anger SelectedValue för att välja det aktiva alternativet. För en ren-text-kontroll är Multiline en bool-egenskap på StructuredDocumentTag som kan anges för att konfigurera kontrollen.

Steg 6: Kontrollera utseende och låsning

Ange Appearance (SdtAppearance) för att styra hur kontrollen visuellt avgränsas i Word, och Color för att sätta dess markeringsfärg. ContentsFont och EndCharacterFont styr typsnittet som tillämpas på kontrollens innehåll och dess avslutande tecken. LockContentControl och LockContents är oberoende växlar – ange LockContentControl för att blockera borttagning av själva kontrollen, och LockContents för att blockera redigering av dess innehåll, utan att påverka den andra.

Steg 7: Hitta och ta bort innehållskontroller

Läs Range.StructuredDocumentTags – ett StructuredDocumentTagCollection avgränsat till det intervallet – och anropa GetById(), GetByTag() eller GetByTitle() för att lokalisera en specifik kontroll, eller Remove() / RemoveAt() på samlingen för att ta bort en efter referens eller index. På en enskild kontroll, anropa Remove() för att radera kontrollen tillsammans med dess innehåll, RemoveSelfOnly() för att bara radera omslaget medan du behåller dess innehåll i dokumentet, eller Clear() för att tömma dess innehåll medan kontrollen själv förblir på plats.

Steg 8: Binda en kontroll till anpassad XML Data

Läs StructuredDocumentTag.XmlMapping – en XmlMapping instans – och anropa SetMapping(customXmlPart, xPath, prefixMapping) för att binda kontrollen till en befintlig anpassad XML-del som redan finns i dokumentets anpassade XML datalager, med hjälp av ett XPath-uttryck för att välja det bundna elementet. XmlMapping.IsMapped rapporterar om en bindning för närvarande är aktiv, CustomXmlPart och StoreItemId identifierar den bundna datadelen, och Delete() tar bort mappningen.

Steg 9: Hantera innehållskontroller som sträcker sig över flera sektioner

En innehållskontroll som sträcker sig över mer än en dokumentsektion – rapporterad av IsMultiSection – representeras inte av en enda StructuredDocumentTag-nod utan av ett StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd-par, kopplat genom StructuredDocumentTagRangeStart.RangeEnd. Programmera mot det delade IStructuredDocumentTag-gränssnittet (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) när koden behöver hantera både enstaka nod- och intervallformer enhetligt, snarare än att grenbryta på den konkreta typen.