Freigeben über

Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit

  • Artikel

Aktualisiert: Juli 2008

Betrifft

Die Informationen in diesem Thema gelten nur für die angegebenen Projekte und Versionen von Visual Studio Tools for Office von Microsoft Office.

Projekte auf Dokumentebene

  • Excel 2003

  • Excel 2007

  • Word 2003

  • Word 2007

Projekte auf Anwendungsebene

  • Excel 2007

  • Word 2007

Weitere Informationen hierzu finden Sie unter Verfügbare Features nach Anwendung und Projekttyp.

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. Ab Visual Studio 2008 Service Pack 1 (SP1) können Sie Dokumenten und Arbeitsmappen dynamische Steuerelemente mit den Add-Ins auf Anwendungsebene hinzufügen.

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

Verwalten von Steuerelementen zur Laufzeit mit den Steuerelementauflistungen

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

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

Hinzufügen von Steuerelementen

Die Microsoft.Office.Tools.Excel.ControlCollection-Klasse und die Microsoft.Office.Tools.Word.ControlCollection-Klasse 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.

Hinweis:

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 hierzu finden Sie unter Beibehalten von dynamischen Steuerelementen in Office-Dokumenten.

Hinweis:

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 stellt Hilfsmethoden für jedes Steuerelement bereit. Diese Hilfsmethoden sind überladen, d. h., Sie können entweder einen Bereich oder die genauen Koordinaten für die Position des Steuerelements übergeben. 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 hierzu finden Sie unter Beibehalten von dynamischen Steuerelementen in Office-Dokumenten.

Hinweis:

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. Für Excel gibt diese Methode ein OLEObject zurück. Für Word gibt diese Methode ein OLEControl zurück. Diese Objekte definieren, wie das Steuerelement mit dem Arbeitsblatt oder dem Dokument interagiert.

Im folgenden Codebeispiel wird veranschaulicht, wie Sie die AddControl(Control, Range, String)-Methode verwenden, um einem Arbeitsblatt ein benutzerdefiniertes Steuerelement dynamisch hinzuzufügen. In diesem Beispiel hat das Benutzersteuerelement den Namen UserControl1 und Range den Namen range1. Bei diesem Beispiel wird davon ausgegangen, dass es von einer der Sheetn-Klassen in einem Projekt auf Dokumentebene für Excel ausgeführt wird.

Dim customControl As New UserControl1()

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

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.OLEObject 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:

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

  • Um auf Eigenschaften und Methoden zuzugreifen, die nur zu dem Benutzersteuerelement gehören, verwenden Sie das System.Windows.Forms.Control.

  • Um auf Eigenschaften und Methoden zuzugreifen, die von den Steuerelementen gemeinsam genutzt werden, verwenden Sie das OLEObject oder das OLEControl.

Wenn Sie über ein System.Windows.Forms.Control auf eine gemeinsam verwendete Methode oder Eigenschaft 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 OLEObject oder des 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 OLEObject-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 OLEObject 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

Referenz

ControlCollection.AddControl

ControlCollection.AddControl

ControlCollection.Remove

ControlCollection.Remove

Weitere Ressourcen

Steuerelemente für Office-Dokumente

Excel-Hoststeuerelemente

Word-Hoststeuerelemente

Änderungsprotokoll

Datum

Versionsgeschichte

Grund

Juli 2008

Informationen über das Hinzufügen von Steuerelementen zu Dokumenten mit Add-Ins auf Anwendungsebene hinzugefügt.

SP1-Featureänderung.