Arbeta med strukturerade dokumenttaggar (innehållskontroller)

Arbeta med strukturerade dokumenttaggar (innehållskontroller)

En strukturerad dokumenttagg (SDT), känd i Word-UI som en innehållskontroll, omsluter ett stycke dokumentinnehåll med typad, begränsad redigeringsbeteende – en kryssruta, en datumväljare, en rullgardinslista eller en vanlig- eller riktext-platshållare. Aspose.Words FOSS för .NET modellerar dessa genom den Aspose.Words.Markup namnrymd, rubricerad av den StructuredDocumentTag klass. Den här sidan behandlar att infoga innehållskontroller, konfigurera varje typ, hitta och ta bort dem samt binda dem till anpassade XML-data.

Objektmodellen för strukturerade dokumenttaggar

StructuredDocumentTag är en CompositeNode som också implementerar IMarkupNode, ITrackableNode och IStructuredDocumentTag. SdtType identifierar vilken typ av kontroll det är. Tag och Title innehåller de identifierande strängar som författare anger i Word; Placeholder (en BuildingBlock) och PlaceholderName tillhandahåller den uppmaningstext som visas när kontrollen är tom, rapporterad via IsShowingPlaceholderText. LockContentControl förhindrar att kontrollen tas bort, och LockContents förhindrar att dess innehåll redigeras, oberoende av varandra.

Infoga innehållskontroller

DocumentBuilder.InsertStructuredDocumentTag(SdtType) infogar en ny kontroll vid markören, men endast för sju av SdtType-värdena: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture och Date. RepeatingSection och RepeatingSectionItem kan inte infogas vid en textmarkör på detta sätt – de omsluter i stället hela stycken eller tabellrader. De återstående SdtType-värdena som finns i Word-filer men som inte finns i Word-gränssnittet som infogbara typer – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group och EntityPicker – stöds inte av denna infogningsmetod.

Typ-specifikt innehåll

En kryssrutan kontrolls tillstånd är StructuredDocumentTag.Checked; SetCheckedSymbol() och SetUncheckedSymbol() anger de glyfer som visas för varje tillstånd. En datumkontroll lagrar sitt värde i FullDate, med DateDisplayFormat och DateDisplayLocale som styr hur den renderas, DateStorageFormat (en SdtDateStorageFormat) som styr hur den lagras när den är bunden till XML data, och CalendarType (en SdtCalendarType) som väljer kalendersystemet. En rullgardinslista eller kombinationsruta visar sina val via ListItems, en SdtListItemCollection av SdtListItem (DisplayText, Value) med en SelectedValue. En rentextkontrolls Multiline egenskap tillåter eller förbjuder radbrytningar inuti den.

Utseende och låsning

Appearance (SdtAppearance) styr hur kontrollen visuellt avgränsas i Word. Color anger dess markeringsfärg, och ContentsFont / EndCharacterFont styr typsnittet som tillämpas på dess innehåll och dess avslutande tecken. LockContentControl och LockContents är oberoende växlar – den första hindrar borttagning av själva kontrollen, den andra hindrar redigering av vad som finns i den.

Hitta och ta bort innehållskontroller

Range.StructuredDocumentTags returnerar en StructuredDocumentTagCollection som är avgränsad till det intervallet, med GetById(), GetByTag() och GetByTitle() för riktad sökning tillsammans med Remove() och RemoveAt(). På en enskild StructuredDocumentTag tar Remove() bort kontrollen och dess innehåll tillsammans, RemoveSelfOnly() tar bara bort omslaget och behåller dess innehåll i dokumentet, och Clear() tömmer kontrollens innehåll samtidigt som kontrollen själv behålls.

XML databindning

StructuredDocumentTag.XmlMapping är en XmlMapping instans som beskriver en bindning till en anpassad XML del i dokumentet: CustomXmlPart, XPath, PrefixMappings, StoreItemId och IsMapped. SetMapping() etablerar bindningen till en befintlig anpassad XML del och Delete() tar bort den.

Flersektion (intervall) innehållskontroller

En innehållskontroll som sträcker sig över mer än en sektion – rapporterad av IsMultiSection – representeras inte av en enda StructuredDocumentTag node utan av ett par StructuredDocumentTagRangeStart och StructuredDocumentTagRangeEnd noder, kopplade genom StructuredDocumentTagRangeStart.RangeEnd. Både enskilda nod- och intervallformer implementerar det gemensamma IStructuredDocumentTag interface, så kod som bara behöver Tag, Title, SdtType, Placeholder och liknande identifierande egenskaper kan fungera med båda formerna enhetligt.

Tips och bästa praxis

• Kontrollera DocumentBuilder.InsertStructuredDocumentTag()s supported-type-lista innan du förlitar dig på den – endast PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture och Date kan infogas vid markören; andra typer kastar ett undantag.
• Använd RemoveSelfOnly() istället för Remove() när du vill ”platta till” en innehållskontroll – behåll dess innehåll i dokumentet men ta bort kontrollomslaget.
• Fyll i ListItems innan du förväntar dig att en DropDownList eller ComboBox kontroll ska visa val, och sätt SelectedValue för att välja den aktiva.
• Programmera mot IStructuredDocumentTag snarare än StructuredDocumentTag direkt om din kod måste hantera både vanliga och flersektions- (intervall-) innehållskontroller på samma sätt.
• XmlMapping.SetMapping() binder till en anpassad XML-del som redan måste finnas i dokumentets anpassade XML datalager – lägg till eller ladda XML-data innan du mappar en kontroll till den.

Vanliga problem

FAQ

Vilka typer av innehållskontroller kan jag infoga direkt med DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture och Date. Andra SdtType-värden stöds inte av InsertStructuredDocumentTag().

Hur hittar jag alla innehållskontroller med en specifik tagg?

Använd Range.StructuredDocumentTags.GetByTag(), eller GetByTitle() / GetById() om du matchar på dem istället.

Hur tar jag bort en innehållskontroll men behåller dess innehåll?

Anropa StructuredDocumentTag.RemoveSelfOnly() snarare än Remove().

Hur binder jag en innehållskontroll till anpassad XML-data?

Anropa XmlMapping.SetMapping() på kontrollen och peka den på en befintlig anpassad XML del samt ett XPath-uttryck i den.

Vad är skillnaden mellan en enkel StructuredDocumentTag och en med intervall?

En innehållskontroll som sträcker sig över mer än en dokumentsektion representeras som ett StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd-par istället för en enskild nod; båda formerna implementerar IStructuredDocumentTag.

API Reference Sammanfattning

Se även

• Aspose.Words for .NET — Enterprise Documentation