Práce se strukturovanými značkami dokumentu (Content Controls)

Práce se strukturovanými značkami dokumentu (ovládacími prvky obsahu)

Strukturovaný značkový tag (SDT), známý v uživatelském rozhraní Wordu jako ovládací prvek obsahu, obaluje část obsahu dokumentu s typovým, omezeným chováním úprav – zaškrtávací políčko, výběr data, rozbalovací seznam nebo zástupný prvek prostého nebo formátovaného textu. Aspose.Words FOSS pro .NET modeluje je prostřednictvím Aspose.Words.Markup jmenného prostoru, vedeného StructuredDocumentTag třídu. Tato stránka popisuje vkládání ovládacích prvků obsahu, konfiguraci každého typu, jejich vyhledávání a odstraňování a propojení s vlastními daty XML.

Objektový model strukturovaných značek dokumentu

StructuredDocumentTag je CompositeNode, který také implementuje IMarkupNode, ITrackableNode a IStructuredDocumentTag. SdtType určuje, o jaký typ ovládacího prvku se jedná. Tag a Title obsahují identifikační řetězce, které autoři nastavili ve Wordu; Placeholder (a BuildingBlock) a PlaceholderName poskytují text nápovědy zobrazovaný, když je ovládací prvek prázdný, hlášený přes IsShowingPlaceholderText. LockContentControl zabraňuje smazání ovládacího prvku a LockContents zabraňuje úpravám jeho obsahu, nezávisle na sobě.

Vkládání ovládacích prvků obsahu

DocumentBuilder.InsertStructuredDocumentTag(SdtType) vloží nový ovládací prvek na pozici kurzoru, ale jen pro sedm hodnot SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture a Date. RepeatingSection a RepeatingSectionItem nelze tímto způsobem vložit na textový kurzor – místo toho obalují celé odstavce nebo řádky tabulky. Zbývající hodnoty SdtType, které se vyskytují v souborech Word, ale nejsou v uživatelském rozhraní Wordu dostupné jako typy k vložení – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group a EntityPicker – nejsou touto metodou vkládání podporovány.

Typově specifický obsah

Stav zaškrtávacího políčka je StructuredDocumentTag.Checked; SetCheckedSymbol() a SetUncheckedSymbol() nastavují glyphy zobrazované pro každý stav. Ovládací prvek data ukládá svou hodnotu v FullDate, přičemž DateDisplayFormat a DateDisplayLocale řídí, jak je vykreslen, DateStorageFormat (je SdtDateStorageFormat) řídí, jak je uložen při svázání s daty XML, a CalendarType (je SdtCalendarType) vybírá kalendářní systém. Rozbalovací seznam nebo kombobox zveřejňuje své možnosti pomocí ListItems, SdtListItemCollection SdtListItem (DisplayText, Value) s SelectedValue. Vlastnost Multiline ovládacího prvku prostého textu povoluje nebo zakazuje zalomení řádků uvnitř něj.

Vzhled a zamykání

Appearance (SdtAppearance) řídí, jak je ovládací prvek vizuálně ohraničen ve Wordu. Color nastavuje jeho barvu zvýraznění a ContentsFont / EndCharacterFont řídí písmo použité pro jeho obsah a koncový znak. LockContentControl a LockContents jsou nezávislé přepínače – první zabraňuje smazání samotného ovládacího prvku, druhý zabraňuje úpravám toho, co je uvnitř.

Vyhledávání a odstraňování obsahových ovládacích prvků

Range.StructuredDocumentTags vrací StructuredDocumentTagCollection ohraničený na tomto rozsahu, s GetById(), GetByTag() a GetByTitle() pro cílené vyhledávání spolu s Remove() a RemoveAt(). U jednotlivého StructuredDocumentTag Remove() smaže ovládací prvek i jeho obsah najednou, RemoveSelfOnly() smaže pouze obal a ponechá jeho obsah v dokumentu a Clear() vyprázdní obsah ovládacího prvku při zachování samotného ovládacího prvku.

Vazba dat XML

StructuredDocumentTag.XmlMapping je XmlMapping instance popisující vazbu na vlastní část XML v dokumentu: CustomXmlPart, XPath, PrefixMappings, StoreItemId a IsMapped. SetMapping() navazuje vazbu na existující vlastní část XML a Delete() ji odstraňuje.

Vícedílné (rozsahové) obsahové ovládací prvky

Ovládací prvek obsahu, který zahrnuje více než jednu sekci – nahlášený IsMultiSection – není reprezentován jedním uzlem StructuredDocumentTag, ale dvojicí uzlů StructuredDocumentTagRangeStart a StructuredDocumentTagRangeEnd, spojených přes StructuredDocumentTagRangeStart.RangeEnd. Jak jednojazyková, tak rozsahová forma implementují společné rozhraní IStructuredDocumentTag, takže kód, který potřebuje jen Tag, Title, SdtType, Placeholder a podobné identifikační vlastnosti, může s oběma formami pracovat jednotně.

Tipy a osvědčené postupy

• Zkontrolujte seznam podporovaných typů DocumentBuilder.InsertStructuredDocumentTag() před tím, než se na něj spolehnete – pouze PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture a Date lze vložit na kurzor; ostatní typy vyvolají výjimku.
• Použijte RemoveSelfOnly() místo Remove(), když chcete „zploštit“ ovládací prvek obsahu – zachovejte jeho obsah v dokumentu, ale odstraňte obal ovládacího prvku.
• Naplňte ListItems před tím, než očekáváte, že ovládací prvek DropDownList nebo ComboBox zobrazí možnosti, a nastavte SelectedValue, aby vybral aktivní.
• Programujte proti IStructuredDocumentTag spíše než přímo proti StructuredDocumentTag, pokud váš kód potřebuje zpracovávat jak běžné, tak vícesekční (rozsahové) ovládací prvky obsahu stejným způsobem.
• XmlMapping.SetMapping() se váže na vlastní část XML, která již musí existovat v uživatelském úložišti dat XML dokumentu – přidejte nebo načtěte data XML před přiřazením ovládacího prvku k ní.

Časté problémy

FAQ

Jaké typy ovládacích prvků obsahu mohu vložit přímo pomocí DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture a Date. Další hodnoty SdtType nejsou podporovány InsertStructuredDocumentTag().

Jak najdu všechny ovládací prvky obsahu s konkrétním štítkem?

Použijte Range.StructuredDocumentTags.GetByTag(), nebo GetByTitle() / GetById(), pokud místo toho porovnáváte tyto.

Jak odebrat ovládací prvek obsahu, ale zachovat jeho obsah?

Zavolejte StructuredDocumentTag.RemoveSelfOnly() místo Remove().

Jak navázat ovládací prvek obsahu na vlastní data XML?

Zavolejte XmlMapping.SetMapping() na ovládacím prvku, nasměrujte jej na existující vlastní část XML a na výraz XPath v ní.

Jaký je rozdíl mezi prostým StructuredDocumentTag a tím s rozsahem?

Ovládací prvek obsahu, který zasahuje více než jednu sekci dokumentu, je reprezentován jako dvojice StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd místo jediného uzlu; oba tvary implementují IStructuredDocumentTag.

API Reference Souhrn

Viz také:

• Aspose.Words for .NET — Enterprise Documentation