Freigeben über

Hinzufügen von Steuerelementen zu Office-Dokumenten während der Laufzeit

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

Gilt für: Die Informationen in diesem Thema gelten für Projekte auf Dokumentebene und VSTO-Add-In-Projekte für Excel und Word. Weitere Informationen finden Sie unter Funktionen verfügbar nach Office-Anwendung und Projekttyp.

In diesem Thema wird Folgendes beschrieben:

Verwalten von Steuerelementen zur Laufzeit mithilfe von Steuerelementsammlungen

Verwenden Sie die Hilfsmethoden der Objekte ControlCollection und ControlCollection, um Steuerelemente zur Laufzeit hinzuzufügen, abzurufen oder zu entfernen.

Die Art und Weise, wie Sie auf diese Objekte zugreifen, hängt vom Typ des Projekts ab, das Sie entwickeln:

Hinzufügen von Steuerelementen

Die Typen ControlCollection und ControlCollection umfassen Hilfsmethoden, mit denen Sie Hoststeuerelemente und allgemeine Windows Forms-Steuerelemente zu Dokumenten und Arbeitsblättern hinzufügen können. Jeder Methodenname weist die Add auf, wobei die Steuerelementklasse der Klassenname des Steuerelements ist, das Sie hinzufügen möchten. Wenn Sie ihrem Dokument beispielsweise ein NamedRange Steuerelement hinzufügen möchten, verwenden Sie die AddNamedRange Methode.

Im folgenden Codebeispiel wird ein NamedRange zu einem Sheet1 in einem Dokumentprojekt für Excel hinzugefügt.

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

Zugriffs- und Löschsteuerelemente

Sie können die Controls-Eigenschaft einer Worksheet oder 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 aufrufen oder die Remove Methode jeder Controls-Auflistung aufrufen. Im folgenden Codebeispiel wird die Remove Methode verwendet, um eine NamedRange aus Sheet1 einem Projekt auf Dokumentebene für Excel zu entfernen.

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

Statische Steuerelemente können zur Laufzeit nicht entfernt werden. Wenn Sie versuchen, die Delete- oder Remove-Methode zu verwenden, um ein statisches Steuerelement zu entfernen, wird ein CannotRemoveControlException ausgelöst.

Hinweis

Steuerelemente im Shutdown Ereignishandler des Dokuments nicht programmgesteuert entfernen. Die UI-Elemente des Dokuments sind nicht mehr verfügbar, wenn das Shutdown Ereignis ausgelöst wird. Wenn Sie Steuerelemente entfernen möchten, bevor das Dokument geschlossen wird, fügen Sie Ihren Code dem Ereignishandler für ein anderes Ereignis hinzu, z. B. BeforeClose oder BeforeSave für Word, oder BeforeClose oder BeforeSave für Excel.

Hinzufügen von Hoststeuerelementen zu Dokumenten

Wenn Sie Hoststeuerelemente programmgesteuert zu Dokumenten hinzufügen, müssen Sie einen Namen angeben, der das Steuerelement eindeutig identifiziert, und Sie müssen angeben, wo das Steuerelement dem Dokument hinzugefügt werden soll. Spezifische Anweisungen finden Sie in den folgenden Themen:

Weitere Informationen zu Hoststeuerungselementen finden Sie unter Übersicht zu Host- und Steuerungselementen.

Wenn ein Dokument gespeichert und dann geschlossen wird, werden alle dynamisch erstellten Hoststeuerelemente von ihren Ereignissen getrennt und verlieren ihre Datenbindungsfunktionen. Sie können Ihrer Lösung Code hinzufügen, um die Hoststeuerelemente erneut zu erstellen, wenn das Dokument erneut geöffnet wird. Weitere Informationen finden Sie unter Beibehalten dynamischer Steuerelemente in Office-Dokumenten.

Hinweis

Hilfsmethoden werden für die folgenden Hoststeuerelemente nicht bereitgestellt, da diese Steuerelemente nicht programmgesteuert zu Dokumenten hinzugefügt werden können: XmlMappedRange, , XMLNodeund XMLNodes.

Hinzufügen von Windows Forms-Steuerelementen zu Dokumenten

Wenn Sie einem Dokument programmgesteuert ein Windows Forms-Steuerelement hinzufügen, müssen Sie den Speicherort des Steuerelements und einen Namen angeben, der das Steuerelement eindeutig identifiziert. Die Visual Studio Tools für Office-Laufzeit stellt Hilfsmethoden für jedes Steuerelement bereit. Diese Methoden sind überladen, sodass Sie entweder einen Bereich oder bestimmte Koordinaten für die Position des Steuerelements übergeben können.

Wenn ein Dokument gespeichert und dann geschlossen wird, werden alle dynamisch erstellten Windows Forms-Steuerelemente aus dem Dokument entfernt. Sie können Ihrer Lösung Code hinzufügen, um die Steuerelemente erneut zu erstellen, wenn das Dokument erneut geöffnet wird. Wenn Sie dynamische Windows Forms-Steuerelemente mithilfe eines VSTO-Add-Ins erstellen, bleiben die ActiveX-Wrapper für die Steuerelemente im Dokument erhalten. Weitere Informationen finden Sie unter Beibehalten dynamischer Steuerelemente in Office-Dokumenten.

Hinweis

Windows Forms-Steuerelemente können nicht programmgesteuert zu geschützten Dokumenten hinzugefügt werden. Wenn Sie den Schutz eines Word-Dokuments oder eines Excel-Arbeitsblatts programmgesteuert aufheben, um ein Steuerelement hinzuzufügen, müssen Sie zusätzlichen Code schreiben, um den ActiveX-Wrapper des Steuerelements zu entfernen, wenn das Dokument geschlossen wird. Der ActiveX-Wrapper des Steuerelements wird nicht automatisch aus geschützten Dokumenten gelöscht.

Hinzufügen von benutzerdefinierten Steuerelementen

Wenn Sie ein Control Steuerelement hinzufügen möchten, das von den verfügbaren Hilfsmethoden, z. B. einem benutzerdefinierten Benutzersteuerelement, nicht unterstützt wird, verwenden Sie die folgenden Methoden:

  • Verwenden Sie für Excel eine der AddControl Methoden eines ControlCollection Objekts.

  • Verwenden Sie für Word eine der AddControl Methoden eines ControlCollection Objekts.

    Um das Steuerelement hinzuzufügen, übergeben Sie den Control, eine Position für das Steuerelement und einen Namen, der das Steuerelement eindeutig an die AddControl Methode identifiziert. Die AddControl Methode gibt ein Objekt zurück, das definiert, wie das Steuerelement mit dem Arbeitsblatt oder Dokument interagiert. Die AddControl Methode gibt ein ControlSite (für Excel) oder ein ControlSite Objekt (für Word) zurück.

    Im folgenden Codebeispiel wird veranschaulicht, wie Die AddControl Methode verwendet wird, um einem Arbeitsblatt in einem Excel-Projekt auf Dokumentebene dynamisch ein benutzerdefiniertes Benutzersteuerelement hinzuzufügen. In diesem Beispiel wird das Benutzersteuerelement UserControl1 genannt, und das Range wird range1 genannt. Um dieses Beispiel zu verwenden, führen Sie es aus einer Sheetn-Klasse im Projekt aus.

    UserControl1 customControl = new UserControl1();

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

Verwenden von Mitgliedern von benutzerdefinierten Steuerelementen

Nachdem Sie eine der AddControl Methoden zum Hinzufügen eines Steuerelements zu einem Arbeitsblatt oder Dokument verwendet haben, verfügen Sie jetzt über zwei verschiedene Steuerelementobjekte:

  • Das Control stellt das benutzerdefinierte Steuerelement dar.

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

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

  • Um nur auf Mitglieder zuzugreifen, die nur zum benutzerdefinierten Steuerelement gehören, verwenden Sie die Control.

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

    Wenn Sie auf ein freigegebenes Mitglied über das ControlElement zugreifen, schlägt es möglicherweise ohne Warnung oder Benachrichtigung fehl, oder es kann zu ungültigen Ergebnissen führen. Verwenden Sie immer Methoden oder Eigenschaften des ControlSite, OLEObject, oder OLEControl-Objekts. Es sei denn, die erforderliche Methode oder Eigenschaft ist nicht verfügbar. Nur dann sollten Sie auf das Control-Objekt zugreifen.

    Beispielsweise verfügen sowohl die ControlSite Klasse als auch die 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 der ControlSite, nicht die Top Eigenschaft der .Control

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

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

Verwandte Inhalte

  • Last updated on