Wie man mit Structured Document Tags in .NET arbeitet

Schritt 1: Paket installieren

Aspose.Words FOSS für .NET veröffentlicht noch kein NuGet-Paket – bauen Sie die Bibliothek stattdessen aus dem Quellcode. Klonen Sie https://github.com/aspose-words-foss/Aspose.Words-FOSS-for-.NET.git, bauen Sie dann Aspose.Words.sln in der Release-Konfiguration mit dem .NET-SDK und binden Sie die resultierende Aspose.Words-Assembly in Ihr Projekt ein. Die Bibliothek zielt auf .NET Standard 2.0 ab, sodass sie auf .NET Framework 4.6.2+ und .NET 6/8/10 läuft.

Schritt 2: Erforderliche Klassen importieren

Fügen Sie eine using Aspose.Words;-Direktive für Document und DocumentBuilder sowie eine using Aspose.Words.Markup;-Direktive für StructuredDocumentTag, SdtType, SdtListItem, SdtListItemCollection, XmlMapping und die anderen Content-Control-Klassen, die in diesem Handbuch behandelt werden, hinzu.

Schritt 3: Prüfen, welche Content-Control-Typen Sie einfügen können

Bevor Sie einfügen, prüfen Sie, ob das Ziel SdtType einer der sieben von DocumentBuilder.InsertStructuredDocumentTag(SdtType) akzeptierten Typen ist: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture und Date. RepeatingSection und RepeatingSectionItem können mit dieser Methode nicht an einem Textcursor eingefügt werden – sie umschließen stattdessen ganze Absätze oder Tabellenzeilen. Die übrigen SdtType-Werte, die in einer Word-Datei vorkommen können, aber in der Word-Benutzeroberfläche nicht als einfügbar angezeigt werden – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group und EntityPicker – werden von dieser Einfügemethode überhaupt nicht akzeptiert.

Schritt 4: Ein Content-Control am Cursor einfügen

Rufen Sie DocumentBuilder.InsertStructuredDocumentTag(SdtType) mit einem der sieben unterstützten Typen auf, um ein neues Control an der aktuellen Cursorposition des Builders einzufügen; der Aufruf gibt das neue StructuredDocumentTag zurück. Setzen Sie Tag und Title auf dem zurückgegebenen Control, um ihm die Kennzeichnungszeichenfolgen zu geben, die Autoren in Word sehen, und setzen Sie PlaceholderName (unterstützt durch ein Placeholder BuildingBlock) für den Hinweistext, den Word anzeigt, während das Control leer ist – IsShowingPlaceholderText gibt an, ob dieser Hinweis derzeit angezeigt wird.

Schritt 5: Typbezogenen Inhalt konfigurieren

Bei einem Checkbox-Control lesen oder setzen Sie StructuredDocumentTag.Checked und rufen SetCheckedSymbol() / SetUncheckedSymbol() auf, um die für jeden Zustand angezeigten Glyphen anzupassen. Bei einem Datums-Control setzen Sie FullDate, wobei DateDisplayFormat und DateDisplayLocale steuern, wie es dargestellt wird, DateStorageFormat (SdtDateStorageFormat) steuert, wie es gespeichert wird, wenn es an XML-Daten gebunden ist, und CalendarType (SdtCalendarType) wählt das Kalendersystem aus. Für eine Dropdown-Liste oder ein Kombinationsfeld füllen Sie ListItems – ein SdtListItemCollection von SdtListItem (DisplayText, Value) – bevor Sie SelectedValue setzen, um die aktive Auswahl zu bestimmen. Für ein Klartext-Control ist Multiline eine bool-Eigenschaft von StructuredDocumentTag, die zur Konfiguration des Controls gesetzt werden kann.

Schritt 6: Erscheinungsbild und Sperrung des Controls

Setzen Sie Appearance (SdtAppearance), um zu steuern, wie das Control in Word optisch abgegrenzt wird, und Color, um seine Hervorhebungsfarbe festzulegen. ContentsFont und EndCharacterFont steuern die auf den Inhalt des Controls angewendete Schriftart bzw. das abschließende Zeichen. LockContentControl und LockContents sind unabhängige Schalter – setzen Sie LockContentControl, um das Löschen des Controls selbst zu verhindern, und LockContents, um die Bearbeitung des Inhalts zu blockieren, ohne den anderen zu beeinflussen.

Schritt 7: Inhaltssteuerelemente finden und entfernen

Lesen Sie Range.StructuredDocumentTags – ein StructuredDocumentTagCollection mit diesem Bereich – und rufen Sie GetById(), GetByTag() oder GetByTitle() auf, um ein bestimmtes Steuerelement zu finden, oder Remove() / RemoveAt() in der Sammlung, um eines nach Referenz oder Index zu entfernen. Bei einem einzelnen Steuerelement rufen Sie Remove() auf, um das Steuerelement zusammen mit seinem Inhalt zu löschen, RemoveSelfOnly(), um nur den Wrapper zu löschen und den Inhalt im Dokument zu behalten, oder Clear(), um den Inhalt zu leeren, während das Steuerelement selbst an Ort und Stelle bleibt.

Schritt 8: Ein Steuerelement an benutzerdefinierte XML-Daten binden

Lesen Sie StructuredDocumentTag.XmlMapping – eine XmlMapping-Instanz – und rufen Sie SetMapping(customXmlPart, xPath, prefixMapping) auf, um das Steuerelement an einen bereits im benutzerdefinierten XML-Datenspeicher des Dokuments vorhandenen benutzerdefinierten XML-Teil zu binden, wobei ein XPath-Ausdruck verwendet wird, um das gebundene Element auszuwählen. XmlMapping.IsMapped gibt an, ob eine Bindung derzeit aktiv ist, CustomXmlPart und StoreItemId identifizieren den gebundenen Datenteil, und Delete() entfernt die Zuordnung.

Schritt 9: Inhaltssteuerelemente behandeln, die mehrere Abschnitte umfassen

Ein Inhaltssteuerelement, das mehr als einen Dokumentabschnitt umfasst – gemeldet von IsMultiSection – wird nicht durch einen einzelnen StructuredDocumentTag-Knoten, sondern durch ein StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd-Paar dargestellt, das über StructuredDocumentTagRangeStart.RangeEnd verbunden ist. Programmieren Sie gegen die gemeinsame IStructuredDocumentTag-Schnittstelle (Tag, Title, Placeholder, PlaceholderName, Appearance, IsShowingPlaceholderText, RemoveSelfOnly()), wenn Code sowohl die Einzelknoten- als auch die Bereichsformen einheitlich behandeln muss, anstatt je nach konkretem Typ zu verzweigen.