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

  • Artikel

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

Betrifft: Die Informationen in diesem Thema betreffen VSTO-Add-In-Projekte für Word 2010. Weitere Informationen finden Sie unter Features Available by Office Application and Project Type.

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

    Hinweis

    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 der IDE.

Voraussetzungen

Zum Abschließen dieser exemplarischen Vorgehensweise benötigen Sie Folgendes:

Erstellen eines neuen Word-Add-In-Projekts

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

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

  1. Erstellen Sie ein VSTO-Add-In-Projekt für Word mit dem Namen "WordDynamicControls". Weitere Informationen finden Sie unter How to: Create Office projects 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.

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

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änderder 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 group1ein 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.

Hinzufügen und Entfernen von Steuerelementen im aktiven Dokument

Sie müssen das aktive Dokument im VSTO-Add-In-Code in ein DocumentHostelement 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 mithilfe der 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 in 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 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);
    }
}

Entfernen des Schaltflächensteuerelements beim Speichern des Dokuments

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, um dynamisch erstellte Windows Forms-Steuerelemente in VSTO-Add-Ins sauber. In dieser exemplarischen Vorgehensweise entfernen Sie das Button Steuerelement programmgesteuert, 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 Klasse die ThisAddIn folgende Methode hinzu. Diese Methode ist ein Ereignishandler für das 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 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 im Menüband klickt

Ändern Sie schließlich die Click Ereignishandler der Kontrollkästchen, die Sie dem Menüband hinzugefügt haben, um dem Dokument Steuerelemente hinzuzufügen oder zu entfernen.

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

  1. Ersetzen Sie in der Codedatei "MyRibbon.cs " oder "MyRibbon.vb " die generierten addButtonCheckBox_Click und addRichTextCheckBox_Click Ereignishandler 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();
}

Testen der Lösung

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:

Zugehöriger Inhalt