Étendre des documents Word et des classeurs Excel dans des compléments VSTO au moment de l’exécution

Vous pouvez utiliser un complément VSTO pour personnaliser des documents Word et des classeurs Excel comme suit :

  • Ajoutez des contrôles managés à tout document ou feuille de calcul ouvert.

  • Convertissez un objet de liste existant sur une feuille de calcul Excel en un ListObject étendu qui expose des événements et qui peut être lié aux données à l'aide du modèle de liaison de données Windows Forms.

  • Accédez à des événements de niveau application qui sont exposés par Word et Excel pour des documents, des classeurs et des feuilles de calcul spécifiques.

    Pour utiliser cette fonctionnalité, vous générez, au moment de l'exécution, un objet qui étend le document ou le classeur.

    S’applique à : Les informations contenues dans cet article s’appliquent aux projets de compléments VSTO pour les applications suivantes : Excel et Word. Pour plus d’informations, consultez fonctionnalités disponibles par type d’application et de projet Office.

Générer des objets étendus dans les compléments VSTO

Les objets étendus sont des instances des types fournis par le runtime Visual Studio Tools pour Office qui ajoutent des fonctionnalités aux objets qui existent en mode natif dans les modèles objet Word ou Excel (appelés objets Office natifs). Pour générer un objet étendu pour un objet Word ou Excel, utilisez la méthode GetVstoObject. La première fois que vous appelez la GetVstoObject méthode pour un objet Word ou Excel spécifié, elle retourne un nouvel objet qui étend l’objet spécifié. Chaque fois que vous appelez la méthode et que vous spécifiez le même objet Word ou Excel, elle retourne le même objet étendu.

Le nom du type de l'objet étendu est identique à celui du type de l'objet Office natif, mais le type est défini dans l'espace de noms Microsoft.Office.Tools.Excel ou Microsoft.Office.Tools.Word . Par exemple, si vous appelez la méthode GetVstoObject pour étendre un objet Document, la méthode retourne un objet Document.

Les méthodes GetVstoObject sont destinées à être utilisées principalement dans les projets de complément VSTO. Vous pouvez également les utiliser dans des projets de niveau document, mais elles se comportent différemment et ont moins d'utilisations.

Pour déterminer si un objet étendu a déjà été généré pour un objet Office natif particulier, utilisez la méthode HasVstoObject. Pour plus d’informations, consultez déterminer si un objet Office a été étendu.

Générer des éléments hôtes

Quand vous utilisez GetVstoObject pour étendre un objet au niveau du document (autrement dit,, Workbook Worksheet ou Document ), l’objet retourné est appelé élément hôte. Un élément hôte est un type qui peut contenir d'autres objets, y compris d'autres objets et contrôles étendus. Il ressemble au type correspondant dans l'assembly PIA (Primary Interop Assembly) Word ou Excel, mais il comporte des fonctionnalités supplémentaires. Pour plus d’informations sur les éléments hôtes, consultez vue d’ensemble des éléments hôtes et des contrôles hôtes.

Après avoir généré un élément hôte, vous pouvez l'utiliser pour ajouter des contrôles managés au document, au classeur ou à la feuille de calcul. Pour plus d’informations, consultez Ajouter des contrôles managés à des documents et des feuilles de calcul.

Pour générer un élément hôte pour un document Word

  • L'exemple de code suivant montre comment générer un élément hôte pour le document actif.

    If Globals.ThisAddIn.Application.Documents.Count > 0 Then
        Dim NativeDocument As Microsoft.Office.Interop.Word.Document = _
            Globals.ThisAddIn.Application.ActiveDocument
        Dim VstoDocument As Microsoft.Office.Tools.Word.Document = _
            Globals.Factory.GetVstoObject(NativeDocument)
    End If
    
    if (Globals.ThisAddIn.Application.Documents.Count > 0)
    {
        Microsoft.Office.Interop.Word.Document nativeDocument =
            Globals.ThisAddIn.Application.ActiveDocument;
        Microsoft.Office.Tools.Word.Document vstoDocument =
            Globals.Factory.GetVstoObject(nativeDocument);
    }
    

Pour générer un élément hôte pour un classeur Excel

  • L'exemple de code suivant montre comment générer un élément hôte pour le classeur actif.

    Dim NativeWorkbook As Microsoft.Office.Interop.Excel.Workbook =
        Globals.ThisAddIn.Application.ActiveWorkbook
    If NativeWorkbook IsNot Nothing Then
        Dim vstoWorkbook As Microsoft.Office.Tools.Excel.Workbook =
            Globals.Factory.GetVstoObject(NativeWorkbook)
    End If
    
    Microsoft.Office.Interop.Excel.Workbook nativeWorkbook = 
        Globals.ThisAddIn.Application.ActiveWorkbook;
    if (nativeWorkbook != null)
    {
        Microsoft.Office.Tools.Excel.Workbook vstoWorkbook = 
            Globals.Factory.GetVstoObject(nativeWorkbook);
    }
    

Pour générer un élément hôte pour une feuille de calcul Excel

  • L'exemple de code suivant montre comment générer un élément hôte de la feuille de calcul active dans un projet.

    Dim NativeWorksheet As Microsoft.Office.Interop.Excel.Worksheet =
        Globals.ThisAddIn.Application.ActiveSheet
    If NativeWorksheet IsNot Nothing Then
        Dim vstoSheet As Microsoft.Office.Tools.Excel.Worksheet =
            Globals.Factory.GetVstoObject(NativeWorksheet)
    End If
    
    Microsoft.Office.Interop.Excel.Worksheet nativeWorksheet =
        Globals.ThisAddIn.Application.ActiveSheet;
    if (nativeWorksheet != null)
    {
        Microsoft.Office.Tools.Excel.Worksheet vstoSheet = 
            Globals.Factory.GetVstoObject(nativeWorksheet);
    }
    

Générer des contrôles hôtes ListObject

Lorsque vous utilisez la méthode GetVstoObject pour étendre un objet ListObject, la méthode retourne un objet ListObject. ListObjectContient toutes les fonctionnalités de l’original ListObject . Il offre également des fonctionnalités supplémentaires et peut être lié aux données à l’aide du modèle de liaison de données Windows Forms. Pour plus d’informations, consultez ListObject Control.

Pour générer un contrôle hôte pour un ListObject

  • L'exemple de code suivant montre comment générer un ListObject pour le premier ListObject dans la feuille de calcul active dans un projet.

    Dim sheet As Microsoft.Office.Interop.Excel.Worksheet =
        Globals.ThisAddIn.Application.ActiveSheet
    If sheet.ListObjects.Count > 0 Then
        Dim listObject As Excel.ListObject = sheet.ListObjects(1)
        Dim vstoListObject As Microsoft.Office.Tools.Excel.ListObject =
            Globals.Factory.GetVstoObject(listObject)
    End If
    
    Microsoft.Office.Interop.Excel.Worksheet sheet =
        Globals.ThisAddIn.Application.ActiveSheet;
    if (sheet.ListObjects.Count > 0)
    {
        Excel.ListObject listObject = 
            sheet.ListObjects[1];
        Microsoft.Office.Tools.Excel.ListObject vstoListObject =
            Globals.Factory.GetVstoObject(listObject);
    }
    

Ajouter des contrôles managés aux documents et aux feuilles de calcul

Après avoir généré un objet Document ou un objet Worksheet, vous pouvez ajouter des contrôles au document ou à la feuille de calcul que ces objets étendus représentent. Pour ajouter des contrôles, utilisez la Controls propriété de Document ou Worksheet . Pour plus d’informations, consultez Ajouter des contrôles aux documents Office au moment de l’exécution.

Vous pouvez ajouter des contrôles Windows Forms ou des contrôles hôtes. Un contrôle hôte est un contrôle fourni par Visual Studio Tools pour Office Runtime qui encapsule un contrôle correspondant dans l'assembly PIA Word ou Excel. Un contrôle hôte expose tout le comportement de l’objet Office natif sous-jacent. Il déclenche également des événements et peut être lié aux données à l’aide du modèle de liaison de données Windows Forms. Pour plus d’informations, consultez vue d’ensemble des éléments hôtes et des contrôles hôtes.

Notes

Vous ne pouvez pas utiliser un complément VSTO pour ajouter un contrôle XmlMappedRange à une feuille de calcul, ou bien un contrôle XMLNode ou XMLNodes à un document. Ces contrôles ne peuvent pas être ajoutés par programmation. Pour plus d’informations, consultez limitations de programmation des éléments hôtes et des contrôles hôtes.

Persistance et suppression de contrôles

Lorsque vous ajoutez des contrôles managés à un document ou à une feuille de calcul, les contrôles ne sont pas persistant lorsque le document est enregistré puis fermé. Tous les contrôles hôtes sont supprimés afin que seuls les objets Office natifs sous-jacents soient conservés. Par exemple, un ListObject devient un ListObject. Tous les contrôles Windows Forms sont également supprimés, mais leurs wrappers ActiveX sont conservés dans le document. Vous devez inclure du code dans votre complément VSTO pour nettoyer les contrôles ou les recréer à l'ouverture suivante du document. Pour plus d’informations, consultez persistance des contrôles dynamiques dans les documents Office.

Accéder aux événements de niveau application sur des documents et des classeurs

Certains événements de document, de classeur et de feuille de calcul dans les objets Word et Excel natifs sont déclenchés uniquement au niveau de l'application. Par exemple, l'événement DocumentBeforeSave est déclenché lorsqu'un document est ouvert dans Word, mais il est défini dans la classe Application , plutôt que dans la classe Document .

Quand vous utilisez uniquement des objets Office natifs dans votre complément VSTO, vous devez gérer ces événements de niveau application, puis écrire du code supplémentaire afin de déterminer si le document qui a déclenché l'événement est un document que vous avez personnalisé. Les éléments hôtes fournissent ces événements au niveau du document, afin qu'il soit plus facile de les gérer pour un document spécifique. Vous pouvez générer un élément hôte, puis gérer l'événement pour cet élément hôte.

Exemple qui utilise des objets Word natifs

L'exemple de code suivant montre comment gérer un événement de niveau application pour les documents Word. La méthode CreateDocument crée un document, puis définit un gestionnaire d'événements DocumentBeforeSave qui empêche l'enregistrement de ce document. L’événement est un événement de niveau application qui est déclenché pour l' Application objet, et le gestionnaire d’événements doit comparer le Doc paramètre avec l' document1 objet pour déterminer si document1 représente le document enregistré.

Private document1 As Word.Document = Nothing

Private Sub CreateDocument1()
    document1 = Me.Application.Documents.Add()
End Sub

Private Sub Application_DocumentBeforeSave(ByVal Doc As Word.Document, _
    ByRef SaveAsUI As Boolean, ByRef Cancel As Boolean) _
    Handles Application.DocumentBeforeSave
    If Type.ReferenceEquals(Doc, document1) Then
        Cancel = True
    End If
End Sub
private Word.Document document1 = null;

private void CreateDocument1()
{
    document1 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    this.Application.DocumentBeforeSave += 
        new Word.ApplicationEvents4_DocumentBeforeSaveEventHandler(
        Application_DocumentBeforeSave);
}

private void Application_DocumentBeforeSave(Word.Document Doc, 
    ref bool SaveAsUI, ref bool Cancel)
{
    if (Type.ReferenceEquals(Doc, document1)) 
    {
        Cancel = true;
    }
}

Exemples qui utilisent un élément hôte

Les exemples de code suivants simplifient ce processus en gérant l'événement BeforeSave d'un élément hôte Document . La CreateDocument2 méthode dans ces exemples génère un Document qui étend l' document2 objet, puis définit un BeforeSave Gestionnaire d’événements qui empêche l’enregistrement du document. Le gestionnaire d’événements est appelé uniquement lorsque document2 est enregistré et peut annuler l’action d’enregistrement sans effectuer de travail supplémentaire pour vérifier quel document a été enregistré.

L'exemple de code suivant illustre cette tâche.

Private document2 As Word.Document = Nothing
Private WithEvents vstoDocument As Microsoft.Office.Tools.Word.Document = Nothing

Private Sub CreateDocument2()
    document2 = Me.Application.Documents.Add()
    vstoDocument = Globals.Factory.GetVstoObject(document2)
End Sub

Private Sub vstoDocument_BeforeSave(ByVal sender As Object, _
    ByVal e As SaveEventArgs) Handles vstoDocument.BeforeSave
    e.Cancel = True
End Sub
private Word.Document document2 = null;
private Microsoft.Office.Tools.Word.Document vstoDocument = null;

private void CreateDocument2()
{
    document2 = this.Application.Documents.Add(ref missing,
        ref missing, ref missing, ref missing);
    vstoDocument = Globals.Factory.GetVstoObject(document2);
    vstoDocument.BeforeSave += new SaveEventHandler(vstoDocument_BeforeSave);
}

private void vstoDocument_BeforeSave(object sender, SaveEventArgs e)
{
    e.Cancel = true;
}

Déterminer si un objet Office a été étendu

Pour déterminer si un objet étendu a déjà été généré pour un objet Office natif particulier, utilisez la méthode HasVstoObject. Cette méthode retourne la valeur true si un objet étendu a déjà été généré.

Utiliser la méthode Globals.Factory.HasVstoMethod. Passez l'objet Word ou Excel natif, comme un objet Document ou Worksheet, pour lequel vous voulez vérifier s'il s'agit d'objet étendu.

La méthode HasVstoObject s'avère utile lorsque vous voulez exécuter du code uniquement lorsqu'un objet Office spécifié possède un objet étendu. Par exemple, si vous avez un complément VSTO Word qui gère l' DocumentBeforeSave événement pour supprimer des contrôles managés d’un document avant son enregistrement, utilisez la HasVstoObject méthode pour déterminer si le document a été étendu. Si le document n’a pas été étendu, il ne peut pas avoir de contrôles managés, et le gestionnaire d’événements peut retourner sans essayer de nettoyer des contrôles sur le document.

Voir aussi