Hoe te werken met gestructureerde documenttags in .NET

Stap 1: Installeer het pakket

Aspose.Words FOSS voor .NET publiceert nog geen NuGet pakket – bouw de bibliotheek in plaats daarvan vanuit de broncode. Clone https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, bouw vervolgens Aspose.Words.sln in Release-configuratie met de .NET SDK en verwijs naar de resulterende Aspose.Words assembly vanuit uw project. De bibliotheek richt zich op .NET Standard 2.0, dus draait op .NET Framework 4.6.2+ en .NET 6/8/10.

Stap 2: Importeer vereiste klassen

Voeg een using Aspose.Words; directive toe voor Document en DocumentBuilder, en een using Aspose.Words.Markup; directive voor StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping, en de andere inhoudsbesturingselementklassen die in deze gids worden behandeld.

Stap 3: Controleer welke Content-Control-types u kunt invoegen

Controleer vóór het invoegen of het doel SdtType een van de zeven typen is die door DocumentBuilder.InsertStructuredDocumentTag(SdtType) worden geaccepteerd: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture en Date. RepeatingSection en RepeatingSectionItem kunnen met deze methode niet op een tekstreeks worden ingevoegd – ze omhullen in plaats daarvan volledige alinea’s of tabelrijen. De overige SdtType-waarden die in een Word-bestand kunnen voorkomen maar niet in de Word-UI verschijnen als invoegbare typen – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group en EntityPicker – worden door deze invoegmethode helemaal niet geaccepteerd.

Stap 4: Een Content Control op de cursor invoegen

Roep DocumentBuilder.InsertStructuredDocumentTag(SdtType) aan met een van de zeven ondersteunde types om een nieuwe control in te voegen op de huidige cursorpositie van de builder; de aanroep retourneert de nieuwe StructuredDocumentTag. Stel Tag en Title in op de geretourneerde control om de identificerende tekenreeksen toe te wijzen die auteurs in Word zien, en stel PlaceholderName (ondersteund door een Placeholder BuildingBlock) in voor de prompttekst die Word weergeeft terwijl de control leeg is – IsShowingPlaceholderText geeft aan of die prompt momenteel wordt weergegeven.

Stap 5: Configureer type-specifieke inhoud

Voor een checkbox-control, lees of stel StructuredDocumentTag.Checked in, en roep SetCheckedSymbol() / SetUncheckedSymbol() aan om de glyphs voor elke status aan te passen. Voor een datum-control, stel FullDate in, waarbij DateDisplayFormat en DateDisplayLocale bepalen hoe deze wordt weergegeven, DateStorageFormat (SdtDateStorageFormat) bepaalt hoe deze wordt opgeslagen wanneer deze is gekoppeld aan XML-gegevens, en CalendarType (SdtCalendarType) selecteert welk kalendersysteem wordt gebruikt. Voor een vervolgkeuzelijst of combobox, vul ListItems – een SdtListItemCollection van SdtListItem (DisplayText, Value) – in voordat SelectedValue wordt ingesteld om de actieve keuze te selecteren. Voor een platte-tekst-control is Multiline een bool-eigenschap op StructuredDocumentTag die kan worden ingesteld om de control te configureren.

Stap 6: Uiterlijk en vergrendeling van de control

Stel Appearance (SdtAppearance) in om te bepalen hoe de control visueel wordt afgebakend in Word, en Color om de markeerkleur in te stellen. ContentsFont en EndCharacterFont bepalen het lettertype dat op de inhoud van de control wordt toegepast en op het afsluitende teken. LockContentControl en LockContents zijn onafhankelijke schakelaars – stel LockContentControl in om het verwijderen van de control zelf te blokkeren, en LockContents om bewerken van de inhoud te blokkeren, zonder de andere te beïnvloeden.

Stap 7: Zoek en verwijder inhoudsbesturingselementen

Lees Range.StructuredDocumentTags – een StructuredDocumentTagCollection die op dat bereik is geschaald – en roep GetById(), GetByTag() of GetByTitle() aan om een specifiek besturingselement te vinden, of Remove() / RemoveAt() op de collectie om er één te verwijderen op basis van referentie of index. Bij een individueel besturingselement roep je Remove() aan om het besturingselement samen met de inhoud te verwijderen, RemoveSelfOnly() om alleen de omhulling te verwijderen terwijl de inhoud in het document behouden blijft, of Clear() om de inhoud te legen terwijl het besturingselement zelf op zijn plaats blijft.

Stap 8: Koppel een besturingselement aan aangepaste XML gegevens

Lees StructuredDocumentTag.XmlMapping – een XmlMapping instantie – en roep SetMapping(customXmlPart, xPath, prefixMapping) aan om het besturingselement te koppelen aan een bestaand aangepast XML onderdeel dat al aanwezig is in de aangepaste XML gegevensopslag van het document, met behulp van een XPath expressie om het gekoppelde element te selecteren. XmlMapping.IsMapped meldt of er momenteel een koppeling actief is, CustomXmlPart en StoreItemId identificeren het gekoppelde gegevensonderdeel, en Delete() verwijdert de mapping.

Stap 9: Behandel inhoudsbesturingselementen die zich over meerdere secties uitstrekken

Een inhoudsbesturingselement dat zich over meer dan één documentsectie uitstrekt – gerapporteerd door IsMultiSection – wordt niet weergegeven door een enkel StructuredDocumentTag knooppunt maar door een StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd paar, verbonden via StructuredDocumentTagRangeStart.RangeEnd. Programmeer tegen de gedeelde IStructuredDocumentTag interface (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()) wanneer code zowel de enkelvoudige knoop- als de bereikvormen uniform moet behandelen, in plaats van te vertakken op het concrete type.