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

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.

Projekttyp

  • Projekte auf Anwendungsebene

Microsoft Office-Version

  • Word 2007

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

Ab Visual Studio 2008 Service Pack 1 (SP1) können Sie jedem offenen Microsoft Office Word 2007-Dokument Steuerelemente mithilfe eines Add-Ins auf Anwendungsebene hinzufügen. In dieser exemplarischen Vorgehensweise wird gezeigt, wie Sie Benutzern mithilfe der Multifunktionsleiste ermöglichen, einem Dokument einen Button oder ein RichTextContentControl hinzuzufügen.

In dieser exemplarischen Vorgehensweise werden die folgenden Aufgaben veranschaulicht:

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

  • Bereitstellen einer Benutzeroberfläche zum Hinzufügen von Steuerelementen zum Dokument.

  • Hinzufügen von Steuerelementen zum Dokument zur Laufzeit.

  • Entfernen von Steuerelementen aus dem Dokument.

Hinweis:

Ihr Computer zeigt möglicherweise für einige der Elemente der Visual Studio-Benutzeroberfläche in der folgenden Anleitung andere Namen oder Standorte an. Diese Elemente sind von der jeweiligen Visual Studio-Version und den verwendeten Einstellungen abhängig. Weitere Informationen finden Sie unter Visual Studio-Einstellungen.

Vorbereitungsmaßnahmen

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

  • Visual Studio Tools for Office (eine optionale Komponente von Visual Studio 2008 Professional und Visual Studio Team System).

  • Visual Studio 2008 SP1.

  • Microsoft Office Word 2007.

Erstellen eines neuen Word-Add-In-Projekts

Erstellen Sie zuerst ein Word 2007-Add-In-Projekt.

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

Bereitstellen einer Benutzeroberfläche zum Hinzufügen von Steuerelementen zu einem Dokument

Fügen Sie der Multifunktionsleiste in Word eine benutzerdefinierte Registerkarte hinzu. Die 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 das Element Multifunktionsleiste (Visual Designer) aus.

  3. Ändern Sie den Namen der neuen Multifunktionsleiste in MyRibbon, und klicken Sie auf Hinzufügen.

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

  4. Klicken Sie im Multifunktionsleisten-Designer auf die Gruppe group1.

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

  6. Ziehen Sie von der Registerkarte Steuerelemente für Office-Multifunktionsleisten der Toolbox ein CheckBox-Steuerelement auf group1.

  7. Klicken Sie auf CheckBox1, um das Element auszuwählen.

  8. Ändern Sie im Eigenschaftenfenster die folgenden Eigenschaften.

    Property

    Value

    Name

    addButtonComboBox

    Bezeichnung

    Schaltfläche "Hinzufügen"

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

    Property

    Value

    Name

    addRichTextCheckBox

    Bezeichnung

    Rich-Text-Steuerelement hinzufügen

  10. Doppelklicken Sie im Multifunktionsleisten-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 Multifunktionsleisten-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.

Im weiteren Verlauf dieser exemplarischen Vorgehensweise werden Sie diesen Ereignishandlern Code hinzufügen, um im aktiven Dokument Steuerelemente hinzuzufügen und zu entfernen.

Hinzufügen und Entfernen von Steuerelementen im aktiven Dokument

Im Add-In-Code muss das aktive Dokument in ein Microsoft.Office.Tools.Word.Document-Hostelement konvertiert werden, bevor Sie ein Steuerelement hinzufügen können. In Visual Studio Tools for Office-Projektmappen können verwaltete Steuerelemente nur zu Hostelementen hinzugefügt werden, die als Container für die Steuerelemente dienen. In Add-In-Projekten auf Anwendungsebene können Hostelemente nur zur Laufzeit mithilfe der GetVstoObject-Methode erstellt werden.

Fügen Sie Methoden zur ThisAddIn-Klasse hinzu, die aufgerufen werden können, um eine Button oder ein RichTextContentControl im aktiven Dokument hinzuzufügen oder zu entfernen. Im weiteren Verlauf dieser exemplarischen Vorgehensweise werden Sie diese Methoden in den Click-Ereignishandlern der Kontrollkästchen in der Multifunktionsleiste aufrufen.

So fügen Sie Steuerelemente im aktiven Dokument hinzu und 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 den folgenden Code hinzu: Mit diesem Code wird ein Button-Objekt und ein RichTextContentControl-Objekt deklariert, mit denen die Steuerelemente dargestellt werden, die dem Dokument hinzugefügt werden.

    Private button As Microsoft.Office.Tools.Word.Controls.Button = Nothing
    Private richTextControl As RichTextContentControl = Nothing
    
    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" in der Multifunktionsleiste klickt, fügt diese Methode eine Button zur aktuellen Auswahl im Dokument hinzu, wenn das Kontrollkästchen aktiviert ist, oder löscht die Button, wenn das Kontrollkästchen deaktiviert ist.

    Friend Sub ToggleButtonOnDocument()
        Dim nativeDocument As Word.Document = Globals.ThisAddIn.Application.ActiveDocument
        Dim vstoDocument As Document = nativeDocument.GetVstoObject()
        Dim name As String = "MyButton"
    
        If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
            If Globals.ThisAddIn.Application.Selection IsNot Nothing Then
                button = vstoDocument.Controls.AddButton( _
                    Globals.ThisAddIn.Application.Selection.Range, 100, 30, name)
            End If
        Else
            vstoDocument.Controls.Remove(name)
        End If
    End Sub
    
    internal void ToggleButtonOnDocument()
    {
        Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
        Document vstoDocument = nativeDocument.GetVstoObject();
        string name = "MyButton";
    
        if (Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked)
        {
            if (Globals.ThisAddIn.Application.Selection != null)
            {
                button = vstoDocument.Controls.AddButton(
                    Globals.ThisAddIn.Application.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 in der Multifunktionsleiste klickt, fügt diese Methode ein RichTextContentControl zur aktuellen Auswahl hinzu, wenn das Kontrollkästchen aktiviert ist, oder löscht das RichTextContentControl, wenn das Kontrollkästchen deaktiviert ist.

    Friend Sub ToggleRichTextControlOnDocument()
        Dim nativeDocument As Word.Document = Globals.ThisAddIn.Application.ActiveDocument
        Dim vstoDocument As Document = nativeDocument.GetVstoObject()
        Dim name As String = "MyRichTextBoxControl"
    
        If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
            If Globals.ThisAddIn.Application.Selection IsNot Nothing Then
                richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                        Globals.ThisAddIn.Application.Selection.Range, name)
            End If
        Else
            vstoDocument.Controls.Remove(name)
        End If
    End Sub
    
    internal void ToggleRichTextControlOnDocument()
    {
        Word.Document nativeDocument = Globals.ThisAddIn.Application.ActiveDocument;
        Document vstoDocument = nativeDocument.GetVstoObject();
        string name = "MyRichTextBoxControl";
    
        if (Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked)
        {
            if (Globals.ThisAddIn.Application.Selection != null)
            {
                richTextControl = vstoDocument.Controls.AddRichTextContentControl(
                    Globals.ThisAddIn.Application.Selection.Range, name);
            }
        }
        else
        {
            vstoDocument.Controls.Remove(name);
        }
    }
    

Entfernen des Button-Steuerelements, wenn das Dokument gespeichert wird

Windows Forms-Steuerelemente werden nicht beibehalten, wenn das Dokument gespeichert und geschlossen wird. Stattdessen verbleibt ein ActiveX-Wrapper für jedes Steuerelement im Dokument, und der Rand dieses Wrappers ist für Endbenutzer beim erneuten Öffnen des Dokuments sichtbar. Es gibt mehrere Möglichkeiten, dynamisch erstellte Windows Forms-Steuerelemente in 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 bzw. ThisAddIn.vb die folgende Methode zur ThisAddIn-Klasse hinzu. Bei dieser Methode handelt es sich um einen Ereignishandler für das DocumentBeforeSave-Ereignis. Wenn dem gespeicherten Dokument ein Document-Hostelement zugeordnet ist, ruft der Ereignishandler das Hostelement ab und entfernt ggf. das Button-Steuerelement.

    Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
        ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) Handles Application.DocumentBeforeSave
        If Doc.HasVstoObject() Then
            Dim vstoDocument As Document = Doc.GetVstoObject()
            If vstoDocument.Controls.Contains(button) Then
                vstoDocument.Controls.Remove(button)
                Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = False
            End If
        End If
    End Sub
    
    private void Application_DocumentBeforeSave(Word.Document Doc, 
        ref bool SaveAsUI, ref bool Cancel)
    {
        if (Doc.HasVstoObject())
        {
            Document vstoDocument = Doc.GetVstoObject();
    
            if (vstoDocument.Controls.Contains(button))
            {
                vstoDocument.Controls.Remove(button);
                Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
            }
        }
    }
    
  2. Fügen Sie in C# den folgenden Code zum ThisAddIn_Startup-Ereignishandler hinzu. Dieser Code ist in C# erforderlich, um den Application_DocumentBeforeSave-Ereignishandler mit dem DocumentBeforeSave-Ereignis zu verbinden.

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

Hinzufügen und Entfernen von Steuerelementen, wenn der Benutzer auf die Kontrollkästchen in der Multifunktionsleiste klickt

Ändern Sie abschließend die Click-Ereignishandler der Kontrollkästchen, die Sie der Multifunktionsleiste hinzugefügt haben, um Steuerelemente im Dokument hinzuzufügen oder zu entfernen.

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

  • Ersetzen Sie in der Codedatei MyRibbon.cs bzw. MyRibbon.vb die generierten Ereignishandler addButtonCheckBox_Click und addRichTextCheckBox_Click durch den folgenden Code. Dieser Code definiert diese Ereignishandler neu, sodass die ToggleButtonOnDocument-Methode und die ToggleRichTextControlOnDocument-Methode aufgerufen werden, die Sie der ThisAddIn-Klasse zuvor in dieser exemplarischen Vorgehensweise hinzugefügt haben.

    Private Sub addButtonCheckBox_Click(ByVal sender As System.Object, _
        ByVal e As RibbonControlEventArgs) Handles addButtonCheckBox.Click
        Globals.ThisAddIn.ToggleButtonOnDocument()
    End Sub
    
    Private Sub addRichTextCheckBox_Click(ByVal sender As System.Object, _
        ByVal e As RibbonControlEventArgs) Handles addRichTextCheckBox.Click
        Globals.ThisAddIn.ToggleRichTextControlOnDocument()
    End Sub
    
    private void addButtonCheckBox_Click(object sender, RibbonControlEventArgs e)
    {
        Globals.ThisAddIn.ToggleButtonOnDocument();
    }
    
    private void addRichTextCheckBox_Click(object sender, RibbonControlEventArgs e)
    {
        Globals.ThisAddIn.ToggleRichTextControlOnDocument();
    }
    

Testen der Projektmappe

Fügen Sie Steuerelemente einem Dokument hinzu, indem Sie sie auf der benutzerdefinierten Registerkarte der Multifunktionsleiste 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 Steuerelement 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 diesen Themen erfahren Sie mehr über Steuerelemente in Add-Ins auf Anwendungsebene:

Siehe auch

Aufgaben

Gewusst wie: Hinzufügen von Windows Forms-Steuerelementen zu Office-Dokumenten

Gewusst wie: Hinzufügen von Inhaltssteuerelementen zu Word-Dokumenten

Beispiel für dynamische Add-In-Steuerelemente in Word

Konzepte

Entwicklung von Add-Ins auf Anwendungsebene für Word

Hinzufügen von Steuerelementen zu Office-Dokumenten zur Laufzeit

Beibehalten von dynamischen Steuerelementen in Office-Dokumenten

Erweitern von Word-Dokumenten und Excel-Arbeitsmappen in Add-Ins auf Anwendungsebene zur Laufzeit

Änderungsprotokoll

Date

Versionsgeschichte

Grund

Juli 2008

Thema hinzugefügt.

SP1-Featureänderung.