Partager via

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

Les éléments hôtes et les contrôles hôtes sont des types qui permettent de fournir le 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 rendent l'interaction avec les modèles d'objet de Microsoft Office Word et Microsoft Office Excel, qui sont basés sur COM, plus similaire à l'interaction avec des objets géré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 type d’application et de projet Office.

Éléments hôtes

Les éléments hôtes sont des types situés en haut des hiérarchies de modèle 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 Document hôte étend l’objet Document , qui est défini dans l’assembly d’interopérabilité principal pour Word.

    Les éléments hôtes ont 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 :

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

  • Modèles d’événements plus riches. Certains événements de document, de classeur et de 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 gérer les événements d’un document spécifique.

Comprendre les objets hôtes dans les projets de niveau document

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

Les Document éléments hôtes et Worksheet les éléments associés ont des 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, et 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 Workbook hôte ne fait pas office de conteneur pour les contrôles qui ont une interface utilisateur. Au lieu de cela, le concepteur de cet élément hôte fonctionne comme un plateau de composants, ce qui vous permet de faire glisser un composant, tel qu’un DataSet, sur la surface de conception. Pour plus d’informations, consultez l’élément hôte du classeur.

Les éléments hôtes ne peuvent pas être créés par programme dans les projets au niveau du document. Utilisez plutôt les ThisDocumentclasses , ThisWorkbookou Sheetn générées automatiquement par Visual Studio 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 des éléments d'hôte Document, Workbook et Worksheet dans les compléments VSTO pour Word et Excel à 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 d’hôte

Les contrôles hôtes étendent différents objets de l’interface utilisateur dans les modèles objet de 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 de XmlMappedRange

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

  • Contrôle de marque-page

  • Contrôles de contenu

  • Contrôle de XMLNode

  • Contrôle XMLNodes

    Les contrôles hôtes ajoutés aux documents Office se comportent comme les objets Office natifs ; Toutefois, les contrôles hôtes ont 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 natif Range 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 s’est produite dans le Range. En revanche, le NamedRange contrôle hôte dispose d'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. Tout comme vous placez un contrôle de zone de texte sur un Windows Form, vous placez un NamedRange contrôle sur un Worksheet élément hôte. L’illustration suivante montre la relation entre les éléments hôtes et les contrôles hôtes.

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

    Vous pouvez également utiliser des contrôles Windows Forms dans vos solutions Office en les ajoutant directement à l’aire de document Word et Excel. Pour plus d’informations, consultez la vue d’ensemble des contrôles Windows Forms sur les documents Office.

Note

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 de l'hôte à vos documents

Dans les projets au niveau du document, vous pouvez ajouter des contrôles hôtes à vos documents Word ou feuilles de calcul Excel au moment du design de la manière suivante :

Contrôles de l'hôte nommé

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

Note

Vous ne pouvez pas utiliser de mots réservés pour nommer les contrôles d’hôte. Par exemple, si vous ajoutez un NamedRange contrôle à une feuille de calcul et que vous remplacez le 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 le nom dans Excel pour supprimer des NamedRange contrôles.

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 la prochaine fois que vous essayez d’utiliser le contrôle dans le code, une exception est levée. La Delete méthode d’un contrôle hôte supprime uniquement les contrôles hôtes ajoutés au document au moment de l’exécution. Si vous appelez la Delete méthode d'un contrôle d'hôte créé au moment de la conception, une exception est levée.

Par exemple, la méthode Delete d’un NamedRange supprime correctement le NamedRange uniquement si celui-ci a été ajouté par programmation à la feuille de calcul, ce qu'on appelle créer dynamiquement des 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 ou à la propriété Controls ou Controls. Pour plus d’informations, consultez Ajouter des contrôles aux 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 des documents dans Word et Excel pour protéger les contrôles hôtes contre la suppression. Pour plus d’informations, consultez les exemples de développement Office et les procédures pas à pas.

Note

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

Programme contre les événements de contrôle d'hôte

L’une des façons dont les contrôles hôtes étendent les objets Office consiste à ajouter des événements. Par exemple, l’objet Range dans Excel et Bookmark l’objet 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 façon que vous accédez aux événements des contrôles sur Windows Forms : via la liste déroulante des événements dans Visual Basic et la page des propriétés d’événement en C#. Pour plus d’informations, consultez Procédure pas à pas : Programmer contre les événements d’un contrôle NamedRange.

Note

Vous ne devez pas définir la EnableEvents propriété de l’objet Application dans Excel sur false. La définition de cette propriété sur false empêche Excel de déclencher des événements, y compris les événements des contrôles hôtes.

Contenu connexe

  • Last updated on