Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit

  • Artikel

Sie können Steuerelemente einem Microsoft Office Word-Dokument und einer Microsoft Office Excel-Arbeitsmappe zur Laufzeit hinzufügen.Sie können sie auch zur Laufzeit entfernen.Steuerelemente, die Sie zur Laufzeit hinzufügen oder entfernen, werden dynamische Steuerelemente aufgerufen.

Betrifft: Die Informationen in diesem Thema betreffen Projekte auf Dokument- und auf Anwendungsebene für die folgenden Anwendungen: Excel 2013 und Excel 2010, Word 2013 und Word 2010. Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

In diesem Thema wird Folgendes beschrieben:

  • Das Verwalten von Steuerelementen zur Laufzeit mit den Steuerelementauflistungen, verwendet.

  • Hinzufügen von Hoststeuerelementen zu Dokumenten.

  • Hinzufügen von Windows Forms-Steuerelementen zu Dokumenten.

Link zu Video Eine entsprechende Videodemo finden Sie unter How Do I: Add Controls to a Document Surface at Runtime?.

Verwalten von Steuerelementen zur Laufzeit mit den Steuerelementauflistungen

Um Steuerelemente zur Laufzeit hinzuzufügen, abzurufen oder zu entfernen, verwenden Sie Hilfsmethoden des Microsoft.Office.Tools.Excel.ControlCollection-Objekts und des Microsoft.Office.Tools.Word.ControlCollection-Objekts.

Auf welche Weise Sie auf diese Objekte zugreifen, hängt vom Typ des Projekts ab, das Sie entwickeln:

x97a5x3s.collapse_all(de-de,VS.110).gifHinzufügen von Steuerelementen

Die Microsoft.Office.Tools.Excel.ControlCollection und Microsoft.Office.Tools.Word.ControlCollection-Typen umfassen Hilfsmethoden, die Sie verwenden können, um allgemeine Hoststeuerelemente und Windows Forms-Steuerelemente Dokumenten und Arbeitsblättern hinzuzufügen.Jeder Methodenname besitzt das Format AddSteuerelementklasse, wo Steuerelementklasse der Klassenname des Steuerelements ist, das Sie hinzufügen möchten.Wenn Sie dem Dokument zum Beispiel ein NamedRange-Steuerelement hinzufügen möchten, verwenden Sie dazu die AddNamedRange-Methode.

Im folgenden Codebeispiel wird in einem Projekt auf Dokumentebene für Excel Sheet1 ein NamedRange hinzugefügt.

Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

x97a5x3s.collapse_all(de-de,VS.110).gifZugreifen auf Steuerelemente und Löschen von Steuerelementen

Sie können die Controls-Eigenschaft von Microsoft.Office.Tools.Excel.Worksheet oder Microsoft.Office.Tools.Word.Document verwenden, um alle Steuerelemente in Ihrem Dokument zu durchlaufen, einschließlich der Steuerelemente, die Sie zur Entwurfszeit hinzugefügt haben.Steuerelemente, die Sie zur Entwurfszeit hinzufügen, werden auch als statische Steuerelemente bezeichnet.

Sie können dynamische Steuerelemente entfernen, indem Sie die Delete-Methode des Steuerelements oder die Remove-Methode der jeweiligen Controls-Auflistung aufrufen.Im folgenden Codebeispiel wird die Remove-Methode verwendet, um einen NamedRange aus Sheet1 in einem Projekt auf Dokumentebene für Excel zu entfernen.

Globals.Sheet1.Controls.Remove("ChartSource")

Globals.Sheet1.Controls.Remove("ChartSource");

Zur Laufzeit können Sie keine statischen Steuerelemente entfernen.Wenn Sie versuchen, mit der Delete-Methode oder der Remove-Methode ein statisches Steuerelement zu entfernen, wird eine CannotRemoveControlException ausgelöst.

HinweisHinweis

Entfernen Sie keine Steuerelemente programmgesteuert im Shutdown-Ereignishandler des Dokuments.Die Benutzeroberflächenelemente des Dokuments sind nicht mehr verfügbar, wenn das Shutdown-Ereignis ausgelöst wird.Wenn Sie vor dem Schließen des Dokuments Steuerelemente entfernen möchten, fügen Sie dem Code einen Ereignishandler für ein anderes Element hinzu, beispielsweise Document.BeforeClose bzw. Document.BeforeSave für Word oder Workbook.BeforeClose bzw. Workbook.BeforeSave für Excel.

Hinzufügen von Hoststeuerelementen zu Dokumenten

Wenn Sie Dokumenten programmgesteuert Steuerelemente hinzufügen, müssen Sie einen Namen zur eindeutigen Identifikation des Steuerelements angeben, und Sie müssen angeben, wo das Steuerelement dem Dokument hinzugefügt werden soll.Genaue Anweisungen finden Sie in den folgenden Themen:

Weitere Informationen zu Hoststeuerelementen finden Sie unter Übersicht über Hostelemente und Hoststeuerelemente.

Beim Speichern und Schließen eines Dokuments werden alle dynamisch erstellten Hoststeuerelemente von ihren Ereignissen getrennt und verlieren ihre Datenbindungsfunktion.Sie können der Projektmappe Code hinzufügen, damit die Hoststeuerelemente beim erneuten Öffnen des Dokuments neu erstellt werden.Weitere Informationen finden Sie unter Beibehalten von dynamischen Steuerelementen in Office-Dokumenten.

HinweisHinweis

Für die folgenden Hoststeuerelemente werden keine Hilfsmethoden bereitgestellt, da sie Dokumenten nicht programmgesteuert hinzugefügt werden können: XmlMappedRange, XMLNode und XMLNodes.

Hinzufügen von Windows Forms-Steuerelementen zu Dokumenten

Wenn Sie einem Dokument programmgesteuert ein Windows Forms-Steuerelement hinzufügen, müssen Sie die Position des Steuerelements und einen Namen zur eindeutigen Identifikation des Steuerelements angeben.Visual Studio-Tools für Office-Laufzeit stellt Hilfsmethoden für jedes Steuerelement bereit.Diese Methoden werden überladen, sodass Sie einen Bereich oder bestimmte Koordinaten für die Position des Steuerelements übergeben können.

Beim Speichern und Schließen eines Dokuments werden die dynamisch erstellten Windows Forms-Steuerelemente aus dem Dokument entfernt.Sie können der Projektmappe Code hinzufügen, damit die Steuerelemente beim erneuten Öffnen des Dokuments neu erstellt werden.Wenn Sie dynamische Windows Forms-Steuerelemente mit einem Add-In auf Anwendungsebene erstellen, bleiben die ActiveX-Wrapper für die Steuerelemente im Dokument zurück.Weitere Informationen finden Sie unter Beibehalten von dynamischen Steuerelementen in Office-Dokumenten.

HinweisHinweis

Das programmgesteuerte Hinzufügen von Windows Forms-Steuerelementen zu geschützten Dokumenten ist nicht möglich.Wenn Sie den Schutz eines Word-Dokuments oder einer Excel-Arbeitsmappe programmgesteuert aufheben, um ein Steuerelement hinzuzufügen, müssen Sie zusätzlichen Code zum Entfernen des ActiveX-Wrappers des Steuerelements beim Schließen des Dokuments schreiben.Der ActiveX-Wrapper des Steuerelements wird nicht automatisch aus geschützten Dokumenten gelöscht.

x97a5x3s.collapse_all(de-de,VS.110).gifHinzufügen benutzerdefinierter Steuerelemente

Wenn Sie System.Windows.Forms.Control hinzufügen möchten, das von den verfügbaren Hilfsmethoden nicht, wie ein benutzerdefiniertes Benutzersteuerelement unterstützt wird, verwenden Sie die folgenden Methoden:

Um das Steuerelement hinzuzufügen, übergeben Sie das System.Windows.Forms.Control, eine Position für das Steuerelement und einen Namen, durch den das Steuerelement gegenüber der AddControl-Methode eindeutig identifiziert wird.Die AddControl-Methode gibt ein Objekt zurück, das definiert, wie das Steuerelement mit dem Arbeitsblatt oder dem Dokument interagiert.Die - Methode gibt AddControlMicrosoft.Office.Tools.Excel.ControlSite (für Excel) oder ein - Objekt zurück Microsoft.Office.Tools.Word.ControlSite (für Word).

Im folgenden Codebeispiel wird veranschaulicht, wie die AddControl(Control, Range, String)-Methode verwendet, um ein benutzerdefiniertes Benutzersteuerelement einem Arbeitsblatt in einem Excel-Projekt dynamisch auf Dokumentebene hinzuzufügen.In diesem Beispiel wird das Benutzersteuerelement UserControl1 genannt, und Range wird range1 benannt. Wenn Sie dieses Beispiel verwenden möchten, führen Sie es von einer Klasse Sheetn im Projekt.

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.ControlSite = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

x97a5x3s.collapse_all(de-de,VS.110).gifVerwenden von Membern benutzerdefinierter Steuerelemente

Nachdem Sie einem Arbeitsblatt oder Dokument mit einer der AddControl-Methoden ein Steuerelement hinzugefügt haben, verfügen Sie über zwei verschiedene Steuerelementobjekte:

  • Das System.Windows.Forms.Control, das das benutzerdefinierte Steuerelement darstellt.

  • Das Objekt ControlSite, OLEObject oder OLEControl, das das Steuerelement darstellt, nachdem es dem Arbeitsblatt oder dem Dokument hinzugefügt wurde.

Viele Eigenschaften und Methoden werden von diesen Steuerelementen gemeinsam verwendet.Es ist wichtig, dass Sie auf diese Member über das entsprechende Steuerelement zugreifen:

  • Um auf Member zuzugreifen, die nur zu dem benutzerdefinierten Steuerelement gehören, verwenden Sie das System.Windows.Forms.Control.

  • Um auf Member zuzugreifen, die von den Steuerelementen gemeinsam genutzt werden, verwenden Sie das Objekt ControlSite, OLEObject oder OLEControl.

Wenn Sie über ein System.Windows.Forms.Control auf einen freigegebenen Member zugreifen, kann dieser Versuch fehlschlagen, ohne dass Sie diesbezüglich eine Warnung oder Benachrichtigung erhalten, oder er kann zu ungültigen Ergebnissen führen.Verwenden Sie immer Methoden oder Eigenschaften des Objekts ControlSite, OLEObject oder OLEControl. Nur wenn die benötigte Methode oder Eigenschaft nicht verfügbar ist, sollten Sie auf das System.Windows.Forms.Control verweisen.

Beispielsweise verfügen sowohl die ControlSite-Klasse als auch die System.Windows.Forms.Control-Klasse über eine Top-Eigenschaft.Um den Abstand zwischen dem oberen Rand des Steuerelements und dem oberen Rand des Dokuments abzurufen oder festzulegen, verwenden Sie die Top-Eigenschaft des ControlSite und nicht die Top-Eigenschaft des System.Windows.Forms.Control.

' Property is set in relation to the document.
dynamicControl.Top = 100

' Property is set in relation to the container control.
customControl.Top = 100

// Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Siehe auch

Aufgaben

Gewusst wie: Hinzufügen von ListObject-Steuerelementen zu Arbeitsblättern

Gewusst wie: Hinzufügen von NamedRange-Steuerelementen zu Arbeitsblättern

Gewusst wie: Hinzufügen von Diagrammsteuerelementen zu Arbeitsblättern

Gewusst wie: Hinzufügen von Inhaltssteuerelementen zu Word-Dokumenten

Gewusst wie: Hinzufügen von Bookmark-Steuerelementen zu Word-Dokumenten

Gewusst wie: Hinzufügen von Windows Forms-Steuerelementen zu Office-Dokumenten

Konzepte

Beibehalten von dynamischen Steuerelementen in Office-Dokumenten

Übersicht über Windows Forms-Steuerelemente in Office-Dokumenten

Weitere Ressourcen

Steuerelemente für Office-Dokumente