Ajouter des en-têtes à l’ouverture d’un document

Les sections suivantes vous guident dans la procédure de développement d’un complément Word qui modifie automatiquement l’en-tête du document lors de l’ouverture d’un document nouveau ou existant. Bien que ce complément spécifique soit destiné à Word, la configuration du manifeste et du fichier webpack.config.js est la même pour Excel et PowerPoint. Pour obtenir une vue d’ensemble de ce modèle d’activation basé sur les événements, voir Activer des compléments avec des événements.

Créer un complément

Créez un nouveau complément en suivant le Guide de démarrage rapide du complément Word, mais notez les modifications suivantes dans les étapes qui y sont décrites.

• Utilisez les instructions pour le manifeste du complément uniquement. Le manifeste unifié pour Microsoft 365 ne prend pas encore en charge l’événement OnDocumentOpened utilisé dans ce projet.
• Lorsque Yo Office vous invite à choisir une langue, sélectionnez JavaScript.

Configurer le manifeste

Pour activer un complément basé sur un événement, vous devez configurer les éléments suivants dans le VersionOverridesV1_0 nœud du manifeste. Notez ce qui suit à propos du nouveau balisage fourni ci-dessous.

• Le code qui gère l’événement OnDocumentOpened s’exécute dans un environnement d’exécution de navigateur dans Word sur le web, mais dans un environnement d’exécution JavaScript uniquement dans Word sur Windows. Pour configurer ce modèle, un élément Runtime est ajouté qui pointe les runtimes du navigateur vers le fichier commands.html du projet. Cet élément a un élément de remplacement enfant pour le runtime qui remplace le type « javascript » et pointe les runtimes JavaScript uniquement vers le fichier commands.js . Pour plus d’informations sur les environnements d’exécution des compléments Office, consultez Runtimes dans les compléments Office.
• Dans l’élément ExtensionPoint , la est xsi:type définie sur LaunchEvent. Cela active la fonctionnalité d’activation en fonction des événements dans votre complément.
• Dans l’élément SourceLocation de l’élément <ExtensionPoint> , la resid valeur est définie pour correspondre à celle de l’élément Runtime qui fait référence au fichier HTML.
• Dans l’élément LaunchEvent , the Type est défini sur OnDocumentOpened et l’attribut FunctionName est défini sur le nom de fonction JavaScript du gestionnaire d’événements.
• Dans cette Resources section, le JsRuntimeWord.Url est défini en tant que sous-dossier \public dans l’application web. En conjonction avec les modifications que vous allez apporter dans le fichier webpack.config.js , cette URL garantit que le commands.js qui s’exécute dans le runtime JavaScript uniquement n’est pas regroupé avec du code qui nécessite un runtime de navigateur. Voir Configurer webpack.config.js.

Utilisez l’exemple de code manifeste suivant pour mettre à jour votre projet.

1. Dans votre éditeur de code, ouvrez le projet de démarrage rapide que vous avez créé.

2. Ouvrez le fichier manifest.xml situé à la racine de votre projet.

3. Sélectionnez le nœud entier <VersionOverrides> (y compris les balises d’ouverture et de fermeture) et remplacez-le par le XML suivant.

     <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
       <Hosts>
         <Host xsi:type="Document">
           <Runtimes>
             <Runtime resid="WebViewRuntime.Url">
               <Override type="javascript" resid="JsRuntimeWord.Url"/>
             </Runtime>
           </Runtimes>
           <DesktopFormFactor>
             <GetStarted>
               <Title resid="GetStarted.Title"/>
               <Description resid="GetStarted.Description"/>
               <LearnMoreUrl resid="GetStarted.LearnMoreUrl"/>
             </GetStarted>
             <FunctionFile resid="Commands.Url"/>
             <ExtensionPoint xsi:type="LaunchEvent">
               <LaunchEvents>
                 <LaunchEvent Type="OnDocumentOpened" FunctionName="changeHeader"></LaunchEvent>
               </LaunchEvents>
               <SourceLocation resid="WebViewRuntime.Url"/>
             </ExtensionPoint>
             <ExtensionPoint xsi:type="PrimaryCommandSurface">
               <OfficeTab id="TabHome">
                 <Group id="CommandsGroup">
                   <Label resid="CommandsGroup.Label"/>
                   <Icon>
                     <bt:Image size="16" resid="Icon.16x16"/>
                     <bt:Image size="32" resid="Icon.32x32"/>
                     <bt:Image size="80" resid="Icon.80x80"/>
                   </Icon>
                   <Control xsi:type="Button" id="TaskpaneButton">
                     <Label resid="TaskpaneButton.Label"/>
                     <Supertip>
                       <Title resid="TaskpaneButton.Label"/>
                       <Description resid="TaskpaneButton.Tooltip"/>
                     </Supertip>
                     <Icon>
                       <bt:Image size="16" resid="Icon.16x16"/>
                       <bt:Image size="32" resid="Icon.32x32"/>
                       <bt:Image size="80" resid="Icon.80x80"/>
                     </Icon>
                     <Action xsi:type="ShowTaskpane">
                       <TaskpaneId>ButtonId1</TaskpaneId>
                       <SourceLocation resid="Taskpane.Url"/>
                     </Action>
                   </Control>
                 </Group>
               </OfficeTab>
             </ExtensionPoint>
           </DesktopFormFactor>
         </Host>
       </Hosts>
       <Resources>
         <bt:Images>
           <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
           <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
           <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
         </bt:Images>
         <bt:Urls>
           <bt:Url id="GetStarted.LearnMoreUrl" DefaultValue="https://go.microsoft.com/fwlink/?LinkId=276812"/>
           <bt:Url id="Commands.Url" DefaultValue="https://localhost:3000/commands.html"/>
           <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html"/>
           <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html"/>
           <bt:Url id="JsRuntimeWord.Url" DefaultValue="https://localhost:3000/public/commands.js"/>
         </bt:Urls>
         <bt:ShortStrings>
           <bt:String id="GetStarted.Title" DefaultValue="Get started with your sample add-in!"/>
           <bt:String id="CommandsGroup.Label" DefaultValue="Event-activated add-in"/>
           <bt:String id="TaskpaneButton.Label" DefaultValue="My add-in"/>
         </bt:ShortStrings>
         <bt:LongStrings>
           <bt:String id="GetStarted.Description" DefaultValue="Your sample add-in loaded successfully. Go to the HOME tab and click the 'Show Task Pane' button to get started."/>
           <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Click to show the task pane"/>
         </bt:LongStrings>
       </Resources>
     </VersionOverrides>
   

4. Enregistrez vos modifications.

Mettre en œuvre le gestionnaire d’événements

Pour permettre à votre complément d’agir lorsque l’événement OnDocumentOpened se produit, vous devez implémenter un gestionnaire d’événements JavaScript. Dans cette section, vous allez créer la changeHeader fonction, qui ajoute un en-tête « Public » aux nouveaux documents ou un en-tête « Hautement confidentiel » aux documents existants qui ont déjà du contenu.

1. Dans le dossier ./src/commandes , ouvrez le fichier nommécommands.js.

2. Remplacez l’intégralité du contenu de commands.js par le code JavaScript suivant.

     /*
     * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
     * See LICENSE in the project root for license information.
     */
     /* global global, Office, self, window */
   
     Office.onReady(() => {
       // If needed, Office.js is ready to be called.
     });
   
     async function changeHeader(event) {
       await Word.run(async (context) => {
         const body = context.document.body;
         body.load("text");
         await context.sync();
   
         if (body.text.length === 0) {
         // For new or empty documents, make a "Public" header. 
           const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
           const firstPageHeader = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.firstPage);
           header.clear();
           firstPageHeader.clear();
   
           header.insertParagraph("Public - The data is for the public and shareable externally", "Start");
           firstPageHeader.insertParagraph("Public - The data is for the public and shareable externally", "Start");
           header.font.color = "#07641d";
           firstPageHeader.font.color = "#07641d";
           await context.sync();
         } else {
           // For existing documents, make a "Highly Confidential" header.
           const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
           const firstPageHeader = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.firstPage);
           header.clear();
           firstPageHeader.clear();
           header.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
           firstPageHeader.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
           header.font.color = "#f8334d";
           firstPageHeader.font.color = "#f8334d";
           await context.sync();
         }
       });
   
       // Calling event.completed is required. event.completed lets the platform know that processing has completed.
       event.completed();
     }
   
     async function paragraphChanged() {
       await Word.run(async (context) => {
         const results = context.document.body.search("110");
         results.load("length");
         await context.sync();
         if (results.items.length === 0) {
           const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
           header.clear();
           header.insertParagraph("Public - The data is for the public and shareable externally", "Start");
           const font = header.font;
           font.color = "#07641d";
   
           await context.sync();
         } else {
           const header = context.document.sections.getFirst().getHeader(Word.HeaderFooterType.primary);
           header.clear();
           header.insertParagraph("Highly Confidential - The data must be secret or in some way highly critical", "Start");
           const font = header.font;
           font.color = "#f8334d";
   
           await context.sync();
         }
       });
     }
   
     async function registerOnParagraphChanged(event) {
       await Word.run(async (context) => {
         let eventContext = context.document.onParagraphChanged.add(paragraphChanged);
         await context.sync();
       });
       // Calling event.completed is required. event.completed lets the platform know that processing has completed.
       event.completed();
     }
   
     Office.actions.associate("changeHeader", changeHeader);
     Office.actions.associate("registerOnParagraphChanged", registerOnParagraphChanged);
   

3. Enregistrez vos modifications.

Configurer webpack.config.js

Le fichier webpack.config.js doit être configuré afin de créer des ensembles distincts de code JavaScript pour le navigateur et les environnements d’exécution JavaScript uniquement. Suivez la procédure ci-après.

1. Ajoutez la ligne suivante en haut du fichier où les autres s globaux constsont déclarés.

   const path = require("path");
   

2. Pour vous assurer que l’icône du complément peut apparaître dans la liste des applications intégrées du portail d’administration de l’Administration Microsoft 365, ajoutez la propriété suivante à l’objet devServer en bas du fichier.

   allowedHosts: "all",
   

3. Pour vous assurer que le commands.js qui s’exécute dans le runtime JavaScript uniquement n’est pas regroupé avec du code qui nécessite un runtime de navigateur, ajoutez la propriété suivante static à l’objet devServer .

   static: {
       directory: path.join(__dirname, "dist"),
       publicPath: "/public",
     },
   

   L’objet entier devServer doit maintenant ressembler à ce qui suit.

   devServer: {
     allowedHosts: "all",
     static: {
       directory: path.join(__dirname, "dist"),
       publicPath: "/public",
     },
     headers: {
       "Access-Control-Allow-Origin": "*",
     },
     server: {
       type: "https",
       options: env.WEBPACK_BUILD || options.https !== undefined ? options.https : await getHttpsOptions(),
     },
     port: process.env.npm_package_config_dev_server_port || 3000,
   },
   

Installez l’exemple pour le tester

1. Dans une invite de commandes, accédez à la racine du projet.
2. Exécutez npm run build:dev.
3. Exécutez npm run dev-server.
4. Dans le portail d’administration Microsoft 365, développez la section Paramètres dans le volet de navigation, puis sélectionnez Applications intégrées.
5. Dans la page Applications intégrées , choisissez l’action Charger des applications personnalisées .
6. Sur la page Charger les applications à déployer , sélectionnez Complément Office dans la liste déroulante Type d’application .
7. Dans la section Choisir comment télécharger l’application , sélectionnez Télécharger le fichier manifeste (.xml) à partir de l’appareil.
8. Utilisez le sélecteur de fichiers pour accéder à la racine du projet, puis sélectionnez le manifest.xml fichier.
9. Sélectionnez Moi uniquement en tant qu’utilisateur.
10. Suivez les instructions à l’écran pour terminer le déploiement.

Essayez

1. Dans Word sur le web ou dans Word sur Windows, essayez d’ouvrir des documents Word nouveaux et existants. Si le complément s’est propagé à la plateforme, les en-têtes doivent être ajoutés automatiquement à l’ouverture du document et un bouton Mon complément doit apparaître dans un groupe de compléments activés par événement sous l’onglet Accueil du ruban. Si ces choses ne se produisent pas, la propagation vers la plateforme n’est pas terminée. Fermez Word et réessayez un peu plus tard.
2. Sélectionnez le bouton Mes compléments pour ouvrir le volet Office.
3. Sélectionnez l’un des liens dans le volet des tâches pour ajouter ou modifier l’en-tête.

Désinstaller le complément

Pour désinstaller le complément, procédez comme suit :

1. Dans le portail d’administration Microsoft 365, développez la section Paramètres dans le volet de navigation, puis sélectionnez Applications intégrées.
2. Dans la page Applications intégrées , sélectionnez le complément.
3. Dans le menu volant du complément, sélectionnez Supprimer l’application.
4. Dans la page Supprimer des applications , confirmez que vous souhaitez supprimer l’application, puis sélectionnez Supprimer.
5. Dans la page Suppression réussie , sélectionnez Terminé.

Voir aussi

• Activer des compléments avec des événements
• Compléments de débogage basés sur des événements ou de rapports de courrier indésirable
• Résoudre les problèmes liés aux modules complémentaires de signalement d'événements et de spams
• Temps d'exécution dans les compléments Office