Hogyan dolgozzunk a strukturált dokumentumcímkékkel a .NET

1. lépés: A csomag telepítése

Aspose.Words FOSS for .NET még nem tesz közzé NuGet csomagot – építse fel a könyvtárat a forráskódból. Klónozza a https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git repót, majd építse a Aspose.Words.sln-t Release konfigurációban a .NET SDK-val, és hivatkozzon a keletkezett Aspose.Words assembly-re a projektjéből. A könyvtár a .NET Standard 2.0-ra céloz, így fut a .NET Framework 4.6.2+ és a .NET 6/8/10 környezeteken.

2. lépés: Szükséges osztályok importálása

Adjon hozzá egy using Aspose.Words; direktívát a Document és DocumentBuilder számára, valamint egy using Aspose.Words.Markup; direktívát a StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping és az útmutatóban szereplő egyéb tartalomvezérlő osztályok számára.

3. lépés: Ellenőrizze, mely Content-Control típusokat szúrhat be

Beszúrás előtt ellenőrizze, hogy a cél SdtType a DocumentBuilder.InsertStructuredDocumentTag(SdtType) által elfogadott hét típus egyike-e: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture és Date. A RepeatingSection és a RepeatingSectionItem nem szúrhatók be szöveges kurzorra ezzel a módszerrel – helyettük teljes bekezdéseket vagy táblázatsorokat foglalnak körül. A maradék SdtType értékek, amelyek megjelenhetnek egy Word-fájlban, de a Word felhasználói felületén nem szerepelnek beszúrható típusokként – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group és EntityPicker – egyáltalán nem fogadják el ezt a beszúrási módszert.

4. lépés: Content Control beszúrása a kurzornál

Hívja meg a DocumentBuilder.InsertStructuredDocumentTag(SdtType) egyik a hét támogatott típussal, hogy új vezérlőt szúrjon be az építő aktuális kurzorpozíciójába; a hívás visszaadja az új StructuredDocumentTag elemet. Állítsa be a Tag és a Title értékeket a visszakapott vezérlőn, hogy megadja a szerzők által a Wordben látott azonosító karakterláncokat, és állítsa be a PlaceholderName (amelyet egy Placeholder BuildingBlock támogat) a felszólító szöveghez, amelyet a Word mutat, amikor a vezérlő üres – a IsShowingPlaceholderText jelzi, hogy a felszólítás jelenleg megjelenik-e.

5. lépés: Típus-specifikus tartalom beállítása

Ellenőrzőnégyzet vezérlő esetén olvassa vagy állítsa be a StructuredDocumentTag.Checked értéket, és hívja meg a SetCheckedSymbol() / SetUncheckedSymbol() függvényeket az egyes állapotokhoz megjelenő jelképek testreszabásához. Dátumvezérlő esetén állítsa be a FullDate értéket, a DateDisplayFormat és DateDisplayLocale határozza meg a megjelenítés módját, a DateStorageFormat (SdtDateStorageFormat) szabályozza, hogy hogyan tárolódik, amikor XML adatokhoz van kötve, és a CalendarType (SdtCalendarType) választja ki a naptárrendszert. Legördülő lista vagy kombinált mező esetén töltse fel a ListItems értéket – egy SdtListItemCollection a SdtListItem (DisplayText, Value) – mielőtt beállítaná a SelectedValue értéket az aktív választás kiválasztásához. Egyszerű szöveges vezérlő esetén a Multiline egy bool tulajdonság a StructuredDocumentTag elemén, amely beállítható a vezérlő konfigurálásához.

6. lépés: Vezérlő megjelenése és zárolása

Állítsa be a Appearance (SdtAppearance) értéket, hogy szabályozza, hogyan van vizuálisan elhatárolva a vezérlő a Wordben, és a Color értékkel adja meg a kiemelés színét. A ContentsFont és a EndCharacterFont határozzák meg a vezérlő tartalmára alkalmazott betűtípust és a záró karaktert. A LockContentControl és a LockContents független kapcsolók – állítsa be a LockContentControl értéket a vezérlő magának a törlésének blokkolásához, és a LockContents értéket a benne lévő tartalom szerkesztésének blokkolásához, anélkül, hogy a másikat befolyásolná.

7. lépés: Tartalomvezérlők keresése és eltávolítása

Olvassa be a Range.StructuredDocumentTags – egy StructuredDocumentTagCollection által határolt tartományt – és hívja a GetById(), GetByTag() vagy GetByTitle() metódust egy adott vezérlő megtalálásához, vagy a Remove() / RemoveAt() metódusokat a gyűjteményen egy referencia vagy index alapján történő eltávolításhoz. Egy egyedi vezérlőnél hívja a Remove() metódust a vezérlő és tartalma együttes törléséhez, a RemoveSelfOnly() metódust a burkoló törléséhez a tartalom dokumentumban való megtartásával, vagy a Clear() metódust a tartalom kiürítéséhez a vezérlő helyben tartásával.

8. lépés: Egy vezérlő kötése egyéni XML adathoz

Olvassa be a StructuredDocumentTag.XmlMapping – egy XmlMapping példányt – és hívja a SetMapping(customXmlPart, xPath, prefixMapping) metódust a vezérlő egy már meglévő egyéni XML részhez való kötéséhez, amely a dokumentum egyéni XML adatáruházában található, egy XPath kifejezés használatával a kötött elem kiválasztásához. A XmlMapping.IsMapped jelzi, hogy a kötés jelenleg aktív-e, a CustomXmlPart és StoreItemId azonosítják a kötött adatrészt, a Delete() pedig eltávolítja a leképezést.

9. lépés: Több szekciót átfogó tartalomvezérlők kezelése

Egy több dokumentumszakaszt átfogó tartalomvezérlő – amelyet a IsMultiSection jelent – nem egyetlen StructuredDocumentTag csomópontként, hanem egy StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd párként jelenik meg, amely a StructuredDocumentTagRangeStart.RangeEnd segítségével van összekapcsolva. Programozzon a közös IStructuredDocumentTag interfész ( Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly() ) felé, amikor a kódnak egységesen kell kezelnie az egyszerű csomópontot és a tartományos formákat, ahelyett, hogy a konkrét típus alapján ágazna.