Freigeben über

Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit

  • Artikel

Sie können zur Laufzeit Steuerelemente zu Microsoft Office Word-Dokumenten und Microsoft Office Excel-Arbeitsmappen hinzufügen und auch entfernen. Steuerelemente, die Sie Dokumenten zur Laufzeit hinzufügen, werden als dynamische Steuerelemente bezeichnet.

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

Dieses Thema enthält folgende Informationen:

  • Verwalten von Steuerelementen zur Laufzeit mit den Steuerelementauflistungen

  • 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:

Hinzufügen von Steuerelementen

Der Microsoft.Office.Tools.Excel.ControlCollection-Typ und der Microsoft.Office.Tools.Word.ControlCollection-Typ umfassen Hilfsmethoden, die Sie verwenden können, um Dokumenten und Arbeitsmappen Hoststeuerelemente und die gängigsten Windows Forms-Steuerelemente hinzuzufügen. Jeder Methodenname besitzt das Format Add<control class>, wobei control class 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. Eine vollständige Liste von Hilfsmethoden finden Sie unter Hilfsmethoden für Hoststeuerelemente und unter Hilfsmethoden für Windows Forms-Steuerelemente.

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");

Zugreifen 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.

Tipp

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.

Tipp

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 for Office-Laufzeit stellt Hilfsmethoden für jedes Steuerelement bereit. Diese Methoden sind überladen, sodass Sie einen Bereich oder bestimmte Koordinaten für die Position des Steuerelements übergeben können. Ausführliche Anweisungen finden Sie unter Gewusst wie: Hinzufügen von Windows Forms-Steuerelementen zu Office-Dokumenten.

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.

Tipp

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.

Hinzufügen benutzerdefinierter Steuerelemente

Wenn Sie ein System.Windows.Forms.Control hinzufügen möchten, das von den verfügbaren Hilfsmethoden nicht unterstützt wird (z. B. ein benutzerdefiniertes Steuerelement), 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. Der Typ des zurückgegebenen Objekts hängt vom Projekt ab:

  • Für Projekte, die auf .NET Framework 4 abzielen, gibt diese Methode ein Microsoft.Office.Tools.Excel.ControlSite-Objekt (für Excel) oder ein Microsoft.Office.Tools.Word.ControlSite-Objekt (für Word) zurück.

  • Für Projekte, die auf .NET Framework 3.5 abzielen, gibt diese Methode ein Microsoft.Office.Tools.Excel.OLEObject-Objekt (für Excel) oder ein Microsoft.Office.Tools.Word.OLEControl-Objekt (für Word) zurück.

Im folgenden Codebeispiel wird dargestellt, wie die AddControl(Control, Range, String)-Methode verwendet wird, um einem Arbeitsblatt in einem Excel-Projekt auf Dokumentebene, das auf .NET Framework 4 abzielt, ein benutzerdefiniertes Benutzersteuerelement dynamisch hinzuzufügen. In diesem Beispiel lautet der Name des Benutzersteuerelements UserControl1, und der Name des Range lautet range1. Wenn Sie dieses Beispiel verwenden möchten, führen Sie es in einer Sheetn-Klasse im Projekt aus.

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");

Verwenden 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

Hilfsmethoden für Hoststeuerelemente

Hilfsmethoden für Windows Forms-Steuerelemente

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

Weitere Ressourcen

Steuerelemente für Office-Dokumente