Vue d'ensemble des éléments hôtes et des contrôles hôtes

  • 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.

Les éléments hôtes et les contrôles hôtes sont des classes qui permettent de fournir le modèle de programmation pour les solutions Visual Studio Tools pour Office. Ils créent une interaction avec les modèles objet de Microsoft Office Word et de Microsoft Office Excel, basés sur COM, plus comme une interaction avec des objets managés tels que les contrôles Windows Forms.

Éléments hôtes

Les éléments hôtes sont des classes qui se trouvent en haut des hiérarchies de modèles objet dans des projets Visual Studio Tools pour Office. Visual Studio Tools pour Office définit les éléments hôtes suivants pour des solutions Word et Excel :

Chacune de ces classes étend une classe qui existe en mode natif dans le modèle objet Word ou Excel (appelé objet Office natif). Par exemple, l'élément hôte Microsoft.Office.Tools.Word.Document étend la classe Microsoft.Office.Interop.Word.Document, qui est définie dans l'assembly PIA (Primary Interop Assembly) pour Word.

Les éléments hôtes possèdent généralement les mêmes fonctionnalités de base que les objets Office correspondants, mais sont améliorés avec les fonctionnalités suivantes :

  • Hébergement des contrôles managés, y compris les contrôles hôtes et Windows Forms.

  • Modèles d'événement plus riches. Certains événements de document, classeur et feuille de calcul dans les modèles objet Word et Excel natifs sont déclenchés uniquement au niveau de l'application. Les éléments hôtes fournissent ces événements au niveau du document, afin qu'il soit plus facile de les gérer pour un document spécifique.

Fonctionnement d'éléments hôtes dans des projets au niveau du document

Dans les projets au niveau du document, les éléments hôtes fournissent un point d'entrée pour votre code et disposent de concepteurs qui vous aident à développer votre solution.

Les éléments hôtes Microsoft.Office.Tools.Word.Document et Microsoft.Office.Tools.Excel.Worksheet possèdent des concepteurs qui constituent la représentation visuelle du document ou de la feuille de calcul, à l'instar d'un concepteur Windows Forms. Vous pouvez utiliser ce concepteur pour modifier le contenu du document ou de la feuille de calcul directement dans Word ou Excel et faire glisser des contrôles sur l'aire de conception. Pour plus d'informations, consultez Élément hôte de document et Élément hôte de feuille de calcul.

L'élément hôte Microsoft.Office.Tools.Excel.Workbook n'agit pas comme un conteneur pour les contrôles qui possèdent une interface utilisateur. À la place, le concepteur de cet élément hôte fonctionne comme une barre d'état des composants, qui vous permet de faire glisser un composant, tel que DataSet sur son aire de conception. Pour plus d'informations, consultez Élément hôte de classeur.

Les éléments hôtes ne peuvent pas être créés par programme dans des projets au niveau du document. À la place, utilisez les classes ThisDocument, ThisWorkbook ou Sheetn que Visual Studio Tools pour Office génère automatiquement dans votre projet au moment du design. Ces classes générées dérivent des classes d'élément hôte et fournissent un point d'entrée pour votre code. Pour plus d'informations, consultez Limitations de programmation des éléments hôtes et des contrôles hôtes.

Fonctionnement d'éléments hôtes dans des projets au niveau de l'application

Lorsque vous créez un complément d'application, vous ne disposez pas d'un accès par défaut à quelque élément hôte que ce soit. Toutefois, à compter de Visual Studio 2008 Service Pack 1 (SP1), vous pouvez générer des éléments hôtes Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook et Microsoft.Office.Tools.Excel.Worksheet dans des compléments au moment de l'exécution.

Après avoir généré un élément hôte, vous pouvez effectuer des tâches telles que l'ajout de contrôles à des documents et la création de balises actives qui sont reconnues dans un document spécifique. Pour plus d'informations, consultez Extension de documents Word et de classeurs Excel dans des compléments d'application au moment de l'exécution..

Contrôles hôtes

Les contrôles hôtes étendent différents objets interface utilisateur dans les modèles objet Word et Excel, tels que les objets Microsoft.Office.Interop.Word.ContentControl et Microsoft.Office.Interop.Excel.Range.

Les contrôles hôtes suivants sont disponibles pour les projets Excel :

Les contrôles hôtes suivants sont disponibles pour les projets Word :

Les contrôles hôtes qui sont ajoutés aux documents Office se comportent comme les objets Office natifs ; toutefois, les contrôles hôtes possèdent des fonctionnalités supplémentaires, notamment les événements et les fonctionnalités de liaison de données. Par exemple, lorsque vous souhaitez capturer les événements d'un objet Microsoft.Office.Interop.Excel.Range natif dans Excel, vous devez d'abord gérer l'événement de modification de la feuille de calcul. Ensuite, vous devez déterminer si la modification a eu lieu dans la Microsoft.Office.Interop.Excel.Range. En revanche, le contrôle hôte Microsoft.Office.Tools.Excel.NamedRange possède un événement Change que vous pouvez gérer directement.

La relation entre un élément hôte et les contrôles hôtes est très semblable à la relation entre un Windows Form et les contrôles Windows Forms. De la même manière que vous placez un contrôle de zone de texte sur un Windows Form, vous placez un contrôle Microsoft.Office.Tools.Excel.NamedRange sur un élément hôte Microsoft.Office.Tools.Excel.Worksheet. L'illustration suivante montre la relation entre les éléments hôtes et les contrôles hôtes.

En outre, Visual Studio Tools pour Office permet d'utiliser des contrôles Windows Forms dans vos solutions Office en les ajoutant directement à la surface de document Word et Excel. Pour plus d'informations, consultez Vue d'ensemble des contrôles Windows Forms dans les documents Office.

Remarque :

L'ajout des contrôles hôtes ou des contrôles Windows Forms à un sous-document Word n'est pas pris en charge.

Ajout des contrôles hôtes à vos documents

Dans les projets au niveau du document, vous pouvez ajouter des contrôles hôtes à vos documents Word ou à vos feuilles de calcul Excel au moment du design, selon les méthodes suivantes :

  • Ajoutez des contrôles hôtes à votre document au moment du design de la même manière que vous ajouteriez un objet natif.

  • Faites glisser des contrôles hôtes de la boîte à outils vers vos documents et feuilles de calcul. Les contrôles hôtes Excel sont disponibles sous l'onglet Contrôles Excel des projets Excel, et les contrôles hôtes Word sous l'onglet Contrôles Word des projets Word.

  • Faites glisser des contrôles hôtes de la fenêtre Sources de données vers vos documents et vos feuilles de calcul. Vous pouvez ainsi ajouter des contrôles déjà liés à des données. Pour plus d'informations, consultez Liaison de données aux contrôles.

À compter de SP1, dans les projets au niveau du document et au niveau de l'application, vous pouvez aussi ajouter certains contrôles hôtes aux documents au moment de l'exécution. Pour plus d'informations, consultez Ajout de contrôles à des documents Office au moment de l'exécution.

Pour plus d'informations sur la manière d'ajouter des contrôles hôtes à des documents, consultez les rubriques suivantes :

Attribution de noms aux contrôles hôtes

Lorsque vous faites glisser un contrôle hôte de la boîte à outils vers votre document, le contrôle est nommé automatiquement en fonction du type de contrôle et d'un nombre incrémentiel à la fin. Par exemple, les signets sont nommés bookmark1, bookmark2, et ainsi de suite. Si vous utilisez les fonctionnalités natives de Word ou Excel pour ajouter le contrôle, vous pouvez lui attribuer un nom spécifique au moment de sa création. Vous pouvez également renommer vos contrôles en modifiant la valeur de la propriété Name dans la fenêtre Propriétés.

Remarque :

Vous ne pouvez pas utiliser de mots réservés pour nommer des contrôles hôtes. Par exemple, si vous ajoutez un contrôle NamedRange à une feuille de calcul et remplacez son nom par Système, des erreurs se produisent lorsque vous générez le projet.

Suppression de contrôles hôtes

Dans les projets au niveau du document, vous pouvez supprimer des contrôles hôtes au moment du design en sélectionnant le contrôle dans la feuille de calcul Excel ou le document Word et en appuyant sur la touche Suppr. Toutefois, vous devez utiliser la boîte de dialogue Définir un nom dans Excel pour supprimer les contrôles NamedRange. Pour plus d'informations, consultez Comment : supprimer des contrôles NamedRange au moment du design.

Si vous ajoutez un contrôle hôte à un document au moment du design, vous ne devez pas le supprimer par programme au moment de l'exécution, car sinon une exception sera levée la prochaine fois que vous essaierez d'utiliser le contrôle dans le code. La méthode Delete d'un contrôle hôte supprime uniquement les contrôles hôtes qui sont ajoutés au document au moment de l'exécution. Si vous appelez la méthode Delete d'un contrôle hôte qui a été créé au moment du design, une exception est levée.

Par exemple, la méthode Delete de NamedRange supprime uniquement NamedRange correctement s'il a été ajouté par programme à la feuille de calcul, ce qui correspond à la création dynamique de contrôles hôtes. Les contrôles hôtes créés dynamiquement peuvent également être supprimés en passant le nom de contrôle à la méthode Remove de la propriété Worksheet.Controls ou Document.Controls. Pour plus d'informations, consultez Ajout de contrôles à des documents Office au moment de l'exécution.

Si les utilisateurs finaux suppriment un contrôle hôte du document au moment de l'exécution, la solution peut échouer de manière inattendue. Vous pouvez utiliser les fonctionnalités de protection de document dans Word et Excel pour empêcher la suppression des contrôles hôtes. Pour plus d'informations, consultez Techniques de protection des documents Word, exemple et Techniques de protection des documents Excel, exemple.

Remarque :

Ne supprimez pas les contrôles par programme lorsque le gestionnaire d'événements Shutdown du document ou de la feuille de calcul est actif. Les éléments d'interface utilisateur ne sont plus disponibles lorsque l'événement Shutdown se produit. Pour supprimer les contrôles avant la fermeture de l'application, ajoutez votre code à un autre gestionnaire d'événements tel que BeforeClose ou BeforeSave.

Programmation d'événements de contrôle hôte

Pour étendre les objets Office, les contrôles hôtes peuvent, entre autres, ajouter des événements. Par exemple, l'objet Microsoft.Office.Interop.Excel.Range dans Excel et l'objet Microsoft.Office.Interop.Word.Bookmark dans Word n'ont pas d'événements, mais Visual Studio Tools pour Office étend ces objets en leur ajoutant des événements programmables. Vous pouvez accéder à ces événements et les coder de la même manière que vous accédez aux événements des contrôles sur les Windows Forms : à l'aide de la liste déroulante d'événements dans Visual Basic et de la page de propriétés d'événement en C#. Pour plus d'informations, consultez Procédure pas à pas : programmation d'événements d'un contrôle NamedRange.

Remarque :

Vous ne devez pas attribuer la valeur false à la propriété EnableEvents de l'objet Application dans Excel. Si cette propriété a la valeur false, Excel ne peut pas déclencher d'événements, y compris les événements de contrôles hôtes.

Voir aussi

Concepts

Contrôles de contenu

Liaison de données aux contrôles

Limitations de programmation des éléments hôtes et des contrôles hôtes

Autres ressources

Contrôles hôtes Word

Contrôles hôtes Excel

Contrôles sur des documents Office

Historique des modifications

Date

Historique

Raison

Juillet 2008

Ajout d'informations relatives à l'utilisation d'éléments hôtes et de contrôles hôtes dans des compléments d'application.

Modifications de fonctionnalités dans le SP1.