Arbeiten mit strukturierten Dokumenttags (Inhaltssteuerelemente)

Arbeiten mit strukturierten Dokument-Tags (Inhaltssteuerelemente)

Ein Structured Document Tag (SDT), in der Word-Benutzeroberfläche als Inhaltssteuerelement bezeichnet, umschließt einen Teil des Dokumentinhalts mit typisiertem, eingeschränktem Bearbeitungsverhalten – ein Kontrollkästchen, ein Datumswähler, eine Dropdown-Liste oder ein einfacher bzw. Rich-Text-Platzhalter. Aspose.Words FOSS für .NET modelliert diese über das Aspose.Words.Markup namespace, geleitet von dem StructuredDocumentTag Klasse. Diese Seite behandelt das Einfügen von Inhaltssteuerelementen, das Konfigurieren jedes Typs, das Finden und Entfernen derselben sowie das Binden an benutzerdefinierte XML-Daten.

Das Objektmodell des strukturierten Dokument-Tags

StructuredDocumentTag ist ein CompositeNode, das auch IMarkupNode, ITrackableNode und IStructuredDocumentTag implementiert. SdtType identifiziert, welche Art von Steuerelement es ist. Tag und Title enthalten die von Autoren in Word festgelegten Identifizierungszeichenketten; Placeholder (ein BuildingBlock) und PlaceholderName liefern den Hinweistext, der angezeigt wird, wenn das Steuerelement leer ist, gemeldet über IsShowingPlaceholderText. LockContentControl verhindert das Löschen des Steuerelements, und LockContents verhindert das Bearbeiten seines Inhalts, unabhängig voneinander.

Einfügen von Inhaltssteuerelementen

DocumentBuilder.InsertStructuredDocumentTag(SdtType) fügt ein neues Steuerelement an der Cursorposition ein, jedoch nur für sieben der SdtType Werte: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture und Date. RepeatingSection und RepeatingSectionItem können auf diese Weise nicht an einem Textcursor eingefügt werden – sie umschließen stattdessen ganze Absätze oder Tabellenzeilen. Die übrigen SdtType Werte, die in Word-Dateien vorkommen, aber in der Word-UI nicht als einfügbare Typen angezeigt werden – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group und EntityPicker – werden von dieser Einfügemethode nicht unterstützt.

Typ-spezifischer Inhalt

Der Zustand eines Kontrollkästchen-Steuerelements ist StructuredDocumentTag.Checked; SetCheckedSymbol() und SetUncheckedSymbol() setzen die für jeden Zustand angezeigten Glyphen. Ein Datumssteuerelement speichert seinen Wert in FullDate, wobei DateDisplayFormat und DateDisplayLocale steuern, wie es dargestellt wird, DateStorageFormat (ein SdtDateStorageFormat) steuert, wie es gespeichert wird, wenn es an XML-Daten gebunden ist, und CalendarType (ein SdtCalendarType) wählt das Kalendersystem aus. Eine Dropdown-Liste oder ein Kombinationsfeld stellt ihre Auswahlmöglichkeiten über ListItems bereit, ein SdtListItemCollection von SdtListItem (DisplayText, Value) mit einem SelectedValue. Die Multiline-Eigenschaft eines Nur-Text-Steuerelements erlaubt oder verbietet Zeilenumbrüche darin.

Darstellung und Sperrung

Appearance (SdtAppearance) steuert, wie das Steuerelement in Word visuell abgegrenzt wird. Color legt seine Hervorhebungsfarbe fest, und ContentsFont / EndCharacterFont bestimmen die auf den Inhalt und das abschließende Zeichen angewandte Schriftart. LockContentControl und LockContents sind unabhängige Schalter – der erste verhindert das Löschen des Steuerelements selbst, der zweite verhindert die Bearbeitung des Inhalts.

Suchen und Entfernen von Inhaltssteuerelementen

Range.StructuredDocumentTags gibt ein StructuredDocumentTagCollection zurück, das auf diesen Bereich beschränkt ist, mit GetById(), GetByTag() und GetByTitle() für gezielte Suche zusammen mit Remove() und RemoveAt(). Bei einem einzelnen StructuredDocumentTag löscht Remove() das Steuerelement und seinen Inhalt zusammen, RemoveSelfOnly() löscht nur den Wrapper und behält den Inhalt im Dokument, und Clear() leert den Inhalt des Steuerelements, während das Steuerelement selbst erhalten bleibt.

XML Datenbindung

StructuredDocumentTag.XmlMapping ist eine XmlMapping-Instanz, die eine Bindung an einen benutzerdefinierten XML-Teil im Dokument beschreibt: CustomXmlPart, XPath, PrefixMappings, StoreItemId und IsMapped. SetMapping() stellt die Bindung an einen bestehenden benutzerdefinierten XML-Teil her und Delete() entfernt sie.

Mehrabschnitts- (bereichsbezogene) Inhaltssteuerelemente

Ein Inhaltssteuerelement, das mehr als einen Abschnitt umfasst – gemeldet von IsMultiSection – wird nicht durch einen einzelnen StructuredDocumentTag-Knoten dargestellt, sondern durch ein Paar von StructuredDocumentTagRangeStart- und StructuredDocumentTagRangeEnd-Knoten, die über StructuredDocumentTagRangeStart.RangeEnd verbunden sind. Sowohl die Einzelknoten- als auch die Bereichsformen implementieren das gemeinsame IStructuredDocumentTag-Interface, sodass Code, der nur Tag, Title, SdtType, Placeholder und ähnliche Identifizierungseigenschaften benötigt, einheitlich mit beiden Formen arbeiten kann.

Tipps und bewährte Verfahren

• Prüfen Sie die unterstützten Typen von DocumentBuilder.InsertStructuredDocumentTag(), bevor Sie sich darauf verlassen – nur PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture und Date können an der Cursorposition eingefügt werden; andere Typen werfen eine Ausnahme.
• Verwenden Sie RemoveSelfOnly() anstelle von Remove(), wenn Sie ein Inhaltssteuerelement „flachlegen“ möchten – behalten Sie dessen Inhalt im Dokument, entfernen jedoch die Steuerelementhülle.
• Füllen Sie ListItems aus, bevor Sie erwarten, dass ein DropDownList- oder ComboBox-Steuerelement Auswahlmöglichkeiten anzeigt, und setzen Sie SelectedValue, um das aktive Element auszuwählen.
• Programmieren Sie gegen IStructuredDocumentTag statt direkt gegen StructuredDocumentTag, wenn Ihr Code sowohl gewöhnliche als auch mehrteilige (bereichsbezogene) Inhaltssteuerelemente auf dieselbe Weise verarbeiten muss.
• XmlMapping.SetMapping() bindet an einen benutzerdefinierten XML-Teil, der bereits im benutzerdefinierten XML-Datenspeicher des Dokuments vorhanden sein muss – fügen Sie die XML-Daten hinzu oder laden Sie sie, bevor Sie ein Steuerelement darauf abbilden.

Häufige Probleme

FAQ

Welche Inhaltssteuerelementtypen kann ich direkt mit DocumentBuilder einfügen?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture und Date. Andere SdtType-Werte werden von InsertStructuredDocumentTag() nicht unterstützt.

Wie finde ich alle Inhaltssteuerelemente mit einem bestimmten Tag?

Verwenden Sie Range.StructuredDocumentTags.GetByTag() oder GetByTitle() / GetById(), wenn Sie stattdessen danach filtern.

Wie entferne ich ein Inhaltssteuerelement, aber behalte dessen Inhalt bei?

Rufen Sie StructuredDocumentTag.RemoveSelfOnly() anstelle von Remove() auf.

Wie binde ich ein Inhaltssteuerelement an benutzerdefinierte XML-Daten?

Rufen Sie XmlMapping.SetMapping() für das Steuerelement auf, indem Sie es auf einen vorhandenen benutzerdefinierten XML-Teil und einen XPath-Ausdruck darin zeigen.

Was ist der Unterschied zwischen einem einfachen StructuredDocumentTag und einem mit Bereich?

Ein Inhaltssteuerelement, das mehr als einen Dokumentabschnitt umfasst, wird als StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd-Paar dargestellt statt als einzelner Knoten; beide Formen implementieren IStructuredDocumentTag.

API Reference Zusammenfassung

Siehe auch

• Aspose.Words for .NET — Enterprise Documentation