Limitations programmatiques des éléments hôtes et des contrôles hôtes

  • Article

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

Pour obtenir des informations générales sur les éléments hôtes et les contrôles hôtes, consultez la vue d’ensemble des éléments hôtes et des contrôles hôtes.

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.

Créer des éléments hôtes par programmation

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. À la place, le nouvel objet est un objet Office natif. 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 . 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 .

Dans les projets au niveau du document, vous ne pouvez pas créer d’éléments hôtes au moment de l’exécution. Vous ne pouvez créer les éléments hôtes qu’au moment du design dans les projets au niveau du document. Pour plus d’informations, consultez l’élément hôte de document, l’élément hôte du classeur et l’élément hôte de feuille de calcul.

Dans les projets de compléments VSTO, vous pouvez créer des éléments hôtes Document, Workbookou Worksheet au moment de l’exécution. Pour plus d’informations, consultez Étendre les documents Word et les classeurs Excel dans les compléments VSTO au moment de l’exécution.

Créer des contrôles hôtes par programmation

Vous pouvez ajouter par programmation des contrôles hôtes à un élément hôte Document ou Worksheet au moment de l’exécution. Pour plus d’informations, consultez Ajouter des contrôles à Bureau documents au moment de l’exécution.

Vous ne pouvez pas ajouter de contrôles hôtes à un Document ou Worksheetnatif.

Remarque

Vous ne pouvez pas ajouter les contrôles hôtes suivants par programmation aux feuilles de calcul ou aux documents : XmlMappedRange, XMLNode, et XMLNodes.

Comprendre les différences de type entre les éléments hôtes, les contrôles hôtes et les objets Bureau natifs

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. Vous pouvez accéder à l’objet sous-jacent à l’aide de la propriété InnerObject de l’élément hôte ou du contrôle hôte. 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. 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é.

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.

Passer des contrôles hôtes aux méthodes et aux propriétés

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. Vous devez utiliser la propriété InnerObject du contrôle hôte pour retourner l’objet Word natif sous-jacent. 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.

Dans Excel, vous devez utiliser la propriété InnerObject du contrôle hôte pour transmettre le contrôle hôte à une méthode ou à une propriété lorsque la méthode ou la propriété attend l’objet Excel sous-jacent.

L’exemple suivant crée un contrôle NamedRange et le passe à la méthode AutoFill . 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 .

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);

Types de retour de méthodes et de propriétés Bureau natives

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

Accéder aux collections de contrôles hôtes

Le runtime Visual Studio Tools pour Office ne fournit pas de collections individuelles pour chaque type de contrôle hôte. Utilisez plutôt la propriété Controls d’un élément hôte pour itérer dans tous les contrôles gérés (contrôles hôtes et contrôles Windows Forms) dans le document ou la feuille de calcul, puis recherchez les éléments qui correspondent au type du contrôle hôte qui vous intéresse. 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.

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

Pour plus d’informations sur la propriété Controls des éléments hôtes, consultez Ajouter des contrôles à Bureau documents au moment de l’exécution.

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. Vous ne pouvez pas accéder aux contrôles managés à l’aide de ces propriétés. 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. 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.

Contenu connexe