Praca ze znacznikami strukturalnymi dokumentu (kontrolki treści)

Praca ze znacznikami strukturalnymi dokumentu (kontrolki treści)

Tag strukturalny dokumentu (SDT), znany w interfejsie Word jako content control, otacza fragment treści dokumentu z typowym, ograniczonym zachowaniem edycji — checkbox, date picker, drop-down list lub plain- lub rich-text placeholder. Aspose.Words FOSS dla .NET modeluje je przez Aspose.Words.Markup przestrzeń nazw, nagłówkiem jest StructuredDocumentTag klasa. Ta strona opisuje wstawianie content controls, konfigurowanie każdego typu, znajdowanie i usuwanie ich oraz powiązanie ich z niestandardowymi danymi XML.

Model obiektowy znacznika strukturalnego dokumentu

StructuredDocumentTag jest CompositeNode, który dodatkowo implementuje IMarkupNode, ITrackableNode i IStructuredDocumentTag. SdtType określa, jakiego rodzaju kontrolką jest. Tag i Title przechowują ciągi identyfikacyjne ustawione przez autorów w Wordzie; Placeholder (jako BuildingBlock) oraz PlaceholderName dostarczają tekst podpowiedzi wyświetlany, gdy kontrolka jest pusta, zgłaszany przez IsShowingPlaceholderText. LockContentControl zapobiega usunięciu kontrolki, a LockContents zapobiega edycji jej zawartości, niezależnie od siebie.

Wstawianie kontrolek treści

DocumentBuilder.InsertStructuredDocumentTag(SdtType) wstawia nową kontrolkę w miejscu kursora, ale tylko dla siedmiu wartości SdtType: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture oraz Date. RepeatingSection i RepeatingSectionItem nie mogą być wstawiane w miejscu kursora tekstu w ten sposób – obejmują całe akapity lub wiersze tabeli. Pozostałe wartości SdtType, które występują w plikach Word, ale nie są dostępne w interfejsie Word jako typy wstawialne – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group i EntityPicker – nie są obsługiwane przez tę metodę wstawiania.

Treść specyficzna dla typu

Stan kontrolki pola wyboru to StructuredDocumentTag.Checked; SetCheckedSymbol() i SetUncheckedSymbol() ustawiają glify wyświetlane dla każdego stanu. Kontrolka daty przechowuje swoją wartość w FullDate, przy czym DateDisplayFormat i DateDisplayLocale kontrolują sposób jej renderowania, DateStorageFormat (jest SdtDateStorageFormat) kontroluje sposób przechowywania, gdy jest powiązana z danymi XML, a CalendarType (jest SdtCalendarType) wybiera system kalendarzowy. Lista rozwijana lub pole kombi udostępnia wybory za pomocą ListItems, jest SdtListItemCollection typu SdtListItem (DisplayText, Value) z SelectedValue. Właściwość Multiline kontrolki tekstowej pozwala lub zabrania wstawiania znaków nowej linii wewnątrz niej.

Wygląd i blokowanie

Appearance (SdtAppearance) kontroluje, jak kontrolka jest wizualnie wyznaczona w programie Word. Color ustawia jej kolor podświetlenia, a ContentsFont / EndCharacterFont kontrolują czcionkę zastosowaną do jej zawartości oraz znak końcowy. LockContentControl i LockContents są niezależnymi przełącznikami — pierwszy blokuje usunięcie samej kontrolki, drugi blokuje edycję jej zawartości.

Znajdowanie i usuwanie kontrolek treści

Range.StructuredDocumentTags zwraca StructuredDocumentTagCollection ograniczony do tego zakresu, z GetById(), GetByTag() i GetByTitle() służącymi do ukierunkowanego wyszukiwania wraz z Remove() i RemoveAt(). Dla pojedynczego StructuredDocumentTag, Remove() usuwa kontrolkę i jej zawartość razem, RemoveSelfOnly() usuwa tylko opakowanie i pozostawia jej zawartość w dokumencie, a Clear() opróżnia zawartość kontrolki, zachowując samą kontrolkę.

XML powiązanie danych

StructuredDocumentTag.XmlMapping jest XmlMapping opisującym powiązanie z niestandardową częścią XML w dokumencie: CustomXmlPart, XPath, PrefixMappings, StoreItemId i IsMapped. SetMapping() ustanawia powiązanie z istniejącą niestandardową częścią XML, a Delete() usuwa je.

Wielosekcyjne (zakresowe) kontrolki treści

Kontrola treści, która obejmuje więcej niż jedną sekcję – zgłoszona przez IsMultiSection – jest reprezentowana nie przez pojedynczy StructuredDocumentTag węzeł, lecz przez parę węzłów StructuredDocumentTagRangeStart i StructuredDocumentTagRangeEnd, połączonych przez StructuredDocumentTagRangeStart.RangeEnd. Obie formy, zarówno pojedynczego węzła, jak i zakresowa, implementują wspólny interfejs IStructuredDocumentTag, więc kod, który potrzebuje jedynie Tag, Title, SdtType, Placeholder oraz podobnych właściwości identyfikujących, może działać z obiema formami jednolicie.

Wskazówki i najlepsze praktyki

• Sprawdź listę obsługiwanych typów DocumentBuilder.InsertStructuredDocumentTag() przed jej użyciem – tylko PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture i Date mogą być wstawiane w miejscu kursora; inne typy generują wyjątek.
• Użyj RemoveSelfOnly() zamiast Remove(), gdy chcesz “spłaszczyć” kontrolę treści – zachowaj jej zawartość w dokumencie, ale usuń otoczkę kontrolną.
• Wypełnij ListItems zanim oczekujesz, że kontrolka DropDownList lub ComboBox wyświetli opcje, i ustaw SelectedValue, aby wybrać aktywną.
• Programuj w oparciu o IStructuredDocumentTag, a nie bezpośrednio StructuredDocumentTag, jeśli Twój kod musi obsługiwać zarówno zwykłe, jak i wielosekcyjne (zakresowe) kontrolki treści w ten sam sposób.
• XmlMapping.SetMapping() wiąże się z niestandardową częścią XML, która musi już istnieć w niestandardowym magazynie danych XML dokumentu – dodaj lub załaduj dane XML przed powiązaniem kontrolki z nią.

Typowe problemy

FAQ

Jakie typy kontrolek zawartości mogę wstawiać bezpośrednio przy użyciu DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture i Date. Inne wartości SdtType nie są obsługiwane przez InsertStructuredDocumentTag().

Jak znaleźć wszystkie kontrolki zawartości z określonym tagiem?

Użyj Range.StructuredDocumentTags.GetByTag(), albo GetByTitle() / GetById(), jeśli dopasowujesz się do nich zamiast.

Jak usunąć kontrolkę zawartości, zachowując jej zawartość?

Wywołaj StructuredDocumentTag.RemoveSelfOnly() zamiast Remove().

Jak powiązać kontrolkę zawartości z niestandardowymi danymi XML?

Wywołaj XmlMapping.SetMapping() na kontrolce, wskazując ją na istniejącą niestandardową część XML oraz wyrażenie XPath w jej obrębie.

Jaka jest różnica między zwykłym StructuredDocumentTag a wersją zakresową?

Kontrola zawartości, która obejmuje więcej niż jedną sekcję dokumentu, jest reprezentowana jako para StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd zamiast pojedynczego węzła; oba formy implementują IStructuredDocumentTag.

API Reference Podsumowanie

Zobacz także

• Aspose.Words for .NET — Enterprise Documentation