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

Artikel
08/10/2011

Mithilfe eines Add-Ins auf Anwendungsebene können Sie einem beliebigen geöffneten Microsoft Office Word-Dokument Steuerelemente hinzufügen. In dieser exemplarischen Vorgehensweise wird gezeigt, wie Sie Benutzern mithilfe des Menübands ermöglichen, einem Dokument einen Button oder ein RichTextContentControl hinzuzufügen.

Betrifft: Die Informationen in diesem Thema betreffen Projekte auf Anwendungsebene für Word 2007 und 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-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.

Tipp

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:

Eine Version von Visual Studio 2010, die die Microsoft Office-Entwicklungstools einschließt. Weitere Informationen finden Sie unter [Konfigurieren eines Computers zum Entwickeln von Office-Lösungen](bb398242\(v=vs.100\).md).

Word 2007 oder Word 2010

Erstellen eines neuen Word-Add-In-Projekts

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

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

Erstellen Sie ein Add-In-Projekt auf Anwendungsebene für Word mit dem Namen "WordDynamicControls". Weitere Informationen finden Sie unter Gewusst wie: Erstellen von Office-Projekten in Visual Studio.
Wenn das Projekt auf .NET Framework 4 ausgerichtet ist, fügen Sie einen Verweis auf die Microsoft.Office.Tools.Word.v4.0.Utilities.dll-Assembly hinzu. Dieser Verweis ist erforderlich, um dem Dokument später in dieser exemplarischen Vorgehensweise programmgesteuert ein Windows Forms-Steuerelement hinzuzufügen.

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

Fügen Sie dem Menüband 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

Klicken Sie im Menü Projekt auf Neues Element hinzufügen.
Wählen Sie im Dialogfeld Neues Element hinzufügen das Element Menüband (Visual Designer) aus.
Ändern Sie den Namen des neuen Menübands in MyRibbon, und klicken Sie 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.
Klicken Sie im Menüband-Designer auf die Gruppe group1.
Ändern Sie im Fenster Eigenschaften die Label-Eigenschaft für group1 in "Steuerelemente hinzufügen".
Ziehen Sie von der Registerkarte Steuerelemente für Office-Menübänder der Toolbox ein CheckBox-Steuerelement auf group1.
Klicken Sie auf CheckBox1, um das Element auszuwählen.
Ändern Sie im Eigenschaftenfenster die folgenden Eigenschaften.

Eigenschaft

Wert

Name

addButtonCheckBox

Bezeichnung

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

Eigenschaft

Wert

Name

addRichTextCheckBox

Bezeichnung

Rich-Text-Steuerelement hinzufügen
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.
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.

Eigenschaft	Wert
Name	addButtonCheckBox
Bezeichnung	Schaltfläche "Hinzufügen"

Eigenschaft	Wert
Name	addRichTextCheckBox
Bezeichnung	Rich-Text-Steuerelement hinzufügen

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 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 auf dem Menüband aufrufen.

So fügen Sie Steuerelemente im aktiven Dokument hinzu und entfernen diese

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

Fügen Sie der ThisAddIn-Klasse 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;

Fügen Sie der ThisAddIn-Klasse die folgende Methode hinzu. Wenn der Benutzer auf das Kontrollkästchen "Schaltfläche 'Hinzufügen'" auf dem Menüband 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()
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()

    Dim name As String = "MyButton"

    If Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked Then
        Dim selection = Me.Application.Selection
        If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
            button = vstoDocument.Controls.AddButton( _
                selection.Range, 100, 30, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleButtonOnDocument()
{
    // Use the following line of code in projects that target the .NET Framework 4.
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();

    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);
    }
}

Fügen Sie der ThisAddIn-Klasse die folgende Methode hinzu. Wenn der Benutzer auf das Kontrollkästchen "Rich-Text-Steuerelement hinzufügen" auf dem Menüband 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()
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Me.Application.ActiveDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim vstoDocument As Document = Me.Application.ActiveDocument.GetVstoObject()

    Dim name As String = "MyRichTextBoxControl"

    If Globals.Ribbons.MyRibbon.addRichTextCheckBox.Checked Then
        Dim selection = Me.Application.Selection
        If selection IsNot Nothing AndAlso selection.Range IsNot Nothing Then
            richTextControl = vstoDocument.Controls.AddRichTextContentControl( _
                    selection.Range, name)
        End If
    Else
        vstoDocument.Controls.Remove(name)
    End If
End Sub

internal void ToggleRichTextControlOnDocument()
{
    // Use the following line of code in projects that target the .NET Framework 4.
    Document vstoDocument = Globals.Factory.GetVstoObject(this.Application.ActiveDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document vstoDocument = this.Application.ActiveDocument.GetVstoObject();

    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);
    }
}

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

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
    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim isExtended As Boolean = Doc.HasVstoObject()

    If isExtended Then
        ' Use the following line of code in projects that target the .NET Framework 4.
        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

        ' In projects that target the .NET Framework 3.5, use the following line of code.
        ' 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)
{
    // Use the following line of code in projects that target the .NET Framework 4.
    bool isExtended = Globals.Factory.HasVstoObject(Doc);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // bool isExtended = Doc.HasVstoObject();

    if (isExtended)
    {
        // Use the following line of code in projects that target the .NET Framework 4.
        Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

        // In projects that target the .NET Framework 3.5, use the following line of code.
        // Microsoft.Office.Tools.Word.Document vstoDocument = Doc.GetVstoObject();

        if (vstoDocument.Controls.Contains(button))
        {
            vstoDocument.Controls.Remove(button);
            Globals.Ribbons.MyRibbon.addButtonCheckBox.Checked = false;
        }
    }
}

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 auf dem Menüband klickt

Ändern Sie abschließend die Click-Ereignishandler der Kontrollkästchen, die Sie dem Menüband 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 auf dem Menüband 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 des Menübands auswählen. Wenn Sie das Dokument speichern, wird das Button-Steuerelement entfernt.

So testen Sie die Projektmappe

Drücken Sie F5, um das Projekt auszuführen.
Drücken Sie im aktiven Dokument mehrmals die EINGABETASTE, um dem Dokument neue leere Absätze hinzuzufügen.
Wählen Sie den ersten Absatz aus.
Klicken Sie auf die Registerkarte Add-Ins.
Klicken Sie in der Gruppe Steuerelemente hinzufügen auf Schaltfläche "Hinzufügen".

Im ersten Absatz wird eine Schaltfläche angezeigt.
Wählen Sie den letzten Absatz aus.
Klicken Sie in der Gruppe Steuerelement hinzufügen auf Rich-Text-Steuerelement hinzufügen.

Dem letzten Absatz wird ein Rich-Text-Inhaltssteuerelement hinzugefügt.
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:

In dem Beispiel für dynamische Add-In-Steuerelemente in Word unter Beispiele und exemplarische Vorgehensweisen für die Programmierung mit Office finden Sie ein Beispiel dafür, wie einem Dokument zur Laufzeit viele andere Typen von Steuerelementen hinzugefügt werden und wie die Steuerelemente beim erneuten Öffnen des Dokuments neu erstellt werden.
Unter Exemplarische Vorgehensweise: Hinzufügen von Steuerelementen zu einem Arbeitsblatt zur Laufzeit in einem Projekt auf Anwendungsebene finden Sie eine exemplarische Vorgehensweise zur Veranschaulichung, wie einem Arbeitsblatt unter Verwendung eines Add-Ins auf Anwendungsebene für Excel Steuerelemente hinzugefügt werden.

Siehe auch

Freigeben über