Werken met gestructureerde documenttags (inhoudsbesturingselementen)

Werken met gestructureerde documenttags (inhoudsbesturingselementen)

Een gestructureerde documenttag (SDT), in de Word UI bekend als een content control, omsluit een stuk documentinhoud met een getypeerd, beperkt bewerkingsgedrag – een selectievakje, een datumkiezer, een vervolgkeuzelijst, of een platte- of rich-text-placeholder. Aspose.Words FOSS voor .NET modelleert deze via de Aspose.Words.Markup namespace, met als kop de StructuredDocumentTag klasse. Deze pagina behandelt het invoegen van content controls, het configureren van elk type, het vinden en verwijderen ervan, en het koppelen ervan aan aangepaste XML-gegevens.

Het gestructureerde documenttag-objectmodel

StructuredDocumentTag is een CompositeNode die ook IMarkupNode, ITrackableNode en IStructuredDocumentTag implementeert. SdtType identificeert welk type besturingselement het is. Tag en Title bevatten de identificerende strings die auteurs in Word instellen; Placeholder (een BuildingBlock) en PlaceholderName leveren de prompttekst die wordt getoond wanneer het besturingselement leeg is, gerapporteerd via IsShowingPlaceholderText. LockContentControl voorkomt dat het besturingselement wordt verwijderd, en LockContents voorkomt dat de inhoud wordt bewerkt, onafhankelijk van elkaar.

Invoegen van inhoudsbesturingselementen

DocumentBuilder.InsertStructuredDocumentTag(SdtType) voegt een nieuw besturingselement in op de cursor, maar alleen voor zeven van de SdtType waarden: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture en Date. RepeatingSection en RepeatingSectionItem kunnen op deze manier niet bij een tekstcursor worden ingevoegd – ze omhullen in plaats daarvan volledige alinea’s of tabelrijen. De overige SdtType waarden die in Word-bestanden voorkomen maar niet in de Word-UI als invoegbare types worden weergegeven – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group en EntityPicker – worden niet ondersteund door deze invoegmethode.

Type-specifieke inhoud

De status van een selectievakje is StructuredDocumentTag.Checked; SetCheckedSymbol() en SetUncheckedSymbol() bepalen de glyphs die voor elke status worden getoond. Een datumcontrole slaat zijn waarde op in FullDate, met DateDisplayFormat en DateDisplayLocale die bepalen hoe deze wordt gerenderd, DateStorageFormat (een SdtDateStorageFormat) die bepaalt hoe deze wordt opgeslagen wanneer gebonden aan XML data, en CalendarType (een SdtCalendarType) die het kalendersysteem selecteert. Een vervolgkeuzelijst of combobox maakt zijn keuzes beschikbaar via ListItems, een SdtListItemCollection van SdtListItem (DisplayText, Value) met een SelectedValue. De Multiline eigenschap van een platte-tekst controle staat regeleinden toe of verbiedt ze.

Uiterlijk en vergrendeling

Appearance (SdtAppearance) bepaalt hoe het besturingselement visueel wordt begrensd in Word. Color stelt de markeerkleur in, en ContentsFont / EndCharacterFont bepalen het lettertype dat op de inhoud en het afsluitende teken wordt toegepast. LockContentControl en LockContents zijn onafhankelijke schakelaars – de eerste blokkeert het verwijderen van het besturingselement zelf, de tweede blokkeert het bewerken van wat erin staat.

Zoeken en verwijderen van inhoudsbesturingselementen

Range.StructuredDocumentTags retourneert een StructuredDocumentTagCollection die op dat bereik is geschaald, met GetById(), GetByTag() en GetByTitle() voor gerichte opzoeking naast Remove() en RemoveAt(). Op een individueel StructuredDocumentTag verwijdert Remove() het besturingselement en de inhoud samen, RemoveSelfOnly() verwijdert alleen de omhulling en behoudt de inhoud in het document, en Clear() maakt de inhoud van het besturingselement leeg terwijl het besturingselement zelf behouden blijft.

XML gegevensbinding

StructuredDocumentTag.XmlMapping is een XmlMapping instantie die een binding beschrijft naar een aangepast XML onderdeel in het document: CustomXmlPart, XPath, PrefixMappings, StoreItemId en IsMapped. SetMapping() legt de binding vast aan een bestaand aangepast XML onderdeel en Delete() verwijdert het.

Multi-Section (Bereik) inhoudsbesturingselementen

Een contentcontrol die zich over meer dan één sectie uitstrekt – gerapporteerd door IsMultiSection – wordt niet weergegeven door een enkele StructuredDocumentTag node maar door een paar StructuredDocumentTagRangeStart en StructuredDocumentTagRangeEnd nodes, verbonden via StructuredDocumentTagRangeStart.RangeEnd. Zowel de enkel-node als de bereikvormen implementeren de gemeenschappelijke IStructuredDocumentTag interface, zodat code die alleen Tag, Title, SdtType, Placeholder en soortgelijke identificerende eigenschappen nodig heeft, uniform met beide vormen kan werken.

Tips en best practices

• Controleer de lijst met ondersteunde typen van DocumentBuilder.InsertStructuredDocumentTag() voordat u erop vertrouwt – alleen PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture en Date kunnen op de cursor worden ingevoegd; andere typen veroorzaken een uitzondering.
• Gebruik RemoveSelfOnly() in plaats van Remove() wanneer u een contentcontrol wilt “flatten” – behoud de inhoud in het document maar verwijder de control-omslag.
• Vul ListItems in voordat u verwacht dat een DropDownList of ComboBox control keuzes toont, en stel SelectedValue in om de actieve te selecteren.
• Programmeert u tegen IStructuredDocumentTag in plaats van direct tegen StructuredDocumentTag als uw code zowel gewone als multi-sectie (bereik) contentcontrols op dezelfde manier moet afhandelen.
• XmlMapping.SetMapping() bindt aan een aangepast XML-onderdeel dat al moet bestaan in de aangepaste XML-datastore van het document – voeg de XML-gegevens toe of laad ze voordat u een control eraan toewijst.

Veelvoorkomende problemen

FAQ

Welke soorten contentbesturingselementen kan ik direct invoegen met DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture en Date. Andere SdtType waarden worden niet ondersteund door InsertStructuredDocumentTag().

Hoe vind ik alle contentbesturingselementen met een specifieke tag?

Gebruik Range.StructuredDocumentTags.GetByTag(), of GetByTitle() / GetById() als je in plaats daarvan op die wilt matchen.

Hoe verwijder ik een contentbesturingselement maar behoud ik de inhoud?

Roep StructuredDocumentTag.RemoveSelfOnly() aan in plaats van Remove().

Hoe bind ik een contentbesturingselement aan aangepaste XML data?

Roep XmlMapping.SetMapping() aan op de besturing, gericht op een bestaande aangepaste XML-onderdeel en een XPath-expressie daarin.

Wat is het verschil tussen een gewone StructuredDocumentTag en een bereikversie?

Een inhoudsbesturing die zich over meer dan één documentsectie uitstrekt, wordt weergegeven als een StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd paar in plaats van een enkel knooppunt; beide vormen implementeren IStructuredDocumentTag.

API Reference Samenvatting

Zie ook

• Aspose.Words for .NET — Enterprise Documentation