ContentControl-Elemente

  • Artikel

Inhaltssteuerelemente bieten Ihnen eine Möglichkeit, Dokumente und Vorlagen zu entwerfen, die die folgenden Features aufweisen:

Informationen zu Inhaltssteuerelementen

Inhaltssteuerelemente stellen eine Benutzeroberfläche bereit, die für Benutzereingaben und Druck optimiert ist. Wenn Sie einem Dokument ein Inhaltssteuerelement hinzufügen, wird das Steuerelement durch einen Rahmen, einen Titel und temporären Text identifiziert, der Anweisungen für den Benutzer bereitstellen kann. Der Rahmen und der Titel des Steuerelements werden nicht in gedruckten Versionen des Dokuments angezeigt.

Wenn Sie z. B. möchten, dass der Benutzer ein Datum in einem Abschnitt Ihres Dokuments eingibt, können Sie dem Dokument ein Datumsauswahl-Inhaltssteuerelement hinzufügen. Wenn Benutzer auf das Steuerelement klicken, wird die Datumsauswahl-Standardbenutzeroberfläche angezeigt. Sie können die Eigenschaften des Steuerelements auch so festlegen, dass der regionale Kalender festgelegt wird, der angezeigt wird, und Sie können das Datumsformat angeben. Nachdem der Benutzer ein Datum ausgewählt hat, wird die Benutzeroberfläche des Steuerelements ausgeblendet, und nur das Datum wird angezeigt, wenn der Benutzer das Dokument druckt.

Inhaltssteuerelemente unterstützen Sie auch bei den folgenden Aufgaben:

  • Verhindern, dass Benutzer Teile eines Dokuments bearbeiten oder löschen. Dies ist sinnvoll, wenn Informationen in einem Dokument oder einer Vorlage vorhanden sind, die Benutzer lesen, jedoch nicht bearbeiten können sollen, oder wenn Benutzer Steuerelemente bearbeiten, jedoch nicht löschen dürfen.

  • Binden von Teilen eines Dokuments oder einer Vorlage an Daten. Sie können Inhaltssteuerelemente an Datenbankfelder, verwaltete Objekte im .NET Framework, XML-Elemente binden, die im Dokument gespeichert sind, und andere Datenquellen.

    In Projekten auf Dokumentebene können Sie dem Dokument Inhaltssteuerelemente zur Entwurfszeit oder zur Laufzeit hinzufügen. In VSTO-Add-In-Projekten können Sie einem beliebigen geöffneten Dokument zur Laufzeit Inhaltssteuerelemente hinzufügen. Weitere Informationen finden Sie unter How to: Add content controls to Word documents.

Hinweis

Sie können Inhaltssteuerelemente nur in Dokumenten verwenden, die im Open XML-Format gespeichert sind. Inhaltssteuerelemente können nicht in Dokumenten verwendet werden, die im Word 97-2003-Dokumentformat (DOC) gespeichert sind.

Typen von Inhaltssteuerelementen

Es gibt neun verschiedene Typen von Inhaltssteuerelementen, die Sie Dokumenten hinzufügen können. Die meisten der Inhaltssteuerelemente besitzen einen entsprechenden Typ im Namespace Microsoft.Office.Tools.Word. Sie können auch einen generischen Namespace ContentControl verwenden, der eines der verfügbaren Inhaltssteuerelemente darstellen kann. Eine exemplarische Vorgehensweise, die die Verwendung der einzelnen verfügbaren Inhaltssteuerelemente veranschaulicht, finden Sie unter Walkthrough: Create a template by using content controls.

Mit einem Bausteinkatalog können Benutzer aus einer Liste von Dokumentbausteinen auswählen, die in ein Dokument eingefügt werden sollen. Ein Dokumentbaustein ist ein Inhaltselement, das erstellt wurde, um mehrere Male verwendet zu werden, z. B. eine allgemeine Titelseite, eine formatierte Tabelle oder ein Header . Weitere Informationen finden Sie unter dem BuildingBlockGalleryContentControl-Typ. Weitere Informationen zu Bausteinen finden Sie unter What's new for developers in Word 2007.

Kontrollkästchen

Ein Kontrollkästchen stellt eine Benutzeroberfläche zur Verfügung, die einen binären Zustand darstellt: aktiviert oder deaktiviert.

Im Gegensatz zu den anderen Inhaltssteuerelementtypen stellt die Visual Studio-Tools für Office-Laufzeit keinen bestimmten Typ bereit, der ein Kontrollkästchen-Inhaltssteuerelement darstellt. Es gibt also keinen CheckBoxContentControl-Typ. Sie können jedoch trotzdem ein Kontrollkästchen-Inhaltssteuerelement erstellen, indem Sie ein generisches ContentControl einem Dokument programmgesteuert hinzufügen. Weitere Informationen finden Sie unter Kontrollkästchen-Inhaltssteuerelemente in Word-Projekten.

Kombinationsfeld

Ein Kombinationsfeld zeigt eine Liste von Elementen an, die Benutzer auswählen können. Im Gegensatz zu einer Dropdownliste ermöglicht das Kombinationsfeld das Hinzufügen eigener Elemente. Weitere Informationen finden Sie unter dem ComboBoxContentControl-Typ.

Datumsauswahl

Eine Datumsauswahl stellt eine Kalenderbenutzeroberfläche zum Auswählen eines Datums zur Verfügung. Der Kalender wird angezeigt, wenn der Endbenutzer auf den Dropdownpfeil im Steuerelement klickt. Sie können regionale Kalender und verschiedene Datumsformate verwenden. Weitere Informationen finden Sie unter dem DatePickerContentControl-Typ.

Eine Dropdownliste zeigt eine Liste von Elementen an, die Benutzer auswählen können. Im Gegensatz zu einem Kombinationsfeld ermöglicht die Dropdownliste Benutzern nicht das Hinzufügen oder Bearbeiten von Elementen. Weitere Informationen finden Sie unter dem DropDownListContentControl-Typ.

Group

Ein Gruppensteuerelement definiert einen geschützten Bereich eines Dokuments, den Benutzer weder bearbeiten noch löschen können. Ein Gruppensteuerelement kann beliebige Dokumentelemente enthalten, z. B. Text, Tabellen, Grafiken und andere Inhaltssteuerelemente. Weitere Informationen finden Sie unter dem GroupContentControl-Typ.

Picture

Ein Bildsteuerelement zeigt ein Bild an. Sie können das Bild zur Entwurfszeit oder zur Laufzeit angeben, oder Benutzer können auf dieses Steuerelement klicken, um ein Bild auszuwählen, das in das Dokument eingefügt werden soll. Weitere Informationen finden Sie unter dem PictureContentControl-Typ.

Rich-Text

Ein Rich-Text-Steuerelement enthält Text oder andere Elemente, z. B. Tabellen, Bilder oder andere Inhaltssteuerelemente. Weitere Informationen finden Sie unter dem RichTextContentControl-Typ.

Nur-Text

Ein Nur-Text-Steuerelement enthält Text. Ein Nur-Text-Steuerelement kann keine anderen Elemente (z. B. Tabellen, Bilder oder andere Inhaltssteuerelemente) enthalten. Darüber hinaus weist der gesamte Text in einem Nur-Text-Steuerelement die gleiche Formatierung auf. Wenn Sie z. B. ein Wort in einem Satz kursiv formatieren, das sich in einem Nur-Text-Steuerelement befindet, wird der gesamte Text im Steuerelement kursiv formatiert. Weitere Informationen finden Sie unter dem PlainTextContentControl-Typ.

Generisches Inhaltssteuerelement

Ein generisches Inhaltssteuerelement ist ein ContentControl-Objekt, das jeden der verfügbaren Typen von Steuerelementen darstellen kann. Sie können ein ContentControl-Objekt so ändern, dass es sich wie ein anderer Typ von Inhaltssteuerelement verhält, indem Sie die Eigenschaft Type verwenden. Wenn Sie z. B. ein ContentControl-Objekt erstellen, das ein Nur-Text-Steuerelement darstellt, können Sie dieses zur Laufzeit so ändern, dass es sich wie ein Kombinationsfeld verhält.

Sie können ContentControl-Objekte nur zur Laufzeit erstellen, nicht zur Entwurfszeit. Weitere Informationen finden Sie unter How to: Add content controls to Word documents.

Allgemeine Features von Inhaltssteuerelementen

Die meisten Inhaltssteuerelemente verwenden eine Sammlung von Elementen gemeinsam, die Sie verwenden können, um allgemeine Aufgaben auszuführen. In der folgenden Tabelle werden einige der Aufgaben beschrieben, die Sie mithilfe dieser Elemente ausführen können.

Aufgabe: Aktion
Abrufen oder Festlegen des Texts, der im Steuerelement angezeigt wird. Verwenden Sie die Text-Eigenschaft . Hinweis: Die PictureContentControl Und ContentControl Typen besitzen diese Eigenschaft nicht.
Abrufen oder Festlegen des temporären Texts, der im Steuerelement angezeigt wird, bis ein Benutzer das Steuerelement bearbeitet, das Steuerelement mit Daten aus einer Datenquelle aufgefüllt wird oder der Inhalt des Steuerelements gelöscht wird. Verwenden Sie die PlaceholderText-Eigenschaft . Hinweis: Der PictureContentControl Typ besitzt diese Eigenschaft nicht.
Abrufen oder Festlegen des Titels, der im Rahmen des Inhaltssteuerelements angezeigt wird, wenn der Benutzer darauf klickt. Verwenden Sie die Title-Eigenschaft .
Automatisches Entfernen des Steuerelement aus dem Dokument, nachdem der Benutzer das Steuerelement bearbeitet hat. (Der Text im Steuerelement verbleibt im Dokument.) Verwenden Sie die temporäre Eigenschaft.
Ausführen von Code, wenn der Benutzer im Inhaltssteuerelement klickt oder wenn der Cursor programmgesteuert in das Inhaltssteuerelement verschoben wird. Behandeln des Entering-Ereignisses des Steuerelements.
Ausführen von Code, wenn der Benutzer außerhalb des Inhaltssteuerelements klickt oder der Cursor programmgesteuert aus dem Inhaltssteuerelement verschoben wird. Behandeln des Exiting-Ereignisses des Steuerelements.
Ausführen von Code, nachdem das Inhaltssteuerelement als Ergebnis eines Vorgangs "Wiederholen" oder "Rückgängig" dem Dokument hinzugefügt wurde. Behandeln des Added-Ereignisses des Steuerelements.
Ausführen von Code, kurz bevor das Inhaltssteuerelement aus dem Dokument gelöscht wird. Behandeln des Deleting-Ereignisses des Steuerelements.

Schützen von Teilen von Dokumenten mithilfe von Inhaltssteuerelementen

Wenn Sie einen Teil eines Dokuments schützen, verhindern Sie dass Benutzer den Inhalt in diesem Teil des Dokuments ändern oder löschen können. Es gibt mehrere Möglichkeiten, wie Sie Teile eines Dokuments mithilfe von Inhaltssteuerelementen schützen können.

Wenn sich der Bereich, den Sie schützen möchten, innerhalb eines Inhaltssteuerelements befindet, können Sie Eigenschaften des Inhaltssteuerelements verwenden, um zu verhindern, dass Benutzer das Steuerelement bearbeiten oder löschen können:

  • Die LockContents-Eigenschaft verhindert, dass Benutzer den Inhalt bearbeiten.

  • Die LockContentControl-Eigenschaft verhindert, dass Benutzer das Steuerelement löschen.

    Wenn sich der Bereich, den Sie schützen möchten, nicht innerhalb eines Inhaltssteuerelements befindet, oder wenn Sie einen Bereich schützen möchten, der Inhaltssteuerelemente und andere Inhaltstypen enthält, können Sie den gesamten Bereich in einem GroupContentControl positionieren. Im Gegensatz zu anderen Inhaltssteuerelementen stellt ein GroupContentControl keine Benutzeroberfläche zur Verfügung, die für den Benutzer sichtbar ist. Sein einziger Zweck besteht darin, einen Bereich zu definieren, den Benutzern nicht bearbeiten können.

Hinweis

Wenn Sie ein GroupContentControl erstellen, das eingebettete Inhaltssteuerelemente enthält, sind die eingebetteten Inhaltssteuerelemente nicht automatisch geschützt. Sie müssen die LockContents-Eigenschaft jedes eingebetteten Steuerelements verwenden, um zu verhindern, dass Benutzer ihre Inhalte bearbeiten.

Weitere Informationen zum Verwenden von Inhaltssteuerelementen zum Schützen von Teilen von Dokumenten finden Sie unter How to: Protect parts of documents by using content controls.

Binden von Daten an Inhaltssteuerelemente

Sie können Daten in Dokumenten anzeigen, indem Sie ein Inhaltssteuerelement an eine Datenquelle binden. Wenn die Datenquelle aktualisiert wird, spiegelt das Inhaltssteuerelement die Änderungen. Sie können Änderungen auch in der Datenquelle speichern.

Inhaltssteuerelemente stellen die folgenden Datenbindungsoptionen zur Verfügung:

  • Sie können Inhaltssteuerelemente an Datenbankfelder oder verwaltete Objekte binden, indem Sie das gleiche Datenbindungsmodell wie Windows Forms verwenden.

  • Sie können Inhaltssteuerelemente an Elemente in XML-Elementen (auch als benutzerdefinierte XML-Komponenten bezeichnet) binden, die in das Dokument eingebettet sind.

    Eine Übersicht über das Binden von Hoststeuerelementen in Office-Lösungen an Daten finden Sie unter Binden von Daten an Steuerelemente in Office-Lösungen.

Verwenden des Windows Forms-Datenbindungsmodells

Die meisten Inhaltssteuerelemente unterstützen das einfache Datenbindungsmodell, das Windows Forms verwendet. Einfache Datenbindung bedeutet, dass ein Steuerelement an ein einzelnes Datenelement gebunden ist, z. B. an einen Wert in einer Spalte einer Datentabelle. Weitere Informationen finden Sie unter Datenbindung und Windows Forms.

In Projekten auf Dokumentebene können Sie Daten mithilfe des Fensters "Datenquellen " in Visual Studio an Inhaltssteuerelemente binden. Weitere Informationen zum Hinzufügen von datengebundenen Inhaltssteuerelementen zu Dokumenten finden Sie unter How to: Populate documents with data from a database and How to: Populate documents with data from objects.

In der folgenden Tabelle sind die Inhaltssteuerelemente aufgeführt, die Sie im Fenster "Datenquellen " an jeden Datentyp binden können.

Datentyp Standard-Inhaltssteuerelement Andere Inhaltssteuerelemente, die an diesen Datentyp gebunden werden können
Boolean

Byte

Char

Double

Enum

Guid

Int16

Int32

Int64

SByte

Single

String

TimeSpan

UInt16

UInt32

UInt64		 PlainTextContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

DatePickerContentControl

RichTextContentControl
DateTime DatePickerContentControl BuildingBlockGalleryContentControl

ComboBoxContentControl

PlainTextContentControl

RichTextContentControl
Image

Byte-Array		 PictureContentControl Keine

In Projekten auf Dokumentebene und VSTO-Add-In-Projekten können Sie ein Inhaltssteuerelement programmgesteuert an eine Datenquelle mithilfe der Methode Add der Eigenschaft DataBindings des Steuerelements binden. Wenn Sie dies tun, übergeben Sie den Zeichenfolgentext an den PropertyName-Parameter der Add Methode. Die Text-Eigenschaft ist die Standarddatenbindungseigenschaft von Inhaltssteuerelementen.

Inhaltssteuerelemente unterstützen auch bidirektionale Datenbindung, bei der Änderungen im Steuerelement in der Datenquelle aktualisiert werden. Weitere Informationen finden Sie unter How to: Update a data source with data from a host control.

Hinweis

Inhaltssteuerelemente unterstützen keine komplexe Datenbindung. Wenn Sie ein DropDownListContentControl oder ComboBoxContentControl mithilfe des Windows Forms-Datenmodells an eine Datenquelle binden, wird Benutzern beim Klicken auf das Steuerelement nur ein einziger Wert angezeigt. Wenn Sie diese Steuerelemente an einen Satz von Datenwerten binden möchten, aus denen Benutzer auswählen können, können Sie diese Steuerelemente an Elemente in einem benutzerdefinierten XML-Abschnitt binden.

Binden von Inhaltssteuerelementen an benutzerdefinierte XML-Komponenten

Sie können einige Inhaltssteuerelemente an Elemente in benutzerdefinierten XML-Abschnitten binden, die im Dokument eingebettet sind. Weitere Informationen zu benutzerdefinierten XML-Komponenten finden Sie in der Übersicht über benutzerdefinierte XML-Komponenten.

Verwenden Sie die XMLMapping-Eigenschaft des Steuerelements, um ein Inhaltssteuerelement an ein Element in einer benutzerdefinierten XML-Komponente zu binden. Im folgenden Codebeispiel wird veranschaulicht, wie ein PlainTextContentControl an das Element Price unter dem Knoten Product in einem benutzerdefinierten XML-Abschnitt gebunden wird, der dem Dokument bereits hinzugefügt wurde.

plainTextContentControl1.XMLMapping.SetMapping("/Product/Price", String.Empty, null);

Eine exemplarische Vorgehensweise, die veranschaulicht, wie Inhaltssteuerelemente an benutzerdefinierte XML-Komponenten ausführlicher gebunden werden, finden Sie unter Walkthrough: Bind content controls to custom XML parts.

Wenn Sie ein Inhaltssteuerelement an einen benutzerdefinierten XML-Abschnitt binden, wird die bidirektionale Datenbindung automatisch aktiviert. Wenn ein Benutzer Text im Steuerelement bearbeitet, werden die entsprechenden XML-Elemente automatisch aktualisiert. Wenn Elementwerte in den benutzerdefinierten XML-Abschnitten geändert werden, zeigen die Inhaltssteuerelemente, die an die XML-Elemente gebunden sind, auf ähnliche Weise die neuen Daten an.

Sie können die folgenden Typen von Inhaltssteuerelementen an benutzerdefinierte XML-Abschnitte binden:

Datenbindungsereignisse für Inhaltssteuerelemente

Alle Inhaltssteuerelemente stellen einen Satz von Ereignissen bereit, die Sie behandeln können, um datenbezogene Aufgaben auszuführen. Sie können z. B. überprüfen, ob der Text in einem Steuerelement bestimmte Kriterien erfüllt, bevor die Datenquelle aktualisiert wird. Die folgende Tabelle listet die Inhaltssteuerelement-Ereignisse auf, die mit der Datenbindung zusammenhängen.

Aufgabe Ereignis
Ausführen von Code , kurz bevor Word automatisch den Text in einem Inhaltssteuerelement aktualisiert, das an einen benutzerdefinierten XML-Abschnitt gebunden ist. ContentUpdating
Ausführen von Code, kurz bevor Word automatisch die Daten in einem benutzerdefinierten XML-Abschnitt aktualisiert, der an ein Inhaltssteuerelement gebunden ist (d. h. nachdem sich der Text im Inhaltssteuerelement ändert). StoreUpdating
Ausführen Ihres eigenen Codes, um den Inhalt des Steuerelements gemäß benutzerdefinierten Kriterien zu überprüfen. Validating
Ausführen von Code, nachdem der Inhalt des Steuerelements erfolgreich überprüft wurde. Validated

Einschränkungen von Inhaltssteuerelementen

Wenn Sie Inhaltssteuerelemente in Office-Projekten verwenden, beachten Sie auf die folgenden Einschränkungen.

Verhaltensunterschiede zwischen Entwurfszeit und Laufzeit

Viele der Einschränkungen, die Microsoft Office Word-Inhaltssteuerelementen zur Laufzeit auferlegt, werden zur Entwurfszeit nicht erzwungen. Achten Sie beim Entwerfen der Benutzeroberfläche einer Projektmappe auf Dokumentebene in Visual Studio darauf, Inhaltssteuerelemente nur auf Die Arten zu ändern, die zur Laufzeit unterstützt werden.

Wenn Sie ein Inhaltssteuerelement zur Entwurfszeit so ändern, dass das Steuerelement zur Laufzeit nicht unterstützt wird, benachrichtigt der Visual Studio-Designer Sie nicht über die nicht unterstützten Änderungen. Allerdings wird beim Debuggen oder Ausführen des Projekts oder beim Speichern und erneuten Öffnen des Projekts von Word eine Fehlermeldung angezeigt und die Berechtigung zum Reparieren des Dokuments angefordert. Wenn Sie das Dokument reparieren, entfernt Word alle nicht unterstützten Inhalte und Formatierungen aus dem Steuerelement.

Word verhindert z. B. nicht, dass Sie einem PlainTextContentControl zur Entwurfszeit eine Tabelle hinzufügen. Da PlainTextContentControl-Objekte jedoch zur Laufzeit keine Tabellen enthalten dürfen, zeigt Word eine Fehlermeldung an, wenn das Dokument geöffnet wird.

Beachten Sie außerdem, dass viele Eigenschaften, die das Verhalten von Inhaltssteuerelementen definieren, zur Entwurfszeit keine Auswirkungen besitzen. Wenn Sie beispielsweise die LockContents-Eigenschaft eines Inhaltssteuerelements zur Entwurfszeit auf "True " festlegen, können Sie text im Visual Studio-Designer weiterhin bearbeiten. Diese Eigenschaft verhindert nur, dass Benutzer das Steuerelement zur Laufzeit bearbeiten können.

Ereignisbeschränkungen

Inhaltssteuerelemente stellen kein Ereignis zur Verfügung, das ausgelöst wird, wenn der Benutzer Text oder andere Elemente im Steuerelement ändert. Es ist z. B. kein Ereignis vorhanden, das ausgelöst wird, wenn ein Benutzer ein anderes Element in einem DropDownListContentControl oder ComboBoxContentControl auswählt.

Wenn Sie ermitteln möchten, wenn ein Benutzer den Inhalt eines Inhaltssteuerelements bearbeitet, können Sie das Steuerelement an einen benutzerdefinierten XML-Abschnitt binden und dann das Ereignis StoreUpdating behandeln. Dieses Ereignis wird ausgelöst, wenn der Benutzer den Inhalt eines Steuerelements ändert, das an einen benutzerdefinierten XML-Abschnitt gebunden ist. Eine exemplarische Vorgehensweise, die veranschaulicht, wie ein Inhaltssteuerelement an eine benutzerdefinierte XML-Komponente gebunden wird, finden Sie unter Walkthrough: Bind content controls to custom XML parts.

Kontrollkästchen-Inhaltssteuerelemente in Word-Projekten

Mit Word 2010 wurde eine neue Art von Steuerelement eingeführt, das ein Kontrollkästchen darstellt. Die Visual Studio-Tools für Die Office-Laufzeit stellt jedoch keinen entsprechenden CheckBoxContentControl-Typ bereit, den Sie in Office-Projekten verwenden können. Verwenden Sie zum Erstellen eines Kontrollkästchen-Inhaltssteuerelements in einem Word 2013- oder Word 2010-Projekt die AddContentControl Methode zum Erstellen eines ContentControl Objekts, und übergeben Sie den wdContentControlCheckBox Wert an die Methode, um ein Kontrollkästchen-Inhaltssteuerelement anzugeben. Das folgende Codebeispiel veranschaulicht, wie Sie dabei vorgehen:

this.Paragraphs[1].Range.InsertParagraphBefore();
this.Paragraphs[1].Range.Select();
Microsoft.Office.Tools.Word.ContentControl checkBoxControl1 = 
    this.Controls.AddContentControl("checkBoxControl1", Word.WdContentControlType.wdContentControlCheckBox);

checkBoxControl1.Checked = true;

Zugehöriger Inhalt