Conserver les contrôles dynamiques persistants dans des documents OfficePersist dynamic controls in Office documents

Les contrôles ajoutés lors de l’exécution ne sont pas conservés lorsque le document ou le classeur est enregistré et fermé.Controls that are added at runtime are not persisted when the document or workbook is saved and closed. Le comportement exact est différent pour les contrôles hôtes et les contrôles Windows Forms.The exact behavior is different for host controls and Windows Forms controls. Dans les deux cas, vous pouvez ajouter du code à votre solution pour recréer les contrôles lorsque l’utilisateur ouvre de nouveau le document.In both cases, you can add code to your solution to re-create the controls when the user reopens the document.

Les contrôles que vous ajoutez aux documents au moment de l’exécution sont appelés contrôles dynamiques.Controls that you add to documents at run time are called dynamic controls. Pour plus d’informations sur les contrôles dynamiques, consultez ajouter des contrôles aux documents Office au moment de l’exécution.For more information about dynamic controls, see Add controls to Office documents at runtime.

S’applique à : Les informations contenues dans cette rubrique s’appliquent aux projets de niveau document et aux projets de compléments VSTO pour Excel et Word.Applies to: The information in this topic applies to document-level projects and VSTO add-in projects for Excel and Word. Pour plus d’informations, consultez Fonctionnalités disponibles par type d’application et de projet Office.For more information, see Features Available by Office Application and Project Type.

Conserver les contrôles hôtes dans le documentPersist host controls in the document

Lorsqu’un document est enregistré puis fermé, tous les contrôles hôtes dynamiques sont supprimés du document.When a document is saved and then closed, all dynamic host controls are removed from the document. Seuls les objets Office natifs sous-jacents restent en arrière-plan.Only the underlying native Office objects remain behind. Par exemple, un contrôle hôte ListObject devient un ListObject.For example, a ListObject host control becomes a ListObject. Les objets Office natifs ne sont pas liés aux événements de contrôle hôte, et ils n’ont pas la fonctionnalité de liaison des données du contrôle hôte.The native Office objects are not connected to the host control events, and they do not have the data binding functionality of the host control.

Le tableau suivant répertorie l’objet Office natif laissé en arrière-plan dans un document pour chaque type de contrôle hôte.The following table lists the native Office object that is left behind in a document for each type of host control.

Type de contrôle hôteHost control type Type d’objet Office natifNative Office object type
Chart Chart
ListObject ListObject
NamedRange Range
Bookmark Bookmark
BuildingBlockGalleryContentControl

ComboBoxContentControl

ContentControl

DatePickerContentControl

DropDownListContentControl

GroupContentControl

PictureContentControl

PlainTextContentControl

RichTextContentControl
ContentControl

Recréer des contrôles hôtes dynamiques lors de l’ouverture de documentsRe-create dynamic host controls when documents are opened

Vous pouvez recréer des contrôles hôtes dynamiques à la place des contrôles natifs existants chaque fois qu’un utilisateur ouvre le document.You can re-create dynamic host controls in place of existing native controls every time a user opens the document. Créer des contrôles hôtes de cette manière lors de l’ouverture d’un document simule l’expérience que les utilisateurs peuvent attendre.Creating host controls in this manner when a document is opened simulates the experience that users might expect.

Pour recréer un contrôle hôte pour Word, ou un NamedRange ou ListObject contrôle hôte pour Excel, utilisez un Add < classe contrôle> méthode d’un ControlCollection ou ControlCollection objet.To re-create a host control for Word, or a NamedRange or ListObject host control for Excel, use an Add<control class> method of an ControlCollection or ControlCollection object. Utilisez une méthode qui a un paramètre pour l’objet Office natif.Use a method that has a parameter for the native Office object.

Par exemple, si vous souhaitez créer un contrôle hôte ListObject à partir d’un ListObject natif existant lors de l’ouverture du document, utilisez la méthode AddListObject et transmettez le ListObjectexistant.For example, if you want to create a ListObject host control from an existing native ListObject when the document is opened, use the AddListObject method and pass in the existing ListObject. L’exemple de code suivant montre cette opération dans un projet au niveau du document pour Excel.The following code example demonstrates this in a document-level project for Excel. Le code recrée un ListObject dynamique qui est basé sur un ListObject existant nommé MyListObject dans la classe Sheet1 .The code re-creates a dynamic ListObject that is based on an existing ListObject named MyListObject in the Sheet1 class.

private Microsoft.Office.Tools.Excel.ListObject vstoListObject;
private const int DISP_E_BADINDEX = unchecked((int)0x8002000B);

private void Sheet1_Startup(object sender, System.EventArgs e)
{
    Excel.ListObject nativeListObject = null;

    try
    {
        nativeListObject = this.ListObjects.get_Item("MyListObject");
    }
    catch (System.Runtime.InteropServices.COMException ex)
    {
        // "MyListObject" does not exist.
        if (ex.ErrorCode != DISP_E_BADINDEX)
            throw;
    }

    if (nativeListObject != null)
    {
        vstoListObject = this.Controls.AddListObject(nativeListObject);
    }
}
Private vstoListObject As Microsoft.Office.Tools.Excel.ListObject
Private Const DISP_E_BADINDEX As Integer = CInt(&H8002000B)

Private Sub Sheet1_Startup(ByVal sender As Object, ByVal e As System.EventArgs) Handles Me.Startup
    Dim nativeListObject As Excel.ListObject = Nothing

    Try
        nativeListObject = Me.ListObjects("MyListObject")
    Catch ex As System.Runtime.InteropServices.COMException
        ' "MyListObject" does not exist.
        If ex.ErrorCode <> DISP_E_BADINDEX Then
            Throw
        End If
    End Try

    If nativeListObject IsNot Nothing Then
        vstoListObject = Me.Controls.AddListObject(nativeListObject)
    End If
End Sub

Recréez le graphiqueRe-create chart

Pour recréer un contrôle hôte Chart , vous devez d’abord supprimer le Chartnatif, puis recréez le Chart à l’aide de la méthode AddChart ou AddChart .To re-create a Chart host control, you must first delete the native Chart, and then re-create the Chart by using the AddChart or AddChart method. Il est sans Add < classe contrôle> méthode qui vous permet de créer un nouveau Chart basé sur un Chart.There is no Add<control class> method that enables you to create a new Chart based on an existing Chart.

Si vous ne commencez pas par supprimer le Chartnatif, vous allez alors créer un second graphique dupliqué lorsque vous recréerez le Chart.If you do not first delete the native Chart, then you will create a second, duplicate chart when you re-create the Chart.

Conserver les contrôles Windows Forms dans des documentsPersist Windows Forms controls in documents

Lorsqu’un document est enregistré puis fermé, le Visual Studio Tools pour Office RuntimeVisual Studio Tools for Office runtime supprime dans le document tous les contrôles Windows Forms créés dynamiquement.When a document is saved and then closed, the Visual Studio Tools pour Office RuntimeVisual Studio Tools for Office runtime automatically removes all dynamically created Windows Forms controls from the document. Toutefois, le comportement est différent pour les projets au niveau du document et de complément VSTO.However, the behavior is different for document-level and VSTO Add-in projects.

Dans les personnalisations au niveau du document, les contrôles et leurs wrappers ActiveX sous-jacents (qui sont utilisés pour héberger les contrôles dans le document) sont supprimés à la prochaine ouverture du document.In document-level customizations, the controls and their underlying ActiveX wrappers (which are used to host the controls on the document) are removed the next time the document is opened. Rien n’indique la présence de ces contrôles.There is no indication that the controls were ever there.

Dans les compléments VSTO, les contrôles sont supprimés mais les wrappers ActiveX restent dans le document.In VSTO Add-ins, the controls are removed, but the ActiveX wrappers remain in the document. Lors de la prochaine ouverture du document, les wrappers ActiveX seront visibles.The next time the user opens the document, the ActiveX wrappers are visible. Dans Excel, les wrappers ActiveX affichent des images des contrôles tels qu’ils apparaissent lors du dernier enregistrement du document.In Excel, the ActiveX wrappers display images of the controls as they appeared the last time the document was saved. Dans Word, les wrappers ActiveX sont invisibles, sauf si l’utilisateur clique dessus, auquel cas ils affichent une ligne en pointillé qui représente la bordure des contrôles.In Word, the ActiveX wrappers are invisible unless the user clicks on them, in which case they display a dotted line that represents the border of the controls. Vous pouvez supprimer les wrappers ActiveX de plusieurs façons.There are several ways you can remove the ActiveX wrappers. Pour plus d’informations, consultez supprimer les Wrappers ActiveX dans un complément.For more information, see Remove ActiveX Wrappers in an Add-in.

Recréer des contrôles Windows Forms lorsque des documents sont ouverts.Re-create Windows Forms controls when documents are opened

Vous pouvez recréer des contrôles Windows Forms supprimés lorsque l’utilisateur ouvre de nouveau le document.You can re-create deleted Windows Forms controls when the user reopens the document. Pour ce faire, votre solution doit effectuer les tâches suivantes :To do this, your solution must perform the following tasks:

  1. Stocker des informations sur la taille, l’emplacement et l’état des contrôles lorsque le document est enregistré ou fermé.Store information about the size, location, and state of the controls when the document is saved or closed. Dans une personnalisation au niveau du document, vous pouvez enregistrer les données dans le cache de données dans le document.In a document-level customization, you can save the data to the data cache in the document. Dans un complément VSTO, vous pouvez enregistrer les données à une partie XML personnalisée dans le document.In a VSTO Add-in, you can save the data to a custom XML part in the document.

  2. Recréez les contrôles dans un événement qui est déclenché lors de l’ouverture du document.Re-create the controls in an event that is raised when the document is opened. Dans les projets au niveau du document, vous pouvez le faire dans les gestionnaires d’évènements Sheetn_Startup ou ThisDocument_Startup .In document-level projects, you can do this in the Sheetn_Startup or ThisDocument_Startup event handlers. Dans les projets de complément VSTO, vous pouvez le faire dans les gestionnaires d’événements pour les événements <xref:Microsoft.Office.Interop.Excel.AppEvents_Event.WorkbookOpen> ou DocumentOpen .In VSTO Add-in projects, you can do this in the event handlers for the <xref:Microsoft.Office.Interop.Excel.AppEvents_Event.WorkbookOpen> or DocumentOpen events.

Supprimer les wrappers ActiveX dans un complémentRemove ActiveX wrappers in an Add-in

Lorsque vous ajoutez des contrôles Windows Forms dynamiques à des documents à l’aide d’un complément VSTO, vous pouvez empêcher l’apparition des wrappers ActiveX des contrôles dans le document lors de sa prochaine ouverture, en utilisant l’une des méthodes suivantes.When you add dynamic Windows Forms controls to documents by using an VSTO Add-in, you can prevent the ActiveX wrappers for the controls from appearing in the document the next time it is opened in the following ways.

Supprimer les wrappers ActiveX lorsque le document est ouvert.Remove ActiveX wrappers when the document is opened

Pour supprimer tous les wrappers ActiveX, appelez le GetVstoObject méthode permettant de générer un élément hôte pour le Document ou Workbook qui représente le document récemment ouvert.To remove all ActiveX wrappers, call the GetVstoObject method to generate a host item for the Document or Workbook that represents the newly opened document. Par exemple, pour supprimer tous les wrappers ActiveX dans un document Word, vous pouvez appeler la GetVstoObject méthode permettant de générer un élément hôte pour le Document objet est passé au gestionnaire d’événements pour le DocumentOpen événement.For example, to remove all ActiveX wrappers from a Word document, you can call the GetVstoObject method to generate a host item for the Document object that is passed to the event handler for the DocumentOpen event.

Cette procédure est utile lorsque vous savez que le document sera ouvert uniquement sur des ordinateurs avec le complément VSTO installé.This procedure is useful when you know that the document will be opened only on computers that have the VSTO Add-in installed. Si le document peut être transmis à d’autres utilisateurs qui n’ont pas le complément VSTO installé, envisagez de supprimer les contrôles avant de fermer le document.If the document might be passed to other users who do not have the VSTO Add-in installed, consider removing the controls before closing the document instead.

L’exemple de code suivant montre comment appeler le GetVstoObject méthode lorsque le document est ouvert.The following code example demonstrates how to call the GetVstoObject method when the document is opened.

Private Sub Application_DocumentOpen_ClearActiveXWrappers( _
    ByVal Doc As Word.Document) Handles Application.DocumentOpen

    Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

End Sub
private void Application_DocumentOpen_ClearActiveXWrappers(Word.Document Doc)
{
    Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

}

Bien que le GetVstoObject méthode est utilisée principalement pour générer un nouvel élément hôte lors de l’exécution, cette méthode efface également tous les wrappers ActiveX du document la première fois qu’elle est appelée pour un document spécifique.Although the GetVstoObject method is used primarily to generate a new host item at runtime, this method also clears all ActiveX wrappers from the document the first time it is called for a specific document. Pour plus d’informations sur l’utilisation de la GetVstoObject méthode, consultez documents Word d’étendre et classeurs Excel dans des Compléments VSTO lors de l’exécution.For more information about how to use the GetVstoObject method, see Extend Word documents and Excel workbooks in VSTO Add-ins at runtime.

Notez que si votre composant complément VSTO crée des contrôles dynamiques lorsque le document est ouvert, votre composant complément VSTO appellera déjà la GetVstoObject méthode dans le cadre du processus de création des contrôles.Note that if your VSTO Add-in creates dynamic controls when the document is opened, your VSTO Add-in will already call the GetVstoObject method as part of the process to create the controls. Vous n’avez pas besoin d’ajouter un appel séparé à la GetVstoObject méthode pour supprimer les wrappers ActiveX dans ce scénario.You do not need to add a separate call to the GetVstoObject method to remove the ActiveX wrappers in this scenario.

Supprimer les contrôles dynamiques avant la fermeture du documentRemove the dynamic controls before the document is closed

Votre complément VSTO peut supprimer, de manière explicite, chaque contrôle dynamique du document avant la fermeture de celui-ci.Your VSTO Add-in can explicitly remove each dynamic control from the document before the document is closed. Cette procédure est utile pour les documents qui peuvent être transmis à d’autres utilisateurs qui n’ont pas le complément VSTO installé.This procedure is useful for documents that might be passed to other users who do not have the VSTO Add-in installed.

L’exemple de code suivant montre comment supprimer tous les contrôles Windows Forms d’un document Word lorsque celui-ci est fermé.The following code example demonstrates how to remove all of the Windows Forms controls from a Word document when the document is closed.

Private Sub Application_DocumentBeforeClose(ByVal Doc As Word.Document, _
    ByRef Cancel As Boolean) Handles Application.DocumentBeforeClose

    Dim isExtended As Boolean = Globals.Factory.HasVstoObject(Doc)

    If isExtended Then

        Dim vstoDocument As Document = Globals.Factory.GetVstoObject(Doc)

        Dim controlsToRemove As System.Collections.ArrayList = _
            New System.Collections.ArrayList()

        ' Get all of the Windows Forms controls.
        For Each control As Object In vstoDocument.Controls
            If TypeOf control Is System.Windows.Forms.Control Then
                controlsToRemove.Add(control)
            End If
        Next

        ' Remove all of the Windows Forms controls from the document.
        For Each control As Object In controlsToRemove
            vstoDocument.Controls.Remove(control)
        Next
    End If
End Sub
void Application_DocumentBeforeClose(Word.Document Doc, ref bool Cancel)
{

    bool isExtended = Globals.Factory.HasVstoObject(Doc);

    if (isExtended)
    {
        Microsoft.Office.Tools.Word.Document vstoDocument = Globals.Factory.GetVstoObject(Doc);

        
        System.Collections.ArrayList controlsToRemove = 
            new System.Collections.ArrayList();
        
        // Get all of the Windows Forms controls.
        foreach (object control in vstoDocument.Controls)
        {
            if (control is System.Windows.Forms.Control)
            {
                controlsToRemove.Add(control);
            }
        }

        // Remove all of the Windows Forms controls from the document.
        foreach (object control in controlsToRemove)
        {
            vstoDocument.Controls.Remove(control);
        }
    }
}

Voir aussiSee also

Ajouter des contrôles aux documents Office au moment de l’exécutionAdd controls to Office documents at runtime