Jak pracować ze znacznikami strukturalnymi dokumentu w .NET

Krok 1: Zainstaluj pakiet

Aspose.Words FOSS for .NET nie opublikował jeszcze pakietu NuGet – zbuduj bibliotekę ze źródeł. Sklonuj https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, a następnie zbuduj Aspose.Words.sln w konfiguracji Release przy użyciu SDK .NET i odwołaj się do powstałego zestawu Aspose.Words w swoim projekcie. Biblioteka jest skierowana na .NET Standard 2.0, więc działa na .NET Framework 4.6.2+ oraz .NET 6/8/10.

Krok 2: Zaimportuj wymagane klasy

Dodaj dyrektywę using Aspose.Words; dla Document i DocumentBuilder, oraz dyrektywę using Aspose.Words.Markup; dla StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping i pozostałych klas kontrolek treści, które omawia ten przewodnik.

Krok 3: Sprawdź, które typy kontrolki treści możesz wstawić

Przed wstawieniem sprawdź, czy docelowy SdtType jest jednym z siedmiu typów akceptowanych przez DocumentBuilder.InsertStructuredDocumentTag(SdtType): PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture oraz Date. RepeatingSection i RepeatingSectionItem nie mogą być wstawiane przy użyciu kursora tekstowego tą metodą — zamiast tego obejmują całe akapity lub wiersze tabeli. Pozostałe wartości SdtType, które mogą występować w pliku Word, ale nie są dostępne w interfejsie Word jako typy wstawialne — None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group i EntityPicker — nie są w ogóle akceptowane przez tę metodę wstawiania.

Krok 4: Wstaw kontrolkę treści w miejscu kursora

Wywołaj DocumentBuilder.InsertStructuredDocumentTag(SdtType) z jednym z siedmiu obsługiwanych typów, aby wstawić nową kontrolkę w bieżącej pozycji kursora budowniczego; wywołanie zwraca nową StructuredDocumentTag. Ustaw Tag i Title na zwróconej kontrolce, aby nadać jej identyfikujące ciągi widoczne dla autorów w Wordzie, oraz ustaw PlaceholderName (zasilany przez Placeholder BuildingBlock) jako tekst podpowiedzi wyświetlany przez Word, gdy kontrolka jest pusta — IsShowingPlaceholderText informuje, czy ta podpowiedź jest aktualnie wyświetlana.

Krok 5: Skonfiguruj zawartość specyficzną dla typu

W przypadku kontrolki pola wyboru odczytaj lub ustaw StructuredDocumentTag.Checked i wywołaj SetCheckedSymbol() / SetUncheckedSymbol(), aby dostosować glify wyświetlane dla każdego stanu. W przypadku kontrolki daty ustaw FullDate, przy czym DateDisplayFormat i DateDisplayLocale kontrolują sposób jej renderowania, DateStorageFormat (SdtDateStorageFormat) kontroluje, jak jest przechowywana po powiązaniu z danymi XML, a CalendarType (SdtCalendarType) wybiera system kalendarzowy. Dla listy rozwijanej lub pola kombi wypełnij ListItems — SdtListItemCollection SdtListItem (DisplayText, Value) — przed ustawieniem SelectedValue, aby wybrać aktywną opcję. W przypadku kontrolki tekstu zwykłego, Multiline jest własnością bool na StructuredDocumentTag, którą można ustawić w celu skonfigurowania kontrolki.

Krok 6: Kontrola wyglądu i blokowanie

Ustaw Appearance (SdtAppearance), aby kontrolować, jak kontrolka jest wizualnie oddzielona w Wordzie, oraz Color, aby określić jej kolor podświetlenia. ContentsFont i EndCharacterFont kontrolują czcionkę zastosowaną do zawartości kontrolki oraz jej końcowy znak. LockContentControl i LockContents są niezależnymi przełącznikami — ustaw LockContentControl, aby zablokować usuwanie samej kontrolki, oraz LockContents, aby zablokować edycję jej zawartości, nie wpływając na drugą opcję.

Krok 7: Znajdź i usuń kontrolki treści

Odczytaj Range.StructuredDocumentTags — StructuredDocumentTagCollection o zakresie obejmującym ten fragment — i wywołaj GetById(), GetByTag() lub GetByTitle(), aby zlokalizować konkretną kontrolkę, lub Remove() / RemoveAt() na kolekcji, aby usunąć ją za pomocą referencji lub indeksu. W przypadku pojedynczej kontrolki wywołaj Remove(), aby usunąć kontrolkę wraz z jej zawartością, RemoveSelfOnly(), aby usunąć tylko kontener, pozostawiając zawartość w dokumencie, lub Clear(), aby opróżnić jej zawartość, zachowując samą kontrolkę.

Krok 8: Powiąż kontrolkę z niestandardowymi danymi XML

Odczytaj StructuredDocumentTag.XmlMapping — instancję XmlMapping — i wywołaj SetMapping(customXmlPart, xPath, prefixMapping), aby powiązać kontrolkę z istniejącą niestandardową częścią XML już znajdującą się w niestandardowym magazynie danych XML dokumentu, używając wyrażenia XPath do wybrania powiązanego elementu. XmlMapping.IsMapped informuje, czy powiązanie jest aktualnie aktywne, CustomXmlPart i StoreItemId identyfikują powiązaną część danych, a Delete() usuwa mapowanie.

Krok 9: Obsłuż kontrolki treści obejmujące wiele sekcji

Kontrolka treści obejmująca więcej niż jedną sekcję dokumentu — zgłaszana przez IsMultiSection — jest reprezentowana nie przez pojedynczy węzeł StructuredDocumentTag, lecz przez parę StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd, połączoną przez StructuredDocumentTagRangeStart.RangeEnd. Programuj przeciwko wspólnemu interfejsowi IStructuredDocumentTag (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()), gdy kod musi obsługiwać zarówno formę jednowęzłową, jak i zakresową w jednolity sposób, zamiast rozgałęziać się w zależności od konkretnego typu.