Partager via

Programmer des personnalisations au niveau du document

  • Article

Quand vous étendez Microsoft Office Word ou Microsoft Office Excel à l’aide d’une personnalisation au niveau du document, vous pouvez effectuer les tâches suivantes :

  • Automatiser l’application à l’aide de son modèle objet.

  • Ajouter des contrôles à la surface du document.

  • Appeler du code Visual Basic pour Applications (VBA) dans le document à partir de l’assembly de personnalisation.

  • Appeler du code dans l’assembly de personnalisation à partir de VBA.

  • Gérer certains aspects du document alors qu’il est sur un serveur sur lequel Microsoft Office n’est pas installé.

  • Personnaliser l’interface utilisateur (IU) de l’application.

    S'applique à : Les informations de cette rubrique s'appliquent aux projets de niveau document pour Excel et Word. Pour plus d'informations, consultez Fonctionnalités disponibles par type d'application et de projet Office.

    Certains aspects de l’écriture de code dans des projets au niveau du document diffèrent des autres types de projets dans Visual Studio. Une grande partie de ces différences ont pour origine la façon dont les modèles objet Office sont exposés au code managé. Pour plus d'informations, voir Écrire du code dans les solutions Office.

    Pour obtenir des informations générales sur les personnalisations de niveau document et les autres types de solutions que vous pouvez créer à l'aide des outils de développement Office de Visual Studio, reportez-vous à la rubrique Vue d'ensemble du développement de solutions Office (VSTO).

Utiliser les classes générées dans les projets de niveau document

Quand vous créez un projet au niveau du document, Visual Studio génère automatiquement une classe dans le projet que vous pouvez utiliser pour commencer à écrire votre code. Visual Studio génère des classes différentes pour Word et Excel :

  • Dans les projets au niveau du document pour Word, la classe est appelée ThisDocument par défaut.

  • Les projets au niveau du document pour Excel comportent plusieurs classes générées : une pour le classeur lui-même et une pour chaque feuille de calcul. Par défaut, ces classes portent les noms suivants :

    • ThisWorkbook

    • Sheet1

    • Sheet2

    • Sheet3

    La classe générée inclut des gestionnaires d’événements appelés quand le document est ouvert ou fermé. Pour exécuter du code à l’ouverture du document, ajoutez-le au gestionnaire d’événements Startup . Pour exécuter du code avant la fermeture du document, ajoutez-le au gestionnaire d’événements Shutdown . Pour plus d'informations, consultez Événements dans les projets Office.

Comprendre la conception des classes générées

Dans les projets qui ciblent .NET Framework 4 ou .NET Framework 4.5, les types d'éléments hôtes dans le runtime Visual Studio Tools for Office sont des interfaces, de sorte que les classes générées ne peuvent pas dériver leur implémentation à partir d'eux. Au lieu de cela, les classes générées dérivent la plupart de leurs membres des classes de base suivantes :

  • ThisDocument: dérive de DocumentBase.

  • ThisWorkbook: dérive de WorkbookBase.

  • Sheet n : dérive de WorksheetBase.

    Ces classes de base redirigent tous les appels à leurs membres vers des implémentations internes des interfaces d'éléments hôtes correspondantes dans le moteur d'exécution Visual Studio Tools for Office. Par exemple, si vous appelez la méthode Protect de la classe ThisDocument, la classe DocumentBase redirige cet appel vers l'implémentation interne de l'interface Document dans le moteur d'exécution Visual Studio Tools for Office.

Accéder au modèle d'objet de l'application hôte

Pour accéder au modèle objet de l’application hôte, utilisez les membres de la classe générée dans votre projet. Chacune de ces classes correspond à un objet dans le modèle objet de Microsoft Excel ou Word, et elles contiennent la plupart des mêmes propriétés, méthodes et événements. Par exemple, la classe ThisDocument dans un projet au niveau du document pour Word fournit plus ou moins les mêmes membres que l’objet Document dans le modèle objet Word.

L’exemple de code suivant montre comment utiliser le modèle objet Word pour enregistrer le document qui fait partie d’une personnalisation au niveau du document pour Word. Cet exemple est destiné à être exécuté à partir de la classe ThisDocument .

this.Save();

Pour effectuer la même opération depuis l'extérieur de la classe ThisDocument , utilisez l'objet Globals pour accéder à la classe ThisDocument . Par exemple, vous pouvez ajouter ce code à un fichier de code du volet Actions si vous voulez inclure un bouton Enregistrer dans l’interface utilisateur de ce volet Actions.

Globals.ThisDocument.Save();

Puisque la classe ThisDocument obtient la plupart de ses membres à partir de l’élément hôte Document , la méthode Save appelée dans ce code correspond vraiment à la méthode Save de l’élément hôte Document . Cette méthode correspond à la méthode Save de l’objet Document dans le modèle objet Word.

Pour plus d'informations sur l'utilisation des modèles d'objets de Word et d'Excel, reportez-vous aux sections Synthèse du modèle d'objet de Word et Synthèse du modèle d'objet d'Excel.

Pour plus d'informations sur l'objet Globals, voir Accès global aux objets dans les projets Office.

Ajouter des contrôles aux documents

Pour personnaliser l’interface utilisateur du document, vous pouvez ajouter des contrôles Windows Forms ou des contrôles hôtes à la surface du document. En combinant plusieurs jeux de contrôles et en écrivant du code, vous pouvez lier les contrôles à des données, recueillir des informations de l’utilisateur et répondre à des actions utilisateur.

Les contrôles hôtes sont des classes qui étendent certains objets du modèle objet Word et Excel. Par exemple, le contrôle hôte ListObject fournit toutes les fonctionnalités de ListObject dans Excel. En revanche, le contrôle hôte ListObject possède également des événements supplémentaires et des fonctionnalités de liaison de données.

Pour plus d'informations, voir la présentation des éléments et des contrôles hôtes et la présentation des contrôles Windows forms sur les documents Office.

Combiner les personnalisations VBA et les personnalisations au niveau du document

Vous pouvez utiliser du code VBA dans un document qui fait partie d’une personnalisation au niveau du document. Vous pouvez appeler du code VBA dans le document à partir de l’assembly de personnalisation ou configurer votre projet pour permettre au code VBA du document d’appeler du code dans l’assembly de personnalisation.

Pour plus d'informations, voir Combiner les personnalisations VBA et les personnalisations au niveau du document.

Gérer des documents sur un serveur

Vous pouvez gérer différents aspects des personnalisations au niveau du document sur un serveur sur lequel Microsoft Office Word ou Microsoft Office Excel ne sont pas installés. Par exemple, vous pouvez accéder aux données du cache du document et les modifier. Vous pouvez également gérer l’assembly de personnalisation associé au document. Par exemple, vous pouvez, par programmation, supprimer l’assembly du document pour qu’il n’exécute plus votre code. Vous pouvez aussi, par programmation, attacher un assembly à un document.

Pour plus d'informations, voir Gérer des documents sur un serveur à l'aide de la classe ServerDocument.

Personnaliser l'interface utilisateur des applications Microsoft Office

Vous pouvez personnaliser l’interface utilisateur de Word et Excel comme suit à l’aide d’une personnalisation au niveau du document :

Obtenir des objets étendus à partir d'objets Office natifs dans les personnalisations au niveau du document

De nombreux gestionnaires d’événements Office reçoivent un objet Office natif qui représente le classeur, la feuille de calcul ou le document qui a déclenché l’événement. Dans certains cas, vous pouvez avoir besoin d’exécuter du code uniquement si le classeur ou le document de votre personnalisation au niveau du document a déclenché l’événement. Par exemple, dans une personnalisation au niveau du document pour Excel, vous pouvez avoir besoin d’exécuter du code quand l’utilisateur active l’une des feuilles de calcul d’un classeur personnalisé, mais pas quand il active une feuille de calcul incluse dans un autre classeur ouvert en même temps.

Quand vous avez un objet Office natif, vous pouvez tester si cet objet a été étendu dans un élément hôte ou contrôle hôte dans une personnalisation au niveau du document. Les éléments hôtes et les contrôles hôtes sont des types fournis par le moteur d'exécution Visual Studio Tools for Office qui ajoutent des fonctionnalités aux objets qui existent nativement dans les modèles d'objets Word ou Excel (appelés objets Office natifs). Collectivement, les éléments hôtes et les contrôles hôtes sont également appelés objets étendus. Pour plus d'informations sur les éléments hôtes et les contrôles hôtes, reportez-vous à la section Présentation des éléments hôtes et des contrôles hôtes.

Comprendre les méthodes GetVstoObject et HasVstoObject

Pour tester un objet Office natif, utilisez les méthodes HasVstoObject et GetVstoObject dans votre projet :

  • Utilisez la méthode HasVstoObject pour déterminer si l’objet Office natif possède un objet étendu dans votre personnalisation. Cette méthode retourne true si l’objet Office natif possède un objet étendu et false dans le cas contraire.

  • Utilisez la méthode GetVstoObject pour obtenir l’objet étendu d’un objet Office natif. Cette méthode retourne un objet ListObject, Workbook, Worksheetou Document si l’objet Office natif spécifié en possède un. Dans le cas contraire, GetVstoObject renvoie la valeur null. Par exemple, la méthode GetVstoObject retourne un objet Document si l’objet Document spécifié est l’objet sous-jacent du document dans votre projet de document Word.

    Dans les projets de niveau document, vous ne pouvez pas utiliser la méthode GetVstoObject pour créer un nouvel élément hôte Workbook, Worksheet ou Document au moment de l'exécution. Vous pouvez utiliser cette méthode uniquement pour accéder aux éléments hôtes existants, générés dans votre projet au moment du design. Pour créer des éléments hôtes au moment de l’exécution, vous devez développer un projet de complément VSTO. Pour plus d'informations, voir Limitations programmatiques des éléments hôtes et des contrôles hôtes et Étendre les documents Word et les classeurs Excel dans les compléments VSTO au moment de l'exécution.

Utilisez les méthodes GetVstoObject et HasVstoObject

Pour appeler les méthodes HasVstoObject et GetVstoObject, utilisez la méthode Globals.Factory.GetVstoObject ou Globals.Factory.HasVstoObject et transmettez l'objet Word ou Excel natif (tel que Document ou Worksheet) que vous souhaitez tester.

Contenu connexe