Limitations de programmation des éléments hôtes et des contrôles hôtesProgrammatic limitations of host items and host controls

Chaque élément hôte et contrôle hôte est conçu pour se comporter comme un objet Microsoft Office Word ou Microsoft Office Excel natif correspondant, avec des fonctionnalités supplémentaires.Each host item and host control is designed to behave like a corresponding native Microsoft Office Word or Microsoft Office Excel object, with additional functionality. Toutefois, il existe des différences fondamentales entre le comportement des éléments hôtes ou contrôles hôtes, et celui des objets Office natifs au moment de l’exécution.However, there are some fundamental differences between the behavior of host items and host controls and native Office objects at run time.

Pour obtenir des informations générales sur les éléments hôtes et des contrôles hôtes, consultez éléments hôtes et héberger la vue d’ensemble des contrôles.For general information about host items and host controls, see Host items and host controls overview.

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.

Créer par programmation des éléments hôtesProgrammatically create host items

Quand vous créez ou ouvrez par programmation un document, un classeur ou une feuille de calcul au moment de l’exécution via le modèle objet Word ou Excel, l’élément n’est pas un élément hôte.When you programmatically create or open a document, workbook, or worksheet at run time by using the Word or Excel object model, the item is not a host item. À la place, le nouvel objet est un objet Office natif.Instead, the new object is a native Office object. Par exemple, si vous utilisez la méthode Add pour créer un document Word au moment de l’exécution, il correspond à un objet Document natif au lieu d’un élément hôte Document .For example, if you use the Add method to create a new Word document at run time, it will be a native Document object rather than a Document host item. De même, quand vous créez une feuille de calcul au moment de l’exécution à l’aide de la méthode Add , vous obtenez un objet Worksheet natif au lieu d’un élément hôte Worksheet .Similarly, when you create a new worksheet at run time using the Add method, you get a native Worksheet object rather than a Worksheet host item.

Dans les projets au niveau du document, vous ne pouvez pas créer des éléments hôtes lors de l’exécution.In document-level projects, you cannot create host items at runtime. Vous ne pouvez créer les éléments hôtes qu’au moment du design dans les projets au niveau du document.Host items can be created only at design time in document-level projects. Pour plus d’informations, consultez élément hôte de Document, élément hôte de classeur, et élément hôte de feuille de calcul.For more information, see Document host item, Workbook host item, and Worksheet host item.

Dans les projets de complément VSTO, vous pouvez créer Document, Workbook, ou Worksheet héberger des éléments lors de l’exécution.In VSTO Add-in projects, you can create Document, Workbook, or Worksheet host items at runtime. 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.

Créer par programmation des contrôles hôtesProgrammatically create host controls

Vous pouvez ajouter par programmation des contrôles hôtes à un Document ou Worksheet élément hôte lors de l’exécution.You can programmatically add host controls to a Document or Worksheet host item at runtime. 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.

Vous ne pouvez pas ajouter de contrôles hôtes à un Document ou Worksheetnatif.You cannot add host controls to a native Document or Worksheet.

Note

Vous ne pouvez pas ajouter les contrôles hôtes suivants par programmation aux feuilles de calcul ou aux documents : XmlMappedRange, XMLNode, et XMLNodes.The following host controls cannot be added programmatically to worksheets or documents: XmlMappedRange, XMLNode, and XMLNodes.

Comprendre les différences de type entre les éléments hôtes, contrôles hôtes et les objets Office natifsUnderstand type differences between host items, host controls, and native Office objects

Pour chaque élément hôte et contrôle hôte, il existe un objet Microsoft Office Word ou Microsoft Office Excel natif sous-jacent.For each host item and host control, there is an underlying native Microsoft Office Word or Microsoft Office Excel object. Vous pouvez accéder à l’objet sous-jacent à l’aide de la propriété InnerObject de l’élément hôte ou contrôle hôte.You can access the underlying object by using the InnerObject property of the host item or host control. Toutefois, il n’existe aucun moyen d’effectuer un cast d’un objet Office natif vers son élément hôte ou contrôle hôte correspondant.However, there is no way to cast a native Office object to its corresponding host item or host control. Si vous essayez d’effectuer un cast d’un objet Office natif vers le type d’un élément hôte ou contrôle hôte, InvalidCastException est levé.If you try to cast a native Office object into the type of a host item or host control, an InvalidCastException is thrown.

Il existe plusieurs scénarios où les différences entre les types des éléments hôtes ou contrôles hôtes, et ceux des objets Office natifs sous-jacents peuvent affecter votre code.There are several scenarios where the differences between the types of host items and host controls and the underlying native Office objects can affect your code.

Passer des contrôles hôtes aux méthodes et propriétésPass host controls to methods and properties

Dans Word, vous ne pouvez pas passer un contrôle hôte à une méthode ou une propriété qui nécessite un objet Word natif en tant que paramètre.In Word, you cannot pass a host control to a method or property that requires a native Word object as a parameter. Vous devez utiliser la propriété InnerObject du contrôle hôte pour retourner l’objet Word natif sous-jacent.You must use the InnerObject property of the host control to return the underlying native Word object. Par exemple, vous pouvez passer un objet Bookmark à une méthode en passant la propriété InnerObject du contrôle hôte Bookmark à la méthode.For example, you can pass a Bookmark object to a method by passing the InnerObject property of the Bookmark host control to the method.

Dans Excel, vous devez utiliser la propriété InnerObject du contrôle hôte pour passer le contrôle hôte à une méthode ou propriété lorsque la méthode ou propriété attend l’objet Excel sous-jacent.In Excel, you must use the InnerObject property of the host control to pass the host control to a method or property when the method or property expects the underlying Excel object.

L’exemple suivant crée un contrôle NamedRange et le passe à la méthode AutoFill .The following example creates a NamedRange control and passes it to the AutoFill method. Le code utilise la propriété InnerObject de la plage nommée pour retourner le Range Office sous-jacent nécessaire à la méthode AutoFill .The code uses the InnerObject property of the named range to return the underlying Office Range that is required by the AutoFill method.

this.Range["A1"].Value2 = "Monday";
this.Range["A2"].Value2 = "Tuesday";

Microsoft.Office.Tools.Excel.NamedRange dayRange = 
    this.Controls.AddNamedRange(this.Range["A1", "A7"], "dayRange");
this.Range["A1", "A2"].AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays);
Me.Range("A1").Value2 = "Monday"
Me.Range("A2").Value2 = "Tuesday"

Dim dayRange As Microsoft.Office.Tools.Excel.NamedRange = _
    Me.Controls.AddNamedRange(Me.Range("A1", "A7"), "dayRange")
Me.Range("A1", "A2").AutoFill(dayRange.InnerObject, Excel.XlAutoFillType.xlFillDays)

Types de retour des propriétés et méthodes Office nativesReturn types of native Office methods and properties

La plupart des méthodes et propriétés des éléments hôtes retournent l’objet Office natif sous-jacent sur lequel l’élément hôte est basé.Most methods and properties of host items return the underlying native Office object upon which the host item is based. Par exemple, la propriété Parent d’un contrôle hôte NamedRange dans Excel retourne un objet Worksheet à la place d’un élément hôte Worksheet .For example, the Parent property of a NamedRange host control in Excel returns a Worksheet object rather than a Worksheet host item. De même, la propriété Parent d’un contrôle hôte RichTextContentControl dans Word retourne un objet Document à la place d’un élément hôte Document .Similarly, the Parent property of a RichTextContentControl host control in Word returns a Document object rather than a Document host item.

Collections d’accès de contrôles hôtesAccess collections of host controls

Le Visual Studio Tools pour Office RuntimeVisual Studio Tools for Office runtime ne fournit pas de collections individuelles pour chaque type de contrôle hôte.The Visual Studio Tools pour Office RuntimeVisual Studio Tools for Office runtime does not provide individual collections for each type of host control. Au lieu de cela, utilisez la propriété de contrôles d’un élément hôte pour itérer sur tous les contrôles managés (contrôles hôtes et contrôles Windows Forms) sur le document ou la feuille de calcul, puis rechercher les éléments qui correspondent au type du contrôle hôte qui que vous intéressez.Instead, use the Controls property of a host item to iterate through all managed controls (both host controls and Windows Forms controls) on the document or worksheet, and then look for items that match the type of the host control you are interested in. L’exemple de code suivant permet d’examiner chaque contrôle d’un document Word et de déterminer si le contrôle correspond à Bookmark.The following code example examines each control on a Word document and determines whether the control is a Bookmark.

foreach (object targetControl in this.Controls)
{
    Microsoft.Office.Tools.Word.Bookmark bookMark =
        targetControl as Microsoft.Office.Tools.Word.Bookmark;

    if (bookMark != null)
    {
        // Do some work with the bookmark here.
    }
}
Dim targetControl As Object
For Each targetControl In Me.Controls

    If TypeOf (targetControl) Is Microsoft.Office.Tools.Word.Bookmark Then
        Dim bookMark As Microsoft.Office.Tools.Word.Bookmark = _
            CType(targetControl, Microsoft.Office.Tools.Word.Bookmark)

        ' Do some work with the book mark here.
    End If
Next

Pour plus d’informations sur la propriété de contrôles des éléments hôtes, consultez ajouter des contrôles aux documents Office au moment de l’exécution.For more information about the Controls property of host items, see Add controls to Office documents at runtime.

Les modèles objet Word et Excel incluent des propriétés qui exposent des collections de contrôles natifs sur des documents et des feuilles de calcul.The Word and Excel object models include properties that expose collections of native controls on documents and worksheets. Vous ne pouvez pas accéder aux contrôles managés à l’aide de ces propriétés.You cannot access managed controls by using these properties. Par exemple, il n’est pas possible d’énumérer chaque contrôle hôte Bookmark d’un document à l’aide de la propriété Bookmarks de Document ou de la propriété Bookmarks de Document.For example, it is not possible to enumerate each Bookmark host control in a document by using the Bookmarks property of a Document or the Bookmarks property of a Document. Ces propriétés incluent uniquement les contrôles Bookmark dans le document ; elles ne contiennent pas les contrôles hôtes Bookmark dans le document.These properties include only the Bookmark controls in the document; they do not contain the Bookmark host controls in the document.

Voir aussiSee also

Éléments hôtes et vue d’ensemble des contrôles hôtes Host items and host controls overview
Automatisation de Word à l’aide d’objets étendus Automate Word by using extended objects
Automatisation d’Excel à l’aide d’objets étendus Automate Excel by using extended objects
Élément hôte de feuille de calcul Worksheet host item
Élément hôte de classeur Workbook host item
Élément hôte de documentDocument host item