Rendre des contrôles dynamiques persistants dans des documents Office
Mise à jour : Juillet 2008
S'applique à |
|---|
Les informations de cette rubrique s'appliquent uniquement aux projets Visual Studio Tools pour Office et versions de Microsoft Office spécifiés. Projets au niveau du document
Projets au niveau de l'application
Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet. |
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.
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.
Type de contrôle hôte |
Type d'objet Office natif |
|---|---|
Microsoft.Office.Tools.Word.BuildingBlockGalleryContentControl Microsoft.Office.Tools.Word.ComboBoxContentControl Microsoft.Office.Tools.Word.ContentControl Microsoft.Office.Tools.Word.DatePickerContentControl Microsoft.Office.Tools.Word.DropDownListContentControl Microsoft.Office.Tools.Word.GroupContentControl Microsoft.Office.Tools.Word.PictureContentControl |
Microsoft.Office.Interop.Word.ContentControl |
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> de la classe Microsoft.Office.Tools.Excel.ControlCollection ou Microsoft.Office.Tools.Word.ControlCollection 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 illustre ce processus dans un projet au niveau du document pour Excel 2007. 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);
}
}
Pour obtenir des exemples au niveau du document des contrôles dynamiques, consultez Contrôles dynamiques Excel, exemple et Contrôles dynamiques Word, exemple.
Pour obtenir des exemples de niveau application des contrôles dynamiques, consultez Contrôles dynamiques de complément Excel, exemple et Contrôles dynamiques de complément Word, exemple.
Recréation de ListObjects dans des projets Excel 2003 et Excel 2007 avant SP1
La méthode AddListObject(ListObject) est une nouveauté des projets Excel 2007 dans Visual Studio 2008 Service Pack 1 (SP1). Si vous utilisez un projet Excel 2007 et que vous n'avez pas installé le Service Pack 1, ou si vous utilisez un projet Excel 2003, vous ne pouvez pas utiliser cette méthode pour recréer un Microsoft.Office.Tools.Excel.ListObject dynamique.
À la place, vous devez tout d'abord supprimer le Microsoft.Office.Interop.Excel.ListObject natif, puis recréer le Microsoft.Office.Tools.Excel.ListObject dynamique en utilisant la méthode AddListObject(Range, String). Pour retrouver un code qui le démontre, consultez Contrôles dynamiques Excel, exemple.
Si vous ne supprimez pas en premier lieu leMicrosoft.Office.Interop.Excel.ListObject natif, vous recevez COMException lorsque vous tentez de recréer Microsoft.Office.Tools.Excel.ListObject, car Excel ne vous autorise pas à créer des objets de liste se chevauchant.
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é, le runtime Visual Studio Tools pour Office supprime automatiquement du document tous les contrôles Windows Forms créés dynamiquement. Le comportement est toutefois différent pour les projets au niveau du document et de niveau 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 de niveau application, vous pouvez le faire dans les gestionnaires d'événements des événements WorkbookOpen ou DocumentOpen.
Pour obtenir des exemples au niveau du document des contrôles dynamiques, consultez Contrôles dynamiques Excel, exemple et Contrôles dynamiques Word, exemple.
Pour obtenir des exemples de niveau application, consultez Contrôles dynamiques de complément Excel, exemple et Contrôles dynamiques de complément Word, exemple.
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 du Microsoft.Office.Interop.Word.Document ou du Microsoft.Office.Interop.Excel.Workbook qui correspond au document ouvert. Par exemple, pour supprimer tous les wrappers ActiveX d'un document Word, vous pouvez appeler la méthode GetVstoObject de l'objet Document passé au gestionnaire d'événements pour l'événement DocumentOpen.
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
Dim vstoDocument As Microsoft.Office.Tools.Word.Document = Doc.GetVstoObject()
End Sub
private void Application_DocumentOpen_ClearActiveXWrappers(Word.Document Doc)
{
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
If Doc.HasVstoObject() Then
Dim vstoDocument As Microsoft.Office.Tools.Word.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)
{
if (Doc.HasVstoObject())
{
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
Tâches
Contrôles dynamiques Excel, exemple
Contrôles dynamiques Word, exemple
Contrôles dynamiques de complément Excel, exemple
Contrôles dynamiques de complément Word, exemple
Concepts
Ajout de contrôles à des documents Office au moment de l'exécution
Méthodes d'assistance pour les contrôles hôtes
Méthodes d'assistance pour les contrôles Windows Forms
Historique des modifications
Date |
Historique |
Raison |
|---|---|---|
|
Juillet 2008 |
Ajout d'informations relatives aux contrôles dynamiques persistants dans les compléments d'application. |
Modifications de fonctionnalités dans le SP1. |