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

  • Article

Les éléments hôtes 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 hôtes et les contrôles hôtes apparentent l’interaction avec les modèles objet Microsoft Office Word et Microsoft Office Excel, qui sont basés sur COM, davantage à l’interaction entre des 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 aux projets de complément VSTO pour Excel et Word. Pour plus d’informations, consultez Fonctionnalités disponibles par application Office lication et le type de projet.

Éléments hôtes

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

  • Document

  • Workbook

  • Worksheet

  • ChartSheet

    Chacun de ces types étend un objet qui existe en mode natif dans le modèle objet Word ou Excel, appelé objet Office natif. Par exemple, l’élément hôte Document étend l’objet Document , qui est défini 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 ils sont améliorés avec les fonctionnalités suivantes :

  • la capacité d’héberger des contrôles managés, y compris des contrôles hôtes et Windows Forms,

  • des modèles d’événement enrichis. Certains événements de document, de classeur et de 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.

Comprendre les éléments hôtes dans les 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 Document et Worksheet disposent de concepteurs associés qui sont la représentation visuelle du document ou de la feuille de calcul, comme 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, ainsi que pour faire glisser des contrôles sur l’aire de conception. Pour plus d’informations, consultez l’élément hôte de document et l’élément hôte de feuille de calcul.

L’élément hôte 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, ce qui vous permet de faire glisser un composant, tel qu’un DataSet, sur son aire de conception. Pour plus d’informations, consultez l’élément hôte du classeur.

Il n’est pas possible de créer par programmation des éléments hôtes dans des projets au niveau du document. Utilisez plutôt les classes ThisDocument, ThisWorkbook, ou Sheetn 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 programmatiques des éléments hôtes et des contrôles hôtes.

Comprendre les éléments hôtes dans les projets de complément VSTO

Lorsque vous créez un complément VSTO, vous n’avez pas accès à des éléments hôtes par défaut. Toutefois, vous pouvez générer les éléments hôtes Document, Workbooket Worksheet dans des compléments Word et Excel VSTO 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 Étendre les documents Word et les classeurs Excel dans les compléments VSTO 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 Range.

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

  • Contrôle graphique

  • Contrôle ListObject

  • Contrôle NamedRange

  • Contrôle XmlMappedRange

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

  • Contrôle Signet

  • Contrôles de contenu

  • Contrôle XMLNode

  • Contrôle XMLNodes

    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 des événements et des fonctionnalités de liaison de données. Par exemple, lorsque vous souhaitez capturer les événements d’un objet Range natif dans Excel, vous devez d’abord gérer l’événement de modification de la feuille de calcul. Vous devez ensuite déterminer si la modification s’est produite dans le Range. En revanche, le contrôle hôte NamedRange possède un événement Change que vous pouvez gérer directement.

    La relation entre un élément hôte et des contrôles hôtes est similaire à la relation entre les contrôles Windows Form et 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 NamedRange sur un élément hôte Worksheet . L’illustration suivante montre la relation entre les éléments hôtes et les contrôles hôtes.

    Relationship between host items and host controls

    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 les contrôles Windows Forms sur Bureau vue d’ensemble des documents.

Remarque

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

Ajouter 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, en procédant comme suit :

Contrôles d’hôte de nom

Lorsque vous faites glisser un contrôle hôte de la boîte à outils vers votre document, le contrôle est nommé automatiquement à l’aide 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 que vous remplacez son nom par System, des erreurs se produisent lorsque vous générez le projet.

Supprimer les contrôles d’hôte

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, puis en appuyant sur la touche Supprimer . 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 est levée la prochaine fois que vous essayez 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 d’un NamedRange supprime correctement le NamedRange uniquement 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 du contrôle à la méthode Remove de la propriété Controls ou Controls Pour plus d’informations, consultez Ajouter des contrôles à Bureau documents 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 Bureau exemples de développement et procédures pas à pas.

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

Programme par rapport aux événements de contrôle d’hôte

Pour étendre les objets Office, les contrôles hôtes peuvent, entre autres, ajouter des événements. Par exemple, l’objet Range dans Excel et Bookmark l’objet dans Word n’ont pas d’événements, mais le runtime Visual Studio Tools pour Office é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 en Visual Basic et de la page de propriétés d’événement en C#. Pour plus d’informations, consultez Procédure pas à pas : Programme sur les événements d’un contrôle NamedRange.

Remarque

Vous ne devez pas attribuer la valeur EnableEvents à la propriété Application de l'objet T:Microsoft.Office.Interop.Excel.Application. 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.

Contenu connexe