Markieren Sie das Kontrollkästchen Englisch, um die englische Version dieses Artikels anzuzeigen. Sie können den englischen Text auch in einem Popup-Fenster einblenden, indem Sie den Mauszeiger über den Text bewegen.
Übersetzung
Englisch

Exemplarische Vorgehensweise: Hinzufügen von Steuerelementen zu einem Dokument zur Laufzeit in einem VSTO-Add-In

 

Mit einem VSTO-Add-In können Sie jedem geöffneten Microsoft Office Word-Dokument Steuerelemente hinzufügen. In dieser exemplarischen Vorgehensweise wird veranschaulicht, wie Sie das Menüband verwenden können, um Benutzern das Hinzufügen eines Button- oder RichTextContentControl-Steuerelements zu einem Dokument zu ermöglichen.

Betrifft: Die Informationen in diesem Thema betreffen VSTO-Add-In-Projekte für Word 2010. Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

In dieser exemplarischen Vorgehensweise werden die folgenden Aufgaben veranschaulicht:

  • Erstellen eines neuen Word-VSTO-Add-In-Projekts

  • Bereitstellen einer Benutzeroberfläche (UI) zum Hinzufügen von Steuerelementen zum Dokument

  • Hinzufügen von Steuerelementen zum Dokument zur Laufzeit

  • Entfernen von Steuerelementen aus dem Dokument

System_CAPS_noteHinweis

Auf Ihrem Computer werden möglicherweise andere Namen oder Speicherorte für die Benutzeroberflächenelemente von Visual Studio angezeigt als die in den folgenden Anweisungen aufgeführten. Diese Elemente sind von der jeweiligen Visual Studio-Version und den verwendeten Einstellungen abhängig. Weitere Informationen finden Sie unter Personalisieren von Visual Studio-IDE.

Vorbereitungsmaßnahmen

Zum Durchführen dieser exemplarischen Vorgehensweise benötigen Sie die folgenden Komponenten:

Beginnen Sie, indem Sie ein Word-VSTO-Add-In-Projekt erstellen.

So erstellen Sie ein neues Word-VSTO-Add-In-Projekt

  1. Erstellen Sie VSTO-Add-In-Projekt für Word namens WordDynamicControls. Weitere Informationen finden Sie unter Gewusst wie: Erstellen von Office-Projekten in Visual Studio.

  2. Fügen Sie einen Verweis auf die Assembly Microsoft.Office.Tools.Word.v4.0.Utilities.dll hinzu. Dieser Verweis ist erforderlich, um später in dieser exemplarischen Vorgehensweise dem Dokument programmgesteuert ein Windows Forms-Steuerelement hinzuzufügen.

Fügen Sie dem Menüband in Word eine benutzerdefinierte Registerkarte hinzu. Benutzer können Kontrollkästchen auf der Registerkarte aktivieren, um einem Dokument Steuerelemente hinzuzufügen.

So stellen Sie eine Benutzeroberfläche zum Hinzufügen von Steuerelementen zu einem Dokument bereit

  1. Klicken Sie im Menü Projekt auf Neues Element hinzufügen.

  2. Wählen Sie im Dialogfeld Neues Element hinzufügen die Option Menüband (Visueller Designer) aus.

  3. Ändern Sie den Namen des neuen Menübands in MyRibbon, und klicken Sie dann auf Hinzufügen.

    Die Datei MyRibbon.cs oder MyRibbon.vb wird im Menüband-Designer geöffnet. Sie beinhaltet eine standardmäßige Registerkarte und eine Gruppe.

  4. Klicken Sie im Menüband-Designer auf die Gruppe group1.

  5. Ändern Sie im Fenster Eigenschaften die Bezeichnung-Eigenschaft für group1 in Steuerelemente hinzufügen.

  6. Ziehen Sie ein Kontrollkästchen-Steuerelement von der Registerkarte Steuerelemente für Office-Menübänder der Toolbox auf group1.

  7. Klicken Sie auf CheckBox1, um dieses Steuerelement auszuwählen.

  8. Ändern Sie im Fenster Eigenschaften die folgenden Eigenschaften:

    Eigenschaft

    Wert

    Name

    addButtonCheckBox

    Bezeichnung

    Schaltfläche hinzufügen

  9. Fügen Sie group1 ein zweites Kontrollkästchen hinzu, und ändern Sie dann die folgenden Eigenschaften.

    Eigenschaft

    Wert

    Name

    addRichTextCheckBox

    Bezeichnung

    Rich-Text-Steuerelement hinzufügen

  10. Doppelklicken Sie im Menüband-Designer auf Schaltfläche hinzufügen.

    Der Click-Ereignishandler des Kontrollkästchens Schaltfläche hinzufügen wird im Code-Editor geöffnet.

  11. Kehren Sie zum Menüband-Designer zurück, und doppelklicken Sie auf Rich-Text-Steuerelement hinzufügen.

    Der Click-Ereignishandler des Kontrollkästchens Rich-Text-Steuerelement hinzufügen wird im Code-Editor geöffnet.

Später in dieser exemplarischen Vorgehensweise werden Sie diesen Ereignishandlern Code hinzufügen, mit dem im aktiven Dokument Steuerelemente hinzugefügt und entfernt werden können.

Sie müssen das aktive Dokument im VSTO-Add-In-Code in ein Microsoft.Office.Tools.Word.Document-Hostelement konvertieren, bevor Sie ein Steuerelement hinzufügen können. In Office-Projektmappen können verwaltete Steuerelemente nur zu Hostelementen hinzugefügt werden, die als Container für die Steuerelemente fungieren. In VSTO-Add-In-Projekten können Hostelemente zur Laufzeit über die GetVstoObject-Methode erstellt werden.

Fügen Sie der ThisAddIn-Klasse Methoden hinzu, die aufgerufen werden können, um ein Button- oder ein RichTextContentControl-Steuerelement auf dem aktiven Dokument hinzuzufügen oder zu entfernen. Später in dieser exemplarischen Vorgehensweise werden Sie diese Methoden aus den Click-Ereignishandlern der Kontrollkästchen im Menüband aufrufen.

So fügen Sie Steuerelemente auf dem aktiven Dokument hinzu oder entfernen diese

  1. Doppelklicken Sie im Projektmappen-Explorer auf „ThisAddIn.cs“ oder „ThisAddIn.vb“, um die Datei im Code-Editor zu öffnen.

  2. Fügen Sie der ThisAddIn-Klasse folgenden Code hinzu. Mit diesem Code werden ein Button- und ein RichTextContentControl-Objekt deklariert, die den Steuerelementen entsprechen, die dem Dokument hinzugefügt werden.

    private Microsoft.Office.Tools.Word.Controls.Button button = null;
    private RichTextContentControl richTextControl = null;
    
  3. Fügen Sie der ThisAddIn-Klasse die folgende Methode hinzu. Wenn der Benutzer auf das Kontrollkästchen Schaltfläche hinzufügen im Menüband klickt, fügt diese Methode ein Button-Objekt zur aktuellen Auswahl im Dokument hinzu, wenn das Kontrollkästchen aktiviert ist, oder löscht sie das Button-Objekt, wenn das Kontrollkästchen deaktiviert ist.

    internal void ToggleButtonOnDocument()
    {
        Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
    
    
        string name = "MyButton";
    
        if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
        {
            Word.Selection selection = this.Application.Selection;
            if (selection != null && selection.Range != null)
            {
                button = vstoDocument.Controls.AddButton(
                    selection.Range, 100, 30, name);
            }
        }
        else
        {
            vstoDocument.Controls.Remove(name);
        }
    }
    
  4. Fügen Sie der ThisAddIn-Klasse die folgende Methode hinzu. Wenn der Benutzer auf das Kontrollkästchen Rich-Text-Steuerelement hinzufügen im Menüband klickt, fügt diese Methode ein RichTextContentControl-Objekt zur aktuellen Auswahl im Dokument hinzu, wenn das Kontrollkästchen aktiviert ist, oder löscht sie das RichTextContentControl-Objekt, wenn das Kontrollkästchen deaktiviert ist.

    internal void ToggleRichTextControlOnDocument()
    {
    
        Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);
    
    
        string name = "MyRichTextBoxControl";
    
        if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
        {
            Word.Selection selection = this.Application.Selection;
            if (selection != null && selection.Range != null)
            {
                richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                    selection.Range, name);
            }
        }
        else
        {
            vstoDocument.Controls.Remove(name);
        }
    }
    

Windows Forms-Steuerelemente bleiben nicht erhalten, wenn das Dokument gespeichert und dann geschlossen wird. Im Dokument verbleibt aber ein ActiveX-Wrapper für jedes Steuerelement, und der Rand eines solchen Wrappers ist für Endbenutzer nach einem erneuten Öffnen des Dokuments sichtbar. Es gibt mehrere Möglichkeiten, dynamisch erstellte Windows Forms-Steuerelemente in VSTO-Add-Ins zu bereinigen. In dieser exemplarischen Vorgehensweise wird das Button-Steuerelement programmgesteuert entfernt, wenn das Dokument gespeichert wird.

So entfernen Sie das Button-Steuerelement, wenn das Dokument gespeichert wird

  1. Fügen Sie in der Codedatei „ThisAddIn.cs“ oder „ThisAddIn.vb“ der ThisAddIn-Klasse die folgende Methode hinzu. Diese Methode ist ein Ereignishandler für das E:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentBeforeSave-Ereignis. Wenn dem gespeicherten Dokument ein Document-Hostelement zugeordnet ist, ruft der Ereignishandler das Hostelement ab und entfernt das Button-Steuerelement, wenn es vorhanden ist.

    private void Application_DocumentBeforeSave(Word.Document Doc, 
        ref bool SaveAsUI, ref bool Cancel)
    {
        bool isExtended = Globals.Factory.HasVstoObject(Doc);
    
    
        if (isExtended)
        {
    
            Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);
    
            if (vstoDocument.Controls.Contains(button))
            {
                vstoDocument.Controls.Remove(button);
                Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
            }
        }
    }
    
  2. In C# fügen Sie dem ThisAddIn_Startup-Ereignishandler den folgenden Code hinzu. Dieser Code ist in C# erforderlich, um den Application_DocumentBeforeSave-Ereignishandler mit dem E:Microsoft.Office.Interop.Word.ApplicationEvents4_Event.DocumentBeforeSave-Ereignis zu verbinden.

    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
    

Ändern Sie abschließend die Click-Ereignishandler der Kontrollkästchen, die Sie dem Menüband hinzugefügt haben, so, dass sie Steuerelemente auf dem Dokument hinzufügen oder entfernen.

So fügen Sie Steuerelemente hinzu oder entfernen diese, wenn der Benutzer auf die Kontrollkästchen im Menüband klickt

  1. Ersetzen Sie in der Codedatei „MyRibbon.cs“ oder „MyRibbon.vb“ die generierten Ereignishandler addButtonCheckBox_Click und addRichTextCheckBox_Click durch den folgenden Code. Dieser Code definiert diese Ereignishandler neu, sodass aus ihnen die ToggleButtonOnDocument- und die ToggleRichTextControlOnDocument-Methode aufgerufen werden, die Sie der ThisAddIn-Klasse früher in dieser exemplarischen Vorgehensweise hinzugefügt haben.

    private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
    {
        Globals.ThisAddIn.ToggleButtonOnDocument();
    }
    
    private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
    {
        Globals.ThisAddIn.ToggleRichTextControlOnDocument();
    }
    

Fügen Sie einem Dokument Steuerelemente hinzu, indem Sie sie auf der benutzerdefinierten Registerkarte im Menüband auswählen. Wenn Sie das Dokument speichern, wird das Button-Steuerelement entfernt.

So testen Sie die Projektmappe

  1. Drücken Sie F5, um das Projekt auszuführen.

  2. Drücken Sie im aktiven Dokument mehrmals die EINGABETASTE, um dem Dokument neue leere Absätze hinzuzufügen.

  3. Wählen Sie den ersten Absatz aus.

  4. Klicken Sie auf die Registerkarte Add-Ins.

  5. Klicken Sie in der Gruppe Steuerelemente hinzufügen auf Schaltfläche hinzufügen.

    Im ersten Absatz wird eine Schaltfläche angezeigt.

  6. Wählen Sie den letzten Absatz aus.

  7. Klicken Sie in der Gruppe Steuerelemente hinzufügen auf Rich-Text-Steuerelement hinzufügen.

    Dem letzten Absatz wird ein Rich-Text-Inhaltssteuerelement hinzugefügt.

  8. Speichern Sie das Dokument.

    Die Schaltfläche wird aus dem Dokument entfernt.

Nächste Schritte

In den folgenden Themen erhalten Sie weitere Informationen zu Steuerelementen in VSTO-Add-Ins:

Anzeigen: