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

Article
03/04/2013

Les éléments et les contrôles hôtes sont des types qui fournissent un modèle de programmation pour les solutions Office créées à l'aide des outils de développement Office dans Visual Studio.Les éléments et les contrôles hôtes rendent l'interaction entre modèles objets Microsoft Office Word et Microsoft Office Excel basés sur COM, similaire à l'interaction entre objets managés tels que les contrôles Windows Forms.

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.

Éléments hôtes

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

Chacun de ces types étendent un objet qui existe en mode natif dans Word ou le modèle objet Excel, appelé un objet Office natif.Par exemple, l'élément hôte Microsoft.Office.Tools.Word.Document étend l'objet Microsoft.Office.Interop.Word.Document, défini dans l'assembly PIA 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 objets 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.Excel.Worksheet et Microsoft.Office.Tools.Word.Document ont associé des concepteurs, qui sont la représentation visuelle du document ou de la feuille de calcul, comme des concepteurs 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 programmation dans des projets au niveau du document.Utilisez plutôt les classes ThisDocument, ThisWorkbook ou nSheet que Visual Studio génère automatiquement dans votre projet au moment du design.Ces classes générées dérivent des éléments hôtes 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, vous pouvez générer les éléments hôtes Microsoft.Office.Tools.Word.Document, Microsoft.Office.Tools.Excel.Workbook et Microsoft.Office.Tools.Excel.Worksheet dans des compléments Word et Excel 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.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.

Relation entre éléments hôtes et contrôles hôtes

Vous pouvez également utiliser des contrôles Windows Forms dans vos solutions Office en les ajoutant directement à la surface du 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 dans les solutions Office.

Dans les projets au niveau du document et au niveau de l'application, vous pouvez également ajouter des 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 de le document, vous pouvez supprimer des contrôles hôtes au moment de le design en sélectionnant le contrôle dans la feuille de calcul Excel ou un 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.

Si vous ajoutez un contrôle hôte à un document au moment du design, vous ne devez pas le supprimer par programmation 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 programmation à 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 Exemples et procédures pas à pas relatifs au développement Office.

[!REMARQUE]

Ne supprimez pas les contrôles par programmation 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 Runtime étend ces objets en 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.