Partager via

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

  • Article

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

  • Excel 2003

  • Excel 2007

  • Word 2003

  • Word 2007

Projets au niveau de l'application

  • Excel 2007

  • Word 2007

Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet.

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. Dans Visual Studio 2008 Service Pack 1 (SP1), vous pouvez ajouter des contrôles dynamiques à des documents et des classeurs en utilisant des compléments d'application.

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

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 classes Microsoft.Office.Tools.Excel.ControlCollection et Microsoft.Office.Tools.Word.ControlCollection.

La manière dont vous accédez aux collections de contrôle dépend du type de projet que vous développez :

Ajout de contrôles

Les classes 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 à des documents et des 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 parcourir 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 programme 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 programme 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 programme aux documents : XmlMappedRange, XMLNode et XMLNodes.

Ajout de contrôles Windows Forms à des documents

Lorsque vous ajoutez par programme 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 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.

Remarque :

Les contrôles Windows Forms ne peuvent pas être ajoutés par programme à des documents protégés. Si vous déprotégez par programme 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 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. Pour Excel, cette méthode retourne un OLEObject. Pour Word, cette méthode retourne un OLEControl. Ces objets définissent la manière dont le contrôle interagit avec la feuille de calcul ou le document.

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 cet exemple, le contrôle utilisateur est nommé UserControl1 et le contrôle Rangerange1. Cet exemple suppose qu'il est exécuté à partir d'une des classes Sheetn dans un projet au niveau du document pour Excel.

Dim customControl As New UserControl1()

Dim dynamicControl As Microsoft.Office.Tools.Excel.OLEObject = _
    Me.Controls.AddControl(customControl, range1, "dynamic")

UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.OLEObject 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 :

Ces contrôles partagent de nombreuses propriétés et méthodes. Il est important que vous accédiez à ces méthodes et à ces propriétés en utilisant le contrôle approprié :

  • Pour accéder aux propriétés et méthodes qui appartiennent uniquement au contrôle personnalisé, utilisez le System.Windows.Forms.Control.

  • Pour accéder aux propriétés et méthodes partagées par les contrôles, utilisez OLEObject ou OLEControl.

Si vous accédez à une propriété ou méthode partagée à partir du System.Windows.Forms.Control, l'opération risque d'échouer sans avertissement ou notification ou de produire des résultats non valides. Utilisez toujours les méthodes ou propriétés de OLEObject ou OLEControl, sauf si la méthode ou la propriété requise n'est pas disponible ; ce n'est que dans ce cas que vous devez référencer le System.Windows.Forms.Control.

Par exemple, la classe OLEObject 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 OLEObject, 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

Référence

ControlCollection.AddControl

ControlCollection.AddControl

ControlCollection.Remove

ControlCollection.Remove

Autres ressources

Contrôles sur des documents Office

Contrôles hôtes Excel

Contrôles hôtes Word

Historique des modifications

Date

Historique

Raison

Juillet 2008

Ajout d'informations relatives à la procédure d'ajout de contrôles aux documents à l'aide de compléments d'application.

Modifications de fonctionnalités dans le SP1.