Jak pracovat se strukturovanými značkami dokumentu v .NET
Tento průvodce ukazuje, jak vkládat, konfigurovat, vyhledávat, odstraňovat a propojit data se strukturovanými značkami dokumentu (ovládacími prvky obsahu) v Aspose.Words FOSS for .NET, pomocí StructuredDocumentTag třídy v Aspose.Words.Markup jmenném prostoru. Pokrývá, které typy ovládacích prvků obsahu DocumentBuilder mohou vkládat, nastavovat typově specifický obsah, jako je stav zaškrtávacího políčka nebo možnosti rozbalovacího seznamu, vyhledávat ovládací prvky podle značky nebo názvu, odstraňovat ovládací prvek s nebo bez jeho obsahu a mapovat ovládací prvek na vlastní data XML.
Průvodce krok za krokem
Krok 1: Nainstalujte balíček
Aspose.Words FOSS for .NET zatím nevydává balíček NuGet – místo toho sestavte knihovnu ze zdrojového kódu. Klonujte https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, poté sestavte Aspose.Words.sln v konfiguraci Release s SDK .NET a odkažte na vzniklé sestavení Aspose.Words ve svém projektu. Knihovna cílí na .NET Standard 2.0, takže běží na .NET Framework 4.6.2+ a .NET 6/8/10.
Krok 2: Importujte požadované třídy
Přidejte direktivu using Aspose.Words; pro Document a DocumentBuilder a direktivu using Aspose.Words.Markup; pro StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping a ostatní třídy ovládacích prvků, které tento průvodce pokrývá.
Krok 3: Zkontrolujte, které typy ovládacích prvků obsahu můžete vložit
Před vložením zkontrolujte, zda je cílový SdtType jedním ze sedmi typů akceptovaných DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture a Date. RepeatingSection a RepeatingSectionItem nelze pomocí této metody vložit na textový kurzor – místo toho obalují celé odstavce nebo řádky tabulky. Zbývající hodnoty SdtType, které se mohou v souboru Word objevit, ale nejsou v uživatelském rozhraní Wordu k dispozici jako vložitelné typy – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group a EntityPicker – nejsou touto metodou vkládání vůbec akceptovány.
Krok 4: Vložte ovládací prvek obsahu na kurzor
Zavolejte DocumentBuilder.InsertStructuredDocumentTag(SdtType) s jedním ze sedmi podporovaných typů, aby se vložil nový ovládací prvek na aktuální pozici kurzoru tvůrce; volání vrátí nový StructuredDocumentTag. Nastavte Tag a Title na vráceném ovládacím prvku, aby měl identifikační řetězce, které autoři vidí ve Wordu, a nastavte PlaceholderName (podporovaný Placeholder BuildingBlock) pro text výzvy, který Word zobrazuje, když je ovládací prvek prázdný – IsShowingPlaceholderText uvádí, zda je tato výzva aktuálně zobrazena.
Krok 5: Nakonfigurujte obsah specifický pro typ
U ovládacího prvku zaškrtávacího políčka čtěte nebo nastavujte StructuredDocumentTag.Checked a zavolejte SetCheckedSymbol() / SetUncheckedSymbol() pro přizpůsobení znaků zobrazovaných pro každý stav. U ovládacího prvku data nastavte FullDate, přičemž DateDisplayFormat a DateDisplayLocale řídí, jak se vykreslí, DateStorageFormat (SdtDateStorageFormat) určuje, jak je uložen při navázání na data XML, a CalendarType (SdtCalendarType) vybírá kalendářní systém. U rozbalovacího seznamu nebo kombinovaného pole naplňte ListItems – SdtListItemCollection SdtListItem (DisplayText, Value) – před nastavením SelectedValue pro výběr aktivní položky. U ovládacího prvku prostého textu je Multiline bool vlastností na StructuredDocumentTag, kterou lze nastavit pro konfiguraci ovládacího prvku.
Krok 6: Vzhled ovládacího prvku a zamykání
Nastavte Appearance (SdtAppearance), aby určoval, jak je ovládací prvek vizuálně ohraničen ve Wordu, a Color pro nastavení jeho barvy zvýraznění. ContentsFont a EndCharacterFont řídí písmo použité pro obsah ovládacího prvku a jeho koncový znak. LockContentControl a LockContents jsou nezávislé přepínače – nastavte LockContentControl, aby se zabránilo smazání samotného ovládacího prvku, a LockContents, aby se zabránilo úpravám jeho obsahu, aniž by to ovlivnilo druhý.
Krok 7: Najít a odstranit ovládací prvky obsahu
Přečtěte Range.StructuredDocumentTags — StructuredDocumentTagCollection ohraničený na tento rozsah — a zavolejte GetById(), GetByTag() nebo GetByTitle() k nalezení konkrétního ovládacího prvku, nebo Remove() / RemoveAt() na kolekci k odstranění podle reference nebo indexu. U jednotlivého ovládacího prvku zavolejte Remove() k odstranění ovládacího prvku spolu s jeho obsahem, RemoveSelfOnly() k odstranění pouze obalu při zachování obsahu v dokumentu, nebo Clear() k vyprázdnění jeho obsahu při zachování samotného ovládacího prvku na místě.
Krok 8: Navázat ovládací prvek na vlastní data XML
Přečtěte StructuredDocumentTag.XmlMapping — instance XmlMapping — a zavolejte SetMapping(customXmlPart, xPath, prefixMapping) k navázání ovládacího prvku na existující vlastní část XML, která již je v úložišti vlastních dat XML dokumentu, přičemž použijete výraz XPath k výběru svázaného prvku. XmlMapping.IsMapped hlásí, zda je svázání aktuálně aktivní, CustomXmlPart a StoreItemId identifikují svázanou datovou část a Delete() odstraňuje mapování.
Krok 9: Zpracovat ovládací prvky obsahu, které zasahují do více sekcí
Ovládací prvek obsahu, který zasahuje do více než jedné sekce dokumentu — hlásí IsMultiSection — není reprezentován jedním uzlem StructuredDocumentTag, ale dvojicí StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, propojenou pomocí StructuredDocumentTagRangeStart.RangeEnd. Programujte proti sdílenému rozhraní IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()), pokud kód potřebuje jednotně zpracovávat jak jednosouborové, tak rozsahové formy, místo aby se rozvětvoval podle konkrétního typu.
Časté problémy a opravy
InsertStructuredDocumentTag vyvolá NotImplementedException Požadovaný SdtType – například Citation, Equation, nebo BuildingBlockGallery – není jedním ze sedmi vkládacích typů. Použijte PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, nebo Date místo toho.
InsertStructuredDocumentTag vyvolá InvalidOperationException RepeatingSection or RepeatingSectionItem byl požadován na textovém kurzoru. Tyto dva typy obalují celé odstavce nebo řádky tabulky, místo aby byly vloženy na pozici kurzoru.
Odstranění ovládacího prvku také odstraní text uvnitř něj Remove() smaže ovládací prvek a jeho obsah najednou. Call RemoveSelfOnly() místo toho, aby zachoval obsah v dokumentu a odstranil jen obal.
Zaškrtávací políčko nezobrazuje očekávaný symbol Vlastní znaky pro zaškrtnutí a odškrtnutí nebyly nikdy nastaveny. Zavolejte SetCheckedSymbol() and SetUncheckedSymbol() na ovládacím prvku.
Rozbalovací seznam nebo kombobox nezobrazuje žádné možnosti ListItems nebyl nikdy naplněn. Přidejte SdtListItem položky do kolekce ovládacího prvku ListItems kolekce, než očekáváte, že se možnosti objeví, a pak nastavte SelectedValue pro výběr aktivní.
Často kladené otázky
Jaké typy obsahových ovládacích prvků mohu vložit přímo pomocí DocumentBuilder?
PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture a Date. Ostatní hodnoty SdtType nejsou podporovány InsertStructuredDocumentTag().
Jak najdu všechny ovládací prvky obsahu s konkrétním štítkem?
Přečtěte Range.StructuredDocumentTags a zavolejte GetByTag(), nebo GetByTitle() / GetById(), pokud místo toho odpovídají těmto identifikátorům.
Jak odstraním ovládací prvek obsahu, ale zachovám jeho obsah v dokumentu?
Zavolejte StructuredDocumentTag.RemoveSelfOnly() místo Remove().
Jak navážu ovládací prvek obsahu na vlastní data XML?
Zavolejte XmlMapping.SetMapping() na XmlMapping ovládacího prvku a nasměrujte jej na existující vlastní část XML a výraz XPath v ní.
Jak se liší ovládací prvek obsahu, který zasahuje do více sekcí, od obyčejného?
Je reprezentován jako pár StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd místo jediného uzlu StructuredDocumentTag; oba tvary implementují IStructuredDocumentTag, takže IsMultiSection vám říká, s jakým tvarem pracujete.
