Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit

  • Artikel

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

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 features available by Office-App lication and project type.

In diesem Thema wird Folgendes beschrieben:

Verwalten von Steuerelementen zur Laufzeit mithilfe von Steuerelementsammlungen

Verwenden Sie zum Hinzufügen, Abrufen oder Entfernen von Steuerelementen zur Laufzeit Hilfsmethoden der Objekte ControlCollection und ControlCollection .

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 enthalten Hilfsmethoden, mit denen Sie Dokumenten und Arbeitsblättern Hoststeuerelemente und allgemeine Windows Forms-Steuerelemente hinzufügen können. Jeder Methodenname weist folgendes Format auf AddSteuerelementklasse. Dabei ist Steuerelementklasse der Klassenname des Steuerelements, das Sie hinzufügen möchten. Verwenden Sie beispielsweise zum Hinzufügen eines NamedRange Steuerelements zu Ihrem Dokument die AddNamedRange -Methode.

Im folgenden Codebeispiel wird in einem Projekt auf Dokumentebene für Excel ein NamedRange zu Sheet1 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 Sie Controls-Eigenschaft eines Worksheet oder Document verwenden, um alle Steuerelemente in Ihrem Dokument zu durchlaufen, auch die zur Entwurfszeit hinzugefügten. Steuerelemente, die zur Entwurfszeit hinzufügt werden, werden auch als statische Steuerelementebezeichnet.

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 in einem Projekt auf Dokumentebene für Excel ein NamedRange aus Sheet1 zu entfernen.

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

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

Hinweis

Vermeiden Sie es, Steuerelemente im Shutdown -Ereignishandlerzeitraum des Dokuments programmgesteuert zu entfernen. Die Benutzeroberflächenelemente des Dokuments sind nicht mehr verfügbar, wenn das Shutdown -Ereignis ausgelöst wird. Wenn Sie Steuerelemente vor dem Schließen des Dokuments entfernen möchten, fügen Sie den Code dem Ereignishandler für ein anderes Ereignis hinzu, z. B. BeforeClose oder BeforeSave für Word oder BeforeCloseoder BeforeSave für Excel.

Hinzufügen von Hoststeuerelementen zu Dokumenten

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

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

Wenn ein Dokument gespeichert und anschließend geschlossen wird, werden alle dynamisch erstellten Hoststeuerelemente von ihren Ereignissen getrennt und verlieren ihre Datenbindungsfunktion. Sie können der Projektmappe Code hinzufügen, damit die Hoststeuerelemente neu erstellt werden, wenn das Dokument erneut geöffnet wird. Weitere Informationen finden Sie unter Beibehalten dynamischer Steuerelemente in Office-Dokumenten.

Hinweis

Für folgende Hoststeuerelemente werden keine Hilfsmethoden bereitgestellt, da diese Steuerelemente nicht programmgesteuert 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 die Position des Steuerelements und einen Namen angeben, der das Steuerelement eindeutig identifiziert. Die Visual Studio-Tools für Die Office-Laufzeit stellt Hilfsmethoden für jedes Steuerelement bereit. Diese Methoden werden überladen, sodass Sie entweder einen Bereich oder bestimmte Koordinaten für die Position des Steuerelements übergeben können.

Wenn ein Dokument gespeichert und anschließend geschlossen wird, werden alle dynamisch erstellten Windows Forms-Steuerelemente aus dem Dokument entfernt. Sie können der Projektmappe Code hinzufügen, damit die Steuerelemente neu erstellt werden, 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 geschützten Dokumenten nicht programmgesteuert hinzugefügt werden. Wenn Sie den Schutz eines Word-Dokuments oder Excel-Arbeitsblatts 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.

Benutzerdefinierte Steuerelemente hinzufügen

Wenn Sie ein Control hinzufügen möchten, das von den verfügbaren Hilfsmethoden nicht unterstützt wird, z. B. ein benutzerdefiniertes Benutzersteuerelement, verwenden Sie folgende 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.

    Übergeben Sie zum Hinzufügen des Steuerelements das Control, eine Position für das Steuerelement und einen Namen, der das Steuerelement eindeutig identifiziert, an die AddControl-Methode. Die AddControl-Methode gibt ein Objekt zurück, das definiert, wie das Steuerelement mit dem Arbeitsblatt oder dem 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 Sie die AddControl -Methode verwenden, um ein benutzerdefiniertes Steuerelement dynamisch zu einem Arbeitsblatt in einem Excel-Projekt auf Dokumentebene hinzuzufügen. In diesem Beispiel heißt das Benutzersteuerelement UserControl1, und der Range heißt range1. Wenn Sie dieses Beispiel verwenden möchten, führen Sie es von 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 mit einer der AddControl-Methoden einem Arbeitsblatt oder Dokument ein Steuerelement hinzugefügt haben, verfügen Sie nun über zwei verschiedene Steuerelementobjekte:

  • das Control -Objekt, das das benutzerdefinierte Steuerelement darstellt, und

  • das ControlSite-, das OLEObject oder das OLEControl-Objekt, das das Steuerelement nach dem Hinzufügen zum Arbeitsblatt oder Dokument darstellt.

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

  • Verwenden Sie zum Zugreifen auf Member, die nur zum benutzerdefinierten Steuerelement gehören, Control.

  • Verwenden Sie zum Zugreifen auf Member, die von den Steuerelementen gemeinsam genutzt werden, das ControlSite-, das OLEObject oder das OLEControl-Objekt.

    Wenn Sie auf einen gemeinsam genutzten Member über das Controlzugreifen, schlägt dieser möglicherweise ohne Warnung oder Benachrichtigung fehl, oder es werden ungültige Ergebnisse erzeugt. Verwenden Sie stets Methoden oder Eigenschaften des ControlSite-, des OLEObject- oder des OLEControl-Objekts, es sei denn, die benötigte Methode oder Eigenschaft ist nicht verfügbar; nur in diesem Fall sollten Sie auf Control verweisen.

    Sowohl die ControlSite-Klasse als auch die Control-Klasse weisen eine Top-Eigenschaft auf. Verwenden Sie zum Abrufen oder Festlegen des Abstands zwischen dem oberen Rand des Steuerelements und dem oberen Rand des Dokuments die Top -Eigenschaft von ControlSiteanstelle der Top -Eigenschaft von Control.

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

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

Zugehöriger Inhalt