Partager via

Ajouter des contrôles aux documents Office au moment de l’exécution

Vous pouvez ajouter des contrôles à un document Microsoft Office Word et un classeur Microsoft Office Excel au moment de l’exécution. Vous pouvez également les supprimer au moment de l’exécution. Les contrôles que vous ajoutez ou supprimez au moment de l’exécution sont appelés contrôles dynamiques.

S’applique à : Les informations contenues dans cette rubrique s’appliquent aux projets de niveau document et aux projets de complément VSTO pour Excel et Word. Pour plus d’informations, consultez Fonctionnalités disponibles par type d’application et de projet Office.

Cette rubrique décrit les éléments suivants :

Gérer les contrôles au moment de l’exécution à l’aide de collections de contrôles

Pour ajouter, obtenir ou supprimer des contrôles au moment de l'exécution, utilisez les méthodes d'assistance des objets ControlCollection et ControlCollection.

La façon dont vous accédez à ces objets dépend du type de projet que vous développez :

Ajouter des contrôles

Les types ControlCollection et ControlCollection incluent des méthodes d’assistance que vous pouvez utiliser pour ajouter des contrôles hôtes et des contrôles Windows Forms courants aux documents et feuilles de calcul. Chaque nom de méthode suit le format Addclasse de contrôle, où classe de contrôle est le nom de la classe du contrôle que vous souhaitez ajouter. Par exemple, pour ajouter un NamedRange contrôle à votre document, utilisez la AddNamedRange méthode.

L’exemple de code suivant ajoute un NamedRange à Sheet1 dans un projet au niveau du document pour Excel.

Excel.Range range1 = Globals.Sheet1.Range["A1", "D5"];
Microsoft.Office.Tools.Excel.NamedRange namedRange1 =
    Globals.Sheet1.Controls.AddNamedRange(range1, "ChartSource");

Contrôles d’accès et de suppression

Vous pouvez utiliser la Controls propriété d’un élément ou Worksheet pour parcourir parmi tous les contrôles de votre document, y compris les contrôles que vous avez ajoutés au moment de la conception. Les contrôles que vous ajoutez au moment du design sont également appelés contrôles statiques.

Vous pouvez supprimer des contrôles dynamiques en appelant la Delete méthode du contrôle ou en appelant la Remove méthode de chaque collection Controls. L’exemple de code suivant utilise la méthode Remove pour supprimer un NamedRange de Sheet1 dans un projet de niveau document pour Excel.

Globals.Sheet1.Controls.Remove("ChartSource");

Vous ne pouvez pas supprimer les 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 déclenchée.

Note

Ne supprimez pas les contrôles par programmation dans le Shutdown gestionnaire d’événements du document. Les éléments d’interface utilisateur du document ne sont plus disponibles lorsque l’événement Shutdown est déclenché. Si vous souhaitez supprimer des contrôles avant la fermeture du document, ajoutez votre code au gestionnaire d’événements pour un autre événement, tel que BeforeClose ou BeforeSave pour Word, ou BeforeClosepour BeforeSave Excel.

Ajouter des contrôles hôtes à des documents

Lorsque vous ajoutez par programme des contrôles hôtes à des documents, vous devez fournir un nom qui identifie de façon unique le contrôle et vous devez spécifier où ajouter le 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 la 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 leurs fonctionnalités de liaison de données. Vous pouvez ajouter du code à votre solution pour recréer les contrôles hôtes lorsque le document est rouvert. Pour plus d’informations, consultez Conserver les contrôles dynamiques dans les documents Office.

Note

Les méthodes d’assistance ne sont pas fournies pour les contrôles hôtes suivants, car ces contrôles ne peuvent pas être ajoutés par programme aux documents : XmlMappedRange, XMLNodeet XMLNodes.

Ajouter des contrôles Windows Forms à des documents

Lorsque vous ajoutez par programme un contrôle Windows Forms à un document, vous devez fournir l’emplacement du contrôle et un nom qui identifie de manière unique le contrôle. Le runtime Visual Studio Tools pour Office fournit des méthodes d’assistance pour chaque contrôle. Ces méthodes sont surchargées pour que vous puissiez passer un intervalle ou des coordonnées spécifiques pour l’emplacement du composant.

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 lorsque le document est rouvert. Si vous créez des contrôles Windows Forms dynamiques à l’aide d’un complément VSTO, les wrappers ActiveX pour les contrôles sont laissés dans le document. Pour plus d’informations, consultez Conserver les contrôles dynamiques dans les documents Office.

Note

Les contrôles Windows Forms ne peuvent pas être ajoutés par programme aux documents protégés. Si vous annulez la protection par programmation d’un document Word ou d’une 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 automatiquement supprimé des documents protégés.

Ajouter des contrôles personnalisés

Si vous souhaitez ajouter un Control élément qui n’est pas pris en charge par les méthodes d’assistance disponibles, telles qu’un contrôle utilisateur personnalisé, utilisez les méthodes suivantes :

  • Pour Excel, utilisez l’une AddControl des méthodes d'un objet ControlCollection.

  • Pour Word, utilisez l’une AddControl des méthodes d’un objet ControlCollection.

    Pour ajouter le contrôle, passez l’emplacement Control, un emplacement pour le contrôle et un nom qui identifie de manière unique le contrôle à la AddControl méthode. La AddControl méthode retourne un objet qui définit la façon dont le contrôle interagit avec la feuille de calcul ou le document. La AddControl méthode retourne un ControlSite (pour Excel) ou un ControlSite objet (pour Word).

    L’exemple de code suivant montre comment utiliser la AddControl méthode pour ajouter dynamiquement un contrôle utilisateur personnalisé à une feuille de calcul dans un projet Excel au niveau du document. Dans cet exemple, le contrôle utilisateur est nommé UserControl1et le Range contrôle est nommé range1. Pour utiliser cet exemple, exécutez-le à partir d’une Sheetclasse n dans le projet.

    UserControl1 customControl = new UserControl1();

Microsoft.Office.Tools.Excel.ControlSite dynamicControl =
    this.Controls.AddControl(customControl, range1, "dynamic");

Utiliser des membres de contrôles personnalisés

Après avoir utilisé l’une des méthodes pour ajouter un contrôle à une feuille de calcul ou un document, vous disposez maintenant de AddControl deux objets de contrôle différents :

  • Le Control qui représente le contrôle personnalisé.

  • L'objet ControlSite, OLEObject ou OLEControl qui représente le contrôle après avoir été ajouté à la feuille de calcul ou au document.

    De nombreuses propriétés et méthodes sont partagées entre ces contrôles. 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 le Control.

  • Pour accéder aux membres partagés par les contrôles, utilisez les objets ControlSite, OLEObject, ou OLEControl.

    Si vous accédez à un membre partagé depuis Control, cela peut échouer sans avertissement ni notification, ou produire des résultats non valides. Utilisez toujours des méthodes ou des propriétés de l'objet ControlSite, OLEObject ou OLEControl sauf si la méthode ou la propriété nécessaire n'est pas disponible ; dans ce cas, vous devez uniquement référencer le Control.

    Par exemple, la ControlSite classe et la Control classe ont une Top propriété. Pour obtenir ou définir la distance entre le haut du contrôle et le haut du document, utilisez la Top propriété du ControlSite, et non la Top propriété du Control.

    // Property is set in relation to the document.
dynamicControl.Top = 100;

// Property is set in relation to the container control.
customControl.Top = 100;

Contenu connexe

  • Last updated on