Ajout de contrôles à des documents Office au moment de l'exécution

Article
03/04/2013

Vous pouvez ajouter des contrôles à un classeur de document Word et Microsoft Office Excel au moment de l'exécution.Vous pouvez également les supprimer de l'exécution.Les contrôles que vous ajoutez ou supprimez 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 2013, Excel 2010, Word 2013 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.

Cette rubrique décrit les opérations suivantes :

Gestion de contrôles au moment de l'exécution en utilisant des collections de contrôle.
Ajouter des contrôles hôtes à des documents.
Ajouter des contrôles Windows Forms à des documents.

lien vers la vidéo 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 d' Microsoft.Office.Tools.Excel.ControlCollection et d' Microsoft.Office.Tools.Word.ControlCollection incluent les méthodes d'assistance que vous pouvez utiliser pour ajouter des contrôles hôtes et Windows Forms communs aux documents et aux feuilles de calcul.Chaque nom de méthode a le format Addclasse de contrôle, où classe de contrôle est le nom de classe du contrôle à ajouter.Par exemple, pour ajouter un contrôle NamedRange à votre document, utilisez la méthode AddNamedRange.

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.

[!REMARQUE]

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 :

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.

[!REMARQUE]

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 des coordonnées spécifiques pour l'emplacement du contrôle.

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.

[!REMARQUE]

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 souhaitez ajouter System.Windows.Forms.Control qui n'est pas pris en charge par les méthodes d'assistance disponibles, comme un contrôle utilisateur personnalisé, 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.La méthode d' AddControl retourne Microsoft.Office.Tools.Excel.ControlSite (pour Excel) ou un objet d' Microsoft.Office.Tools.Word.ControlSite (pour Word).

L'exemple de code suivant montre comment utiliser la méthode d' AddControl(Control, Range, String) pour ajouter dynamiquement un contrôle utilisateur personnalisé à une feuille de calcul dans un projet Excel au niveau de le document.Dans cet exemple, le contrôle utilisateur se nomme UserControl1, et Range est nommé range1. Pour utiliser cet exemple, exécutez -le à partir d'une classe n d' Sheetdans le projet.

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;

Partager via

Ajout de contrôles à des documents Office au moment de l'exécution

Gestion de contrôles au moment de l'exécution à l'aide des collections de contrôle

Ajout de contrôles

Accès aux contrôles et suppression

Ajout de contrôles hôtes à des documents

Ajout de contrôles Windows Forms à des documents

Ajout de contrôles personnalisés

Utilisation de membres de contrôles personnalisés

Voir aussi

Tâches

Concepts

Autres ressources

Ressources supplémentaires