Ajout de contrôles à des documents Office au moment de l'exécution
Vous pouvez ajouter et supprimer des contrôles dans un document Microsoft Office Word et un classeur Microsoft Office Excel au moment de l'exécution. Les contrôles que vous ajoutez à des documents au moment de l'exécution sont appelés des contrôles dynamiques.
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.
Cette rubrique fournit les informations suivantes :
Gestion de contrôles au moment de l'exécution à l'aide des collections de contrôle
Ajout de contrôles hôtes à des documents
Ajout de contrôles Windows Forms à des documents
Pour une démonstration vidéo connexe, consultez How Do I: Add Controls to a Document Surface at Runtime? (page éventuellement en anglais).
Gestion de contrôles au moment de l'exécution à l'aide des collections de contrôle
Pour ajouter, obtenir ou supprimer des contrôles au moment de l'exécution, utilisez les méthodes d'assistance des objets Microsoft.Office.Tools.Excel.ControlCollection et Microsoft.Office.Tools.Word.ControlCollection.
La manière d'accéder à ces objets dépend du type de projet que vous développez :
Dans un projet au niveau du document pour Excel, utilisez la propriété Worksheet.Controls des classes Sheet1, Sheet2 et Sheet3. Pour plus d'informations sur ces classes, consultez Élément hôte de feuille de calcul.
Dans un projet au niveau du document pour Word, utilisez la propriété Document.Controls de la classe ThisDocument. Pour plus d'informations sur cette classe, consultez Élément hôte de document.
Dans un projet au niveau de l'application pour Excel ou Word, utilisez la propriété Controls d'une Microsoft.Office.Tools.Excel.Worksheet ou d'un Microsoft.Office.Tools.Word.Document que vous générez au moment de l'exécution. Pour plus d'informations sur la génération de ces objets au moment de l'exécution, consultez Extension de documents Word et de classeurs Excel dans des compléments d'application au moment de l'exécution..
Ajout de contrôles
Les types Microsoft.Office.Tools.Excel.ControlCollection et Microsoft.Office.Tools.Word.ControlCollection incluent des méthodes d'assistance que vous pouvez utiliser pour ajouter des contrôles hôtes et des contrôles Windows Forms communs aux documents et feuilles de calcul. Chaque nom de méthode présente le format Add<classe de contrôle>, classe de contrôle étant le nom de classe du contrôle à ajouter. Par exemple, pour ajouter un contrôle NamedRange à votre document, utilisez la méthode AddNamedRange. Pour obtenir une liste complète des méthodes d'assistance, consultez Méthodes d'assistance pour les contrôles hôtes et Méthodes d'assistance pour les contrôles Windows Forms.
L'exemple de code suivant ajoute NamedRange à Sheet1 dans un projet au niveau du document pour Excel.
Dim range1 As Excel.Range = Globals.Sheet1.Range("A1", "D5")
Dim namedRange1 As Microsoft.Office.Tools.Excel.NamedRange = _
Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource")
Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");
Accès aux contrôles et suppression
Vous pouvez utiliser la propriété Controls d'une Microsoft.Office.Tools.Excel.Worksheet ou d'un Microsoft.Office.Tools.Word.Document pour itérer au sein de tous les contrôles de votre document, y compris ceux que vous avez ajoutés au moment du design. Les contrôles que vous ajoutez au moment du design sont également appelés des contrôles statiques.
Vous pouvez supprimer des contrôles dynamiques en appelant la méthode Delete du contrôle ou la méthode Remove de chaque collection Controls. L'exemple de code suivant utilise la méthode Remove pour supprimer NamedRange de Sheet1 dans un projet au niveau du document pour Excel.
Globals.Sheet1.Controls.Remove("ChartSource")
Globals.Sheet1.Controls.Remove("ChartSource");
Vous ne pouvez pas supprimer des contrôles statiques au moment de l'exécution. Si vous essayez d'utiliser la méthode Delete ou Remove pour supprimer un contrôle statique, une CannotRemoveControlException sera levée.
Notes
Ne supprimez pas les contrôles par programmation dans le gestionnaire d'événements Shutdown du document. Les éléments d'interface du document ne sont plus disponibles lorsque l'événement Shutdown est déclenché. Pour supprimer les contrôles avant la fermeture du document, ajoutez votre code au gestionnaire d'événements pour un autre événement, tel que Document.BeforeClose ou Document.BeforeSave pour Word, ou Workbook.BeforeClose ou Workbook.BeforeSave pour Excel.
Ajout de contrôles hôtes à des documents
Lorsque vous ajoutez par programmation des contrôles hôtes aux documents, vous devez fournir un nom qui identifie le contrôle de façon unique, de même que spécifier l'emplacement du contrôle sur le document. Pour obtenir des instructions spécifiques, consultez les rubriques suivantes :
Comment : ajouter des contrôles ListObject aux feuilles de calcul
Comment : ajouter des contrôles NamedRange aux feuilles de calcul
Comment : ajouter des contrôles Chart aux feuilles de calcul
Comment : ajouter des contrôles de contenu à des documents Word
Comment : ajouter des contrôles Bookmark à des documents Word
Pour plus d'informations sur les contrôles hôtes, consultez Vue d'ensemble des éléments hôtes et des contrôles hôtes.
Lorsqu'un document est enregistré puis fermé, tous les contrôles hôtes créés dynamiquement sont déconnectés de leurs événements et perdent leur fonctionnalité de liaison de données. Vous pouvez ajouter du code à votre solution pour recréer les contrôles hôtes à la réouverture du document. Pour plus d'informations, consultez Rendre des contrôles dynamiques persistants dans des documents Office.
Notes
Les méthodes d'assistance ne sont pas fournies pour les contrôles hôtes suivants, car ces derniers ne peuvent pas être ajoutés par programmation aux documents : XmlMappedRange, XMLNode et XMLNodes.
Ajout de contrôles Windows Forms à des documents
Lorsque vous ajoutez par programmation un contrôle Windows Forms à un document, vous devez préciser l'emplacement du contrôle et un nom qui l'identifie de façon unique. Visual Studio Tools pour Office Runtime fournit des méthodes d'assistance pour chaque contrôle. Ces méthodes sont surchargées afin que vous puissiez passer une plage ou les coordonnées spécifiques de l'emplacement du contrôle. Pour obtenir des instructions spécifiques, consultez Comment : ajouter des contrôles Windows Forms à des documents Office.
Lorsqu'un document est enregistré, puis fermé, tous les contrôles Windows Forms créés dynamiquement sont supprimés du document. Vous pouvez ajouter du code à votre solution pour recréer les contrôles à la réouverture du document. Si vous créez des contrôles Windows Forms dynamiques en utilisant un complément d'application, les wrappers ActiveX des contrôles sont laissés dans le document. Pour plus d'informations, consultez Rendre des contrôles dynamiques persistants dans des documents Office.
Notes
Les contrôles Windows Forms ne peuvent pas être ajoutés par programmation à des documents protégés. Si vous déprotégez par programmation le document Word ou la feuille de calcul Excel pour ajouter un contrôle, vous devez écrire du code supplémentaire pour supprimer le wrapper ActiveX du contrôle lorsque le document est fermé. Le wrapper ActiveX du contrôle n'est pas supprimé automatiquement des documents protégés.
Ajout de contrôles personnalisés
Si vous voulez ajouter un System.Windows.Forms.Control qui n'est pas pris en charge par les méthodes d'assistance disponibles (contrôle utilisateur personnalisé, par exemple), utilisez les méthodes suivantes :
Pour Excel, utilisez l'une des méthodes AddControl() d'un objet Microsoft.Office.Tools.Excel.ControlCollection.
Pour Word, utilisez l'une des méthodes AddControl() d'un objet Microsoft.Office.Tools.Word.ControlCollection.
Pour ajouter le contrôle, passez le System.Windows.Forms.Control, son emplacement et un nom qui l'identifie de manière unique à la méthode AddControl. La méthode AddControl retourne un objet qui définit la manière dont le contrôle interagit avec la feuille de calcul ou le document. Le type de l'objet retourné dépend du projet :
Pour les projets qui ciblent le .NET Framework 4, cette méthode retourne un Microsoft.Office.Tools.Excel.ControlSite(pour Excel) ou un objet Microsoft.Office.Tools.Word.ControlSite (pour Word).
Pour les projets qui ciblent le .NET Framework 3.5, cette méthode retourne un objet Microsoft.Office.Tools.Excel.OLEObject (pour Excel) ou Microsoft.Office.Tools.Word.OLEControl (pour Word).
L'exemple de code suivant montre comment utiliser la méthode AddControl(Control, Range, String) pour ajouter dynamiquement un contrôle utilisateur personnalisé à une feuille de calcul dans un projet Excel au niveau du document qui cible le .NET Framework 4. Dans cet exemple, le contrôle utilisateur se nomme UserControl1 et le Rangese nomme range1. Pour utiliser cet exemple de code, exécutez-le dans votre projet à partir d'une classe Sheetn.
Dim customControl As New UserControl1()
Dim dynamicControl As Microsoft.Office.Tools.Excel.ControlSite = _
Me.Controls.AddControl(customControl, range1, "dynamic")
UserControl1 customControl = new UserControl1();
Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
this.Controls.AddControl(customControl, range1, "dynamic");
Utilisation de membres de contrôles personnalisés
Lorsque vous avez utilisé l'une des méthodes AddControl pour ajouter un contrôle à une feuille de calcul ou un document, vous disposez alors de deux objets de contrôle différents :
Le System.Windows.Forms.Control qui représente le contrôle personnalisé.
Objet ControlSite, OLEObject ou OLEControl qui représente le contrôle après son ajout à la feuille de calcul ou au document.
Ces contrôles partagent de nombreuses propriétés et méthodes. Il est important d'accéder à ces membres via le contrôle approprié :
Pour accéder aux membres qui appartiennent uniquement au contrôle personnalisé, utilisez System.Windows.Forms.Control.
Pour accéder aux membres partagés par les contrôles, utilisez l'objet ControlSite, OLEObject ou OLEControl.
Si vous accédez à un membre partagé du System.Windows.Forms.Control, il peut échouer sans avertissement ni notification ou produire des résultats non valides. Utilisez toujours les méthodes ou propriétés de l'objet ControlSite, OLEObject ou OLEControl à moins que la méthode ou propriété nécessaire ne soit pas disponible ; dans ce cas, vous pouvez référencer System.Windows.Forms.Control.
Par exemple, la classe ControlSite et la classe System.Windows.Forms.Control possèdent une propriété Top. Pour obtenir ou définir la distance entre le haut du contrôle et le haut du document, utilisez la propriété Top de ControlSite, et non la propriété Top de System.Windows.Forms.Control.
' Property is set in relation to the document.
dynamicControl.Top = 100
' Property is set in relation to the container control.
customControl.Top = 100
// Property is set in relation to the document.
dynamicControl.Top = 100;
// Property is set in relation to the container control.
customControl.Top = 100;
Voir aussi
Tâches
Comment : ajouter des contrôles ListObject aux feuilles de calcul
Comment : ajouter des contrôles NamedRange aux feuilles de calcul
Comment : ajouter des contrôles Chart aux feuilles de calcul
Comment : ajouter des contrôles de contenu à des documents Word
Comment : ajouter des contrôles Bookmark à des documents Word
Comment : ajouter des contrôles Windows Forms à des documents Office
Concepts
Rendre des contrôles dynamiques persistants dans des documents Office
Méthodes d'assistance pour les contrôles hôtes
Méthodes d'assistance pour les contrôles Windows Forms
Vue d'ensemble des contrôles Windows Forms dans les documents Office