Éléments hôtes et la vue d’ensemble des contrôles hôtesHost items and host controls overview

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.Host items and host controls are types that help provide the programming model for Office solutions that are created by using the Office development tools in 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.Host items and host controls make interacting with the object models of Microsoft Office Word and Microsoft Office Excel, which are based on COM, more like interacting with managed objects such as Windows Forms controls.

S’applique à : les informations contenues dans cette rubrique s’applique au document-projets et ajouter de VSTO de niveau-dans les projets Word et Excel.Applies to: The information in this topic applies to document-level projects and VSTO Add-in projects for Excel and Word. Pour plus d’informations, consultez fonctionnalités disponibles par type d’application et de projet Office.For more information, see Features available by Office application and project type.

Éléments hôtesHost items

Les éléments hôtes sont des types qui se trouvent en haut des hiérarchies de modèles objet dans les projets Office.Host items are types that are at the top of object model hierarchies in Office projects. Visual Studio Tools pour Office RuntimeVisual Studio Tools for Office runtime définit les éléments hôtes suivants pour les solutions Word et Excel :The Visual Studio Tools pour Office RuntimeVisual Studio Tools for Office runtime defines the following host items for Word and Excel solutions:

  • 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.Each of these types extends an object that exists natively in the Word or Excel object model, called a native Office object. 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.For example, the Document host item extends the Document object, which is defined in the primary interop assembly for 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 :Host items generally have the same base functionality as the corresponding Office objects, but are enhanced with the following features:

  • la capacité d’héberger des contrôles managés, y compris des contrôles hôtes et Windows Forms,The ability to host managed controls, including host controls and Windows Forms controls.

  • des modèles d’événement enrichis.Richer event models. 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.Some document, workbook, and worksheet events in the native Word and Excel object models are raised only at the application level. 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.Host items provide these events at the document level, so that it is easier to handle the events for a specific document.

Comprendre les éléments hôtes dans les projets au niveau du documentUnderstand host items in document-level projects

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.In document-level projects, host items provide an entry point for your code, and they have designers that help you develop your 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.The Document and Worksheet host items have associated designers that are the visual representation of the document or worksheet, like a Windows Forms designer. 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.You can use this designer to modify the content of the document or worksheet directly in Word or Excel, and to drag controls onto the design surface. Pour plus d’informations, consultez élément hôte de Document et élément hôte de feuille de calcul.For more information, see Document host item and Worksheet host item.

L’élément hôte Workbook n’agit pas comme un conteneur pour les contrôles qui possèdent une interface utilisateur.The Workbook host item does not act as a container for controls that have a user interface. À 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.Instead, the designer for this host item functions as a component tray, which enables you to drag a component, such as a DataSet, onto its design surface. Pour plus d’informations, consultez élément hôte de classeur.For more information, see Workbook host item.

Il n’est pas possible de créer par programmation des éléments hôtes dans des projets au niveau du document.Host items cannot be created programmatically in document-level projects. Utilisez plutôt les classes ThisDocument, ThisWorkbook, ou Sheetn que Visual Studio génère automatiquement dans votre projet au moment du design.Instead, use the ThisDocument, ThisWorkbook, or Sheetn classes that Visual Studio automatically generates in your project at design time. Ces classes générées dérivent des éléments hôtes et fournissent un point d’entrée pour votre code.These generated classes derive from the host items, and they provide an entry point for your code. Pour plus d’informations, consultez limitations de programmation des éléments hôtes et contrôles hôtes.For more information, see Programmatic limitations of host items and host controls.

Comprendre les éléments hôtes dans les projets de complément VSTOUnderstand host items in VSTO Add-in projects

Lorsque vous créez un complément, VSTO, vous n’avez pas les accès à tous les éléments hôte par défaut.When you create a VSTO Add-in, you do not have access to any host items by default. Toutefois, vous pouvez générer Document, Workbook, et Worksheet héberger les éléments dans Word et Excel VSTO Add-ins lors de l’exécution.However, you can generate Document, Workbook, and Worksheet host items in Word and Excel VSTO Add-ins at runtime.

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.After you generate a host item, you can perform tasks such as adding controls to documents. Pour plus d’informations, consultez documents Word d’étendre et classeurs Excel dans des Compléments VSTO lors de l’exécution.For more information, see Extend Word documents and Excel workbooks in VSTO Add-ins at runtime.

Contrôles hôtesHost controls

Contrôles hôtes étendent différents objets interface utilisateur dans les modèles objet Word et Excel, tels que Microsoft.Office.Interop.Word.ContentControl et Range objets.Host controls extend various user interface (UI) objects in the Word and Excel object models, such as Microsoft.Office.Interop.Word.ContentControl and Range objects.

Les contrôles hôtes suivants sont disponibles pour les projets Excel :The following host controls are available for Excel projects:

  • Contrôle de graphiqueChart control

  • ListObject (contrôle)ListObject control

  • NamedRange (contrôle)NamedRange control

  • XmlMappedRange, contrôleXmlMappedRange control

    Les contrôles hôtes suivants sont disponibles pour les projets Word :The following host controls are available for Word projects:

  • Bookmark (contrôle)Bookmark control

  • Contrôles de contenuContent controls

  • XMLNode, contrôleXMLNode control

  • XMLNodes, contrôleXMLNodes control

    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.Host controls that are added to Office documents behave like the native Office objects; however, host controls have additional functionality, including events and data-binding capabilities. 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.For example, when you want to capture the events of a native Range object in Excel, you must first handle the change event of the worksheet. Vous devez ensuite déterminer si la modification s’est produite dans le Range.Then you must determine whether the change occurred within the Range. En revanche, le contrôle hôte NamedRange possède un événement Change que vous pouvez gérer directement.In contrast, the NamedRange host control has a Change event that you can handle directly.

    La relation entre un élément hôte et des contrôles hôtes est similaire à la relation entre un contrôle Windows Form et Windows Forms.The relationship between a host item and host controls is similar to the relationship between a Windows Form and Windows Forms controls. 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 .Just as you would place a text box control on a Windows Form, you place a NamedRange control on a Worksheet host item. L’illustration suivante montre la relation entre les éléments hôtes et les contrôles hôtes.The following illustration shows the relationship between host items and host controls.

    Relation entre éléments hôtes et contrôles hôtesRelationship 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.You can also use Windows Forms controls in your Office solutions by adding them directly to the Word and Excel document surface. Pour plus d’informations, consultez des contrôles de Windows Forms dans les documents Office.For more information, see Windows Forms controls on Office documents overview.

Note

L’ajout de contrôles hôtes ou de contrôles Windows Forms à un sous-document Word n’est pas pris en charge.Adding host controls or Windows Forms controls to a Word subdocument is not supported.

Ajouter des contrôles hôtes à vos documentsAdd host controls to your 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 :In document-level projects, you can add host controls to your Word documents or Excel worksheets at design time in the following ways:

Nommer des contrôles hôtesName host controls

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.When you drag a host control from the Toolbox to your document, the control is automatically named using the control type with an incremental number at the end. Par exemple, les signets sont nommés bookmark1, bookmark2, et ainsi de suite.For example, bookmarks are named bookmark1, bookmark2, and so on. 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.If you use the native functionality of Word or Excel to add the control, you can give it a specific name at the time that you create it. Vous pouvez également renommer vos contrôles en modifiant la valeur de la propriété Name dans la fenêtre Propriétés .You can also rename your controls by changing the value of the Name property in the Properties window.

Note

Vous ne pouvez pas utiliser de mots réservés pour nommer des contrôles hôtes.You cannot use reserved words to name host controls. 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.For example, if you add a NamedRange control to a worksheet and change the name to System, errors occur when you build the project.

Supprimer des contrôles hôtesDelete host controls

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 un document Word et en appuyant sur la supprimer clé.In document-level projects, you can delete host controls at design time by selecting the control on the Excel worksheet or Word document and pressing the Delete key. Toutefois, vous devez utiliser la boîte de dialogue Définir un nom dans Excel pour supprimer les contrôles NamedRange .However, you must use the Define Name dialog box in Excel to delete NamedRange controls.

Si vous ajoutez un contrôle hôte à un document au moment du design, vous ne devez pas le supprimer par programmation lors de l’exécution, car la prochaine fois que vous essayez d’utiliser le contrôle dans le code, une exception est levée.If you add a host control to a document at design time, you should not remove it programmatically at runtime because the next time you try to use the control in code, an exception is thrown. Le Delete méthode d’un contrôle hôte supprime uniquement les contrôles hôtes qui sont ajoutés au document lors de l’exécution.The Delete method of a host control only removes host controls that are added to the document at runtime. 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.If you call the Delete method of a host control that was created at design time, an exception is thrown.

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.For example, the Delete method of a NamedRange only successfully deletes the NamedRange if it was programmatically added to the worksheet, which is known as creating host controls dynamically. 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 ControlsDynamically created host controls can also be removed by passing the control name to the Remove method of the Controls or Controls property. Pour plus d’informations, consultez ajouter des contrôles aux documents Office au moment de l’exécution.For more information, see Add controls to Office documents at runtime.

Si les utilisateurs finaux suppriment un contrôle hôte à partir du document lors de l’exécution, la solution peut échouer de façon inattendue.If end users delete a host control from the document at runtime, the solution might fail in unexpected ways. Vous pouvez utiliser les fonctionnalités de protection de document dans Word et Excel pour empêcher la suppression des contrôles hôtes.You can use the document protection features in Word and Excel to protect the host controls from being deleted. Pour plus d’informations, consultez exemples de développement Office et des procédures pas à pas.For more information, see Office development samples and walkthroughs.

Note

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.Do not programmatically remove controls during the Shutdown event handler of the document or worksheet. Les éléments d’interface utilisateur ne sont plus disponibles quand l’événement Shutdown se produit.The UI elements are no longer available when the Shutdown event occurs. 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.If you want to remove controls before the application closes, add your code to another event handler such as BeforeClose or BeforeSave.

Programmer des événements de contrôle hôteProgram against host control events

Pour étendre les objets Office, les contrôles hôtes peuvent, entre autres, ajouter des événements.One way that host controls extend Office objects is by adding events. Par exemple, l’objet Range dans Excel et l’objet Bookmark dans Word n’ont pas d’événements, mais Visual Studio Tools pour Office RuntimeVisual Studio Tools for Office runtime étend ces objets en ajoutant des événements programmables.For example, the Range object in Excel and Bookmark object in Word do not have events, but the Visual Studio Tools pour Office RuntimeVisual Studio Tools for Office runtime extends these objects by adding programmable events. 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#.You can access and code against these events the same way you access events of controls on Windows Forms: through the event drop-down list in Visual Basic and the event property page in C#. Pour plus d’informations, consultez procédure pas à pas : programmer des événements d’un contrôle NamedRange.For more information, see Walkthrough: Program against events of a NamedRange control.

Note

Vous ne devez pas attribuer la valeur EnableEvents à la propriété Application de l'objet T:Microsoft.Office.Interop.Excel.Application.You should not set the EnableEvents property of the Application object in Excel to false. 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.Setting this property to false prevents Excel from raising any events, including the events of host controls.

Voir aussiSee also

Limitations de programmation des éléments hôtes et contrôles hôtes Programmatic limitations of host items and host controls
Programmer des Compléments VSTO Program VSTO Add-ins
Programmer des personnalisations au niveau du document Program document-level customizations
Automatiser Word à l’aide d’objets étendus Automate Word by using extended objects
Automatiser Excel à l’aide d’objets étendus Automate Excel by using extended objects
Contrôles sur des documents Office Controls on Office documents
Lier des données aux contrôles dans les solutions OfficeBind data to controls in Office solutions