Strukturált dokumentumcímkék (tartalomvezérlők) kezelése

Struktúrált dokumentumcímkék (tartalomvezérlők) kezelése

A structured document tag (SDT), amelyet a Word UI-ban content control-nak hívnak, egy dokumentumtartalom darabját körülveszi típusú, korlátozott szerkesztési viselkedéssel – egy jelölőnégyzetet, egy dátumválasztót, egy legördülő listát vagy egy egyszerű- vagy gazdag szöveges helykitöltőt. Aspose.Words FOSS a .NET számára modellezi ezeket a Aspose.Words.Markup névtér, amelyet a StructuredDocumentTag class. Ez az oldal tárgyalja a content control-ok beszúrását, az egyes típusok konfigurálását, azok megtalálását és eltávolítását, valamint a saját XML adatokhoz való kötésüket.

A struktúrált dokumentumcímke objektummodell

StructuredDocumentTag egy CompositeNode, amely emellett megvalósítja a IMarkupNode, ITrackableNode és IStructuredDocumentTag interfészeket. SdtType határozza meg, hogy milyen típusú vezérlő. Tag és Title tartalmazzák azokat az azonosító karakterláncokat, amelyeket a szerzők a Wordben állítanak be; Placeholder (egy BuildingBlock) és PlaceholderName biztosítják a felhívó szöveget, amely akkor jelenik meg, amikor a vezérlő üres, és ezt a IsShowingPlaceholderText jelenti. LockContentControl megakadályozza a vezérlő törlését, míg LockContents megakadályozza a tartalma szerkesztését, egymástól függetlenül.

Tartalomvezérlők beszúrása

DocumentBuilder.InsertStructuredDocumentTag(SdtType) új vezérlőt szúr be a kurzor helyére, de csak a SdtType értékek hét esetében: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture és Date. RepeatingSection és RepeatingSectionItem nem szúrhatók be szöveges kurzorral – ezek helyette egész bekezdéseket vagy táblázatsorokat foglalnak körül. A maradék SdtType értékek, amelyek a Word fájlokban megjelennek, de a Word felhasználói felületén nem elérhetők beszúrható típusokként – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group és EntityPicker – nem támogatottak ezzel a beszúrási módszerrel.

Típus-specifikus tartalom

Egy jelölőnégyzet vezérlő állapota StructuredDocumentTag.Checked; SetCheckedSymbol() és SetUncheckedSymbol() állítják be az egyes állapotokhoz megjelenő jeleket. Egy dátumvezérlő értékét FullDate tárolja, a DateDisplayFormat és DateDisplayLocale szabályozzák, hogyan jelenik meg, DateStorageFormat (egy SdtDateStorageFormat) szabályozza, hogyan tárolódik, ha XML adatokhoz van kötve, és CalendarType (egy SdtCalendarType) választja ki a naptárrendszert. Egy legördülő lista vagy kombinált mező a választásait ListItems segítségével teszi elérhetővé, egy SdtListItemCollection SdtListItem (DisplayText, Value) -ból, SelectedValue -el. Egy egyszerű szöveges vezérlő Multiline tulajdonsága engedélyezi vagy tiltja a sortöréseket benne.

Megjelenés és zárolás

Appearance (SdtAppearance) szabályozza, hogyan jelenik meg vizuálisan a vezérlő a Wordben. Color állítja be a kiemelés színét, és ContentsFont / EndCharacterFont szabályozzák a tartalomra alkalmazott betűtípust és a záró karaktert. LockContentControl és LockContents független kapcsolók – az első megakadályozza a vezérlő magának a törlését, a második tiltja a benne lévő tartalom szerkesztését.

Tartalomvezérlők keresése és eltávolítása

Range.StructuredDocumentTags visszaad egy StructuredDocumentTagCollection -t, amely az adott tartományra vonatkozik, GetById(), GetByTag() és GetByTitle() célzott kereséshez, valamint Remove() és RemoveAt() mellett. Egyetlen StructuredDocumentTag esetén a Remove() együttesen törli a vezérlőt és annak tartalmát, a RemoveSelfOnly() csak a burkot törli, a tartalmat a dokumentumban megtartva, a Clear() pedig kiüríti a vezérlő tartalmát, miközben magát a vezérlőt megtartja.

XML adatkötés

StructuredDocumentTag.XmlMapping egy XmlMapping példány, amely a dokumentumban lévő egyedi XML részhez való kötést írja le: CustomXmlPart, XPath, PrefixMappings, StoreItemId és IsMapped. SetMapping() létrehozza a kötést egy meglévő egyedi XML részhez, a Delete() pedig eltávolítja azt.

Többszakaszos (tartományos) tartalomvezérlők

Az több mint egy szekciót átfogó tartalomvezérlő – jelentve: IsMultiSection – nem egyetlen StructuredDocumentTag csomópontként, hanem egy StructuredDocumentTagRangeStart és egy StructuredDocumentTagRangeEnd csomópárként van ábrázolva, amelyet a StructuredDocumentTagRangeStart.RangeEnd köt össze. Mind az egycsomópontos, mind a tartományos formák implementálják a közös IStructuredDocumentTag interfészt, így a csak Tag, Title, SdtType, Placeholder és hasonló azonosító tulajdonságokra szükséges kód egyformán működik mindkét formával.

Tippek és legjobb gyakorlatok

• Ellenőrizze a DocumentBuilder.InsertStructuredDocumentTag() támogatott típusok listáját, mielőtt rá támaszkodna – csak a PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture és Date szúrható be a kurzornál; a többi típus kivételt dob.
• Használja a RemoveSelfOnly() elemet a Remove() helyett, ha egy tartalomvezérlőt „laposra” szeretne tenni – a tartalmát a dokumentumban megtartja, de a vezérlő burkolatát eltávolítja.
• Töltse fel a ListItems elemet, mielőtt egy DropDownList vagy ComboBox vezérlőnek választásokat kellene megjelenítenie, és állítsa be a SelectedValue értékét az aktív kiválasztásához.
• Programozzon a IStructuredDocumentTag felé, ahelyett, hogy közvetlenül a StructuredDocumentTag-et használná, ha a kódnak ugyanúgy kell kezelnie az egyszerű és a több szekciót (tartományos) átfogó tartalomvezérlőket.
• A XmlMapping.SetMapping() egy egyedi XML részhez kötődik, amely már léteznie kell a dokumentum egyedi XML adatbázisában – adja hozzá vagy töltse be a XML adatot, mielőtt a vezérlőt ehhez rendeli.

Általános problémák

FAQ

Milyen tartalomvezérlő típusokat tudok közvetlenül beszúrni a DocumentBuilder segítségével?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, és Date. Más SdtType értékek nem támogatottak a InsertStructuredDocumentTag() által.

Hogyan találhatom meg az összes tartalomvezérlőt egy adott címkével?

Használja a Range.StructuredDocumentTags.GetByTag() elemet, vagy a GetByTitle() / GetById() kombinációt, ha azok szerint szeretne egyezést.

Hogyan távolíthatom el egy tartalomvezérlőt, miközben megőrzöm a tartalmát?

Hívja a StructuredDocumentTag.RemoveSelfOnly() helyett a Remove().

Hogyan köthetem egy tartalomvezérlőt egyedi XML adatokhoz?

Hívja meg a(z) XmlMapping.SetMapping() vezérlőn, úgy irányítva, hogy egy meglévő egyéni XML részt és egy XPath kifejezést célozzon meg benne.

Mi a különbség egy egyszerű StructuredDocumentTag és egy tartományos változat között?

Egy olyan tartalomvezérlő, amely egynél több dokumentum szakaszon átnyúlik, StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd párként jelenik meg egyetlen csomópont helyett; mindkét forma megvalósítja a IStructuredDocumentTag.

API Reference összefoglaló

Lásd még:

• Aspose.Words for .NET — Enterprise Documentation