Rendre des contrôles dynamiques persistants dans des documents Office
Les contrôle ajoutés au moment de l'exécution ne sont pas rendus persistants lorsque le document ou le classeur est enregistré et fermé. Le comportement exact est différent pour les contrôles hôtes et les contrôles Windows Forms. Dans les deux cas, vous pouvez ajouter un code à votre solution pour recréer les contrôles lorsque l'utilisateur rouvre le document.
Les contrôles que vous ajoutez à des documents au moment de l'exécution sont appelés des contrôles dynamiques. Pour plus d'informations sur les contrôles dynamiques, consultez Ajout de contrôles à des documents Office au moment de l'exécution.
S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document et de niveau application pour les applications suivantes : Excel 2007, Excel 2010, Word 2007 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.
Rendre des contrôles hôtes persistants dans le document
Lorsqu'un document est enregistré puis fermé, tous les contrôles hôtes dynamiques sont supprimés du document. Seuls les objets Office natifs sous-jacents restent à l'arrière-plan. Par exemple, un contrôle hôte Microsoft.Office.Tools.Excel.ListObject devient un Microsoft.Office.Interop.Excel.ListObject. Les objets Office natifs ne sont pas connectés aux événements des contrôles hôtes et ne disposent pas de la fonctionnalité de liaison de données de ces derniers.
Le tableau suivant répertorie les objets Office natifs laissés à l'arrière-plan d'un document pour chaque type de contrôle hôte.
Recréation de contrôles hôtes dynamiques lorsque des documents sont ouverts
Vous pouvez recréer des contrôles hôtes dynamiques au lieu des contrôles natifs existants chaque fois qu'un utilisateur ouvre le document. Cette méthode de création de contrôles hôtes lorsqu'un document est ouvert simule l'expérience à laquelle les utilisateurs peuvent s'attendre.
Pour recréer un contrôle hôte pour Word ou un contrôle hôte Microsoft.Office.Tools.Excel.NamedRange ou Microsoft.Office.Tools.Excel.ListObject pour Excel, utilisez une méthode Add<classe de contrôle> d'un objet Microsoft.Office.Tools.Excel.ControlCollection ou Microsoft.Office.Tools.Word.ControlCollection. Utilisez une méthode qui possède un paramètre pour l'objet Office natif.
Par exemple, si vous souhaitez créer un contrôle hôte Microsoft.Office.Tools.Excel.ListObject à partir d'un Microsoft.Office.Interop.Excel.ListObject natif existant lorsque le document est ouvert, utilisez la méthode AddListObject(ListObject) et passez le Microsoft.Office.Interop.Excel.ListObject existant. L'exemple de code suivant montre cela dans un projet au niveau du document pour Excel. Le code recrée un Microsoft.Office.Tools.Excel.ListObject dynamique basé sur un Microsoft.Office.Interop.Excel.ListObject existant nommé MyListObject dans la classe Sheet1.
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
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);
}
}
Recréation de graphiques
Pour recréer un contrôle hôte Microsoft.Office.Tools.Excel.Chart, vous devez tout d'abord supprimer le Microsoft.Office.Interop.Excel.Chart natif, puis recréer le Microsoft.Office.Tools.Excel.Chart en utilisant la méthode AddChart(Range, String) ou AddChart(Double, Double, Double, Double, String). Il n'existe pas de méthode Add<classe de contrôle> vous permettant de créer un nouveau Microsoft.Office.Tools.Excel.Chart sur la base d'un Microsoft.Office.Interop.Excel.Chart existant.
Si vous ne supprimez pas en premier lieu le Microsoft.Office.Interop.Excel.Chart natif, vous créez alors un second graphique dupliqué lorsque vous recréez Microsoft.Office.Tools.Excel.Chart.
Rendre des contrôles Windows Forms persistants dans les documents
Lorsqu'un document est enregistré puis fermé, Visual Studio Tools pour Office Runtime supprime automatiquement tous les contrôles Windows Forms créés dynamiquement dans le document. Le comportement est toutefois différent pour les projets au niveau du document et au niveau de l'application.
Dans les personnalisations au niveau du document, les contrôles et les wrappers ActiveX sous-jacents (utilisés pour héberger les contrôles dans le document) sont supprimés lors de l'ouverture suivante du document. Rien n'indique que les contrôles y ont un jour existé.
Dans les compléments d'application, les contrôles sont supprimés, mais les wrappers ActiveX restent dans le document et sont visibles lorsque l'utilisateur rouvre le document. Dans Excel, les wrappers ActiveX affichent des images des contrôles tels qu'ils sont apparus la dernière fois que le document a été enregistré. Dans Word, les wrappers ActiveX sont invisibles, sauf si l'utilisateur clique dessus, auquel cas ils affichent un trait en pointillés représentant la bordure des contrôles. Il existe différentes façons de supprimer les wrappers ActiveX. Pour plus d'informations, consultez Supprimer des wrappers ActiveX dans un complément.
Recréation de contrôles Windows Forms lorsque des documents sont ouverts
Vous pouvez recréer des contrôles Windows Forms supprimés lorsque l'utilisateur rouvre le document. Pour ce faire, votre solution doit exécuter les tâches suivantes :
Stocker des informations concernant la taille, l'emplacement et l'état des contrôles lorsque le document est enregistré ou fermé. Dans une personnalisation au niveau du document, vous pouvez enregistrer ces données dans le cache de données du document. Dans un complément d'application, vous pouvez les enregistrer dans une partie XML personnalisée du document.
Recréez les contrôles dans un événement déclenché lorsque le document est ouvert. Dans les projets au niveau du document, vous pouvez le faire dans le gestionnaire d'événements Sheetn_Startup ou ThisDocument_Startup. Dans les projets au niveau de l'application, vous pouvez le faire dans les gestionnaires d'événements des événements WorkbookOpen ou DocumentOpen.
Supprimer des wrappers ActiveX dans un complément
Lorsque vous ajoutez des contrôles Windows Forms dynamiques à des documents en utilisant un complément, vous pouvez empêcher les wrappers ActiveX des contrôles d'apparaître dans le document lors de sa prochaine ouverture en procédant comme suit.
Supprimer des wrappers ActiveX à l'ouverture du document
Pour supprimer tous les wrappers ActiveX, appelez la méthode GetVstoObject pour générer un élément hôte pour Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Workbook qui représente le document récemment ouvert. Par exemple, vous pouvez appeler la méthode GetVstoObject pour générer un élément hôte pour l'objet Document passé au gestionnaire d'événements pour l'événement DocumentOpen pour supprimer tous les wrappers ActiveX d'un document Word.
Cette procédure est utile lorsque vous savez que le document sera ouvert uniquement sur des ordinateurs où le complément est installé. Si le document est susceptible d'être transféré à des utilisateurs qui n'ont pas installé le complément, il peut être préférable de supprimer les contrôles avant de fermer le document.
L'exemple de code suivant montre comment appeler la méthode GetVstoObject à l'ouverture du document.
Private Sub Application_DocumentOpen_ClearActiveXWrappers( _
ByVal Doc As Word.Document) Handles Application.DocumentOpen
' 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 Microsoft.Office.Tools.Word.Document = Doc.GetVstoObject()
End Sub
private void Application_DocumentOpen_ClearActiveXWrappers(Word.Document Doc)
{
// 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();
}
Bien que la méthode GetVstoObject soit surtout utilisée pour générer un nouvel élément hôte au moment de l'exécution, elle efface également tous les wrappers ActiveX du document la première fois qu'elle est appelée pour un document spécifique. Pour plus d'informations sur l'utilisation de la méthode GetVstoObject, consultez Extension de documents Word et de classeurs Excel dans des compléments d'application au moment de l'exécution..
Notez que si votre complément crée des contrôles dynamiques à l'ouverture du document, il appellera déjà la méthode GetVstoObject dans le cadre du processus de création des contrôles. Il est alors inutile d'ajouter un appel séparé à la méthode GetVstoObject pour supprimer les wrappers ActiveX.
Supprimer les contrôles dynamiques avant la fermeture du document
Votre complément peut supprimer de manière explicite les différents contrôles dynamiques du document avant la fermeture de ce dernier. Cette procédure est utile pour les documents susceptibles d'être transmis à des utilisateurs qui n'ont pas installé le complément.
L'exemple de code suivant montre comment supprimer tous les contrôles Windows Forms d'un document Word à la fermeture de ce dernier.
Private Sub Application_DocumentBeforeClose(ByVal Doc As Word.Document, _
ByRef Cancel As Boolean) Handles Application.DocumentBeforeClose
' 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()
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)
{
// 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();
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 aussi
Concepts
Ajout de contrôles à des documents Office au moment de l'exécution