Personnaliser les personnalisations au niveau du document

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 contenues dans 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, consultez écrire du code dans les solutions Office.

    Pour obtenir des informations générales sur les personnalisations au niveau du document et d’autres types de solutions que vous pouvez créer à l’aide des outils de développement Office dans Visual Studio, consultez vue d’ensemble du développement des solutions office (VSTO).

Utiliser les classes générées dans les projets au niveau du 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 le .NET Framework 4 ou le .NET Framework 4.5, les types d’élément hôte dans le Visual Studio Tools pour Office Runtime sont des interfaces, donc les classes générées ne peuvent pas en dériver leur implémentation. 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.

  • Sheetn: dérive de WorksheetBase .

    Ces classes de base redirigent tous les appels à leurs membres vers les implémentations internes des interfaces de l’élément hôte correspondant dans le Visual Studio Tools pour Office Runtime. 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 Visual Studio Tools pour Office Runtime.

Accéder au modèle 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 .

Me.Save()
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()
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 objet de Word et Excel, consultez vue d’ensemble du modèle objet Word et vue d’ensemble du modèle objet Excel.

Pour plus d’informations sur l' Globals objet, consultez 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 auprès de l’utilisateur et répondre aux actions de l’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, consultez vue d’ensemble des éléments hôtes et des contrôles hôtes et vue d’ensemble des contrôles Windows Forms dans les documents Office.

Combiner 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, consultez combiner des personnalisations VBA et 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, consultez 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 :

Récupérer 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 Visual Studio Tools pour Office Runtime qui ajoutent des fonctionnalités aux objets qui existent en mode natif dans les modèles objet 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, consultez vue d’ensemble 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. Sinon, GetVstoObject retourne 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 au niveau du document, vous ne pouvez pas utiliser la GetVstoObject méthode pour créer un nouvel Workbook Worksheet Document élément hôte, ou 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. Si vous souhaitez 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, consultez limitations de programmation 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 momentde l’exécution.

Utiliser les méthodes GetVstoObject et HasVstoObject

Pour appeler la HasVstoObject GetVstoObject méthode et, utilisez la Globals.Factory.GetVstoObject Globals.Factory.HasVstoObject méthode ou, puis transmettez l’objet Word ou Excel natif (par exemple, Document ou Worksheet ) que vous voulez tester.

Voir aussi