Programmation de personnalisations au niveau du document

Article
03/04/2013

Lorsque vous étendez Microsoft Office Word ou Microsoft Office Excel par le biais 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 depuis l'assembly de personnalisation.
Appeler du code dans l'assembly de personnalisation depuis VBA.
Gérer certains aspects du document lorsqu'il se trouve sur un serveur sur lequel Microsoft Office n'est pas installé.
Personnaliser l'interface utilisateur de l'application.

S'applique à : Les informations contenues dans cette rubrique s'appliquent aux projets de niveau document pour les applications suivantes : Excel 2013, Excel 2010, Word 2013 et Word 2010. Pour en savoir plus, consultez Fonctionnalités disponibles par type d'application et de projet Office.

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

Pour plus d'informations générales sur les personnalisations au niveau du document et les 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.

Utilisation des classes générées dans les projets au niveau du document

Lorsque 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 autre 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 à l'ouverture et à la fermeture du document.Pour exécuter un code à l'ouverture du document, ajoutez celui-ci au gestionnaire d'événements Startup.Pour exécuter du code juste 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, l'élément hôte types dans Visual Studio Tools pour Office Runtime sont des interfaces, les classes générées ne peuvent pas dériver leur implémentation de ces derniers.Les membres des classes générées dérivent pour la plupart des classes de base suivantes :

ThisDocument: dérive d' Microsoft.Office.Tools.Word.DocumentBase.
ThisWorkbook: dérive d' Microsoft.Office.Tools.Excel.WorkbookBase.
Sheetn: dérive d' Microsoft.Office.Tools.Excel.WorksheetBase.

Ces classes de base redirigent tous les appels généraux à leurs membres vers les implémentations internes des interfaces d'élément hôte correspondantes du Visual Studio Tools pour Office Runtime.Par exemple, si vous appelez la méthode d' Protect de classe d' ThisDocument, la classe d' Microsoft.Office.Tools.Word.DocumentBase redirige cet appel à l'implémentation interne de l'interface d' Microsoft.Office.Tools.Word.Document dans Visual Studio Tools pour Office Runtime.

Accès au modèle objet de l'application hôte

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

L'exemple de code suivant indique 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é depuis la classe ThisDocument.

Me.Save()

this.Save();

Pour effectuer la même opération en dehors 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 de volet Actions si vous souhaitez inclure un bouton Enregistrer dans l'interface utilisateur de celui-ci.

Globals.ThisDocument.Save()

Globals.ThisDocument.Save();

Étant donné que la classe ThisDocument obtient la plupart de ses membres de l'élément hôte Microsoft.Office.Tools.Word.Document, la méthode Save appelée dans ce code est réellement la méthode Save de l'élément hôte Microsoft.Office.Tools.Word.Document.Cette méthode correspond à la méthode Save de l'objet Microsoft.Office.Interop.Word.Document dans le modèle objet de Word.

Pour plus d'informations sur l'utilisation des modèles objets 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'objet Globals, consultez Accès global aux objets dans les projets Office.

Ajout de contrôles à des 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 aux données, rassembler des informations auprès de l'utilisateur et répondre aux actions de celui-ci.

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 Microsoft.Office.Tools.Excel.ListObject fournit toutes les fonctionnalités de Microsoft.Office.Interop.Excel.ListObject dans Excel.Toutefois, le contrôle hôte Microsoft.Office.Tools.Excel.ListObject contient aussi des événements supplémentaires et des fonctions 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.

Combinaison de VBA et de personnalisations au niveau du document

Vous pouvez utiliser du code VBA dans un document appartenant à une personnalisation au niveau du document.Vous pouvez appeler du code VBA dans le document de l'assembly de personnalisation et configurer votre projet pour permettre au code VBA du document d'appeler le code de l'assembly de personnalisation.

Pour plus d'informations, consultez Combinaison de VBA et de personnalisations au niveau du document.

Gestion de documents sur un serveur

Vous pouvez gérer différents aspects des personnalisations au niveau du document sur un serveur qui n'est pas doté de Microsoft Office Word ou de Microsoft Office Excel.Par exemple, vous pouvez accéder aux données du cache de données du document et les modifier.Vous pouvez également gérer l'assembly de personnalisation associé au document.Par exemple, vous pouvez supprimer par programmation l'assembly du document afin que le document n'exécute plus votre code, ou vous pouvez joindre par programmation un assembly à un document.

Pour plus d'informations, consultez Gestion de documents sur un serveur à l'aide de la classe ServerDocument.

Personnalisation de l'interface utilisateur des applications Microsoft Office

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

Ajouter des contrôles hôtes ou des contrôles Windows Forms à la surface du document.

Pour plus d'informations, consultez Automatisation de Word à l'aide d'objets étendus, Automatisation d'Excel à l'aide d'objets étendus et Vue d'ensemble des contrôles Windows Forms dans les documents Office.
Ajouter un volet Actions au document.

Pour plus d'informations, consultez Vue d'ensemble du volet Actions.
Ajouter des onglets personnalisés au ruban.

Pour plus d'informations, consultez Vue d'ensemble du ruban.
Ajoutez des groupes personnalisés à un onglet intégré du ruban.

Pour plus d'informations, consultez Comment : personnaliser un onglet intégré.

Pour plus d'informations sur la personnalisation de l'interface utilisateur des applications Microsoft Office, consultez Personnalisation de l'interface utilisateur Office.

Obtention d'objets étendus les objets Office natifs dans les personnalisations au niveau de le document

De nombreux gestionnaires d'événements pour 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.Il peut arriver que vous ne souhaitiez exécuter du code que 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 souhaiter exécuter du code lorsque l'utilisateur active l'une des feuilles de calcul d'un classeur personnalisé, mais pas lorsqu'il active une feuille de calcul d'un autre classeur qui se trouve ouvert au même moment.

Lorsque vous avez un objet Office natif, vous pouvez vérifier si cet objet a été étendu en un élément hôte ou en un contrôle hôte dans une personnalisation de niveau document.Les éléments hôtes et contrôles hôtes sont des types fournis par le Visual Studio Tools pour Office Runtime qui ajoutent les fonctionnalités aux objets qui existent en mode natif dans les modèles objets (appelés objets Office natifs) de Word ou d'Excel.Ensemble, les éléments hôtes et contrôles hôtes sont également appelés objets étendus. Pour plus d'informations sur les éléments hôtes et des contrôles hôtes, consultez Vue d'ensemble des éléments hôtes et des contrôles hôtes.

Compréhension des 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 si vous souhaitez simplement déterminer si l'objet Office natif a un objet étendu dans votre personnalisation.Cette méthode retourne la valeur true si l'objet Office natif a un objet étendu, et false si ce n'est pas le cas.
Utilisez la méthode GetVstoObject si vous souhaitez obtenir l'objet étendu d'un objet Office natif.Cette méthode retourne un objet Microsoft.Office.Tools.Excel.ListObject, Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheetou Microsoft.Office.Tools.Word.Document si l'objet Office natif spécifié en a un.Sinon, GetVstoObject retourne null.Par exemple, la méthode GetVstoObject retourne un Microsoft.Office.Tools.Word.Document si le Microsoft.Office.Interop.Word.Document spécifié est un objet sous-jacent du document de 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 Microsoft.Office.Tools.Excel.Workbook, Microsoft.Office.Tools.Excel.Worksheet ou Microsoft.Office.Tools.Word.Document au moment de l'exécution.Vous ne pouvez utiliser cette méthode que 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 niveau application.Pour plus d'informations, consultez Limitations de programmation des éléments hôtes et des contrôles hôtes et Extension de documents Word et de classeurs Excel dans des compléments d'application au moment de l'exécution..

Utilisation des méthodes GetVstoObject et HasVstoObject

Pour appeler la méthode d' HasVstoObject et d' GetVstoObject, utilisez la méthode d' Globals.Factory.GetVstoObject ou d' Globals.Factory.HasVstoObject, et passez dans l'objet Word ou Excel natif (tel qu' Microsoft.Office.Interop.Word.Document ou Microsoft.Office.Interop.Excel.Worksheet) que vous souhaitez tester.