Adicionar cabeçalhos quando um documento for aberto

As seções a seguir orientam você sobre como desenvolver um suplemento do Word que altera automaticamente o cabeçalho do documento quando um documento novo ou existente é aberto. Embora esse suplemento específico seja para Word, a configuração do manifesto e do arquivo webpack.config.js é a mesma para o Excel e o PowerPoint. Para obter uma visão geral desse padrão de ativação baseado em eventos, consulte Ativar suplementos com eventos.

Criar um novo suplemento

Crie um novo suplemento seguindo o início rápido do suplemento do Word, mas observe as seguintes alterações nas etapas descritas lá.

• Use as diretrizes para o manifesto somente do suplemento. O manifesto unificado para o Microsoft 365 ainda não é compatível com o OnDocumentOpened evento usado neste projeto.
• Quando o Yo Office solicitar que você escolha um idioma, selecione JavaScript.

Configurar o manifesto

Para habilitar um suplemento baseado em eventos, você deve configurar os elementos a seguir no VersionOverridesV1_0 nó do manifesto. Observe o seguinte sobre a nova marcação, fornecida abaixo.

• O código que manipula o OnDocumentOpened evento é executado em um tempo de execução do navegador no Word na Web, mas em um tempo de execução somente em JavaScript no Word no Windows. Para configurar esse padrão, um elemento Runtime é adicionado que aponta os tempos de execução do navegador para o arquivo commands.html do projeto. Esse elemento tem um elemento Override filho para Runtime que substitui o tipo "javascript" e aponta runtimes somente JavaScript para o arquivo commands.js . Para obter mais informações sobre runtimes para Suplementos do Office, consulte Runtimes em Suplementos do Office.
• No elemento ExtensionPoint , o xsi:type é definido como LaunchEvent. Isso habilita o recurso de ativação baseada em eventos no suplemento.
• No elemento SourceLocation do <elemento ExtensionPoint> , o resid valor é definido para corresponder ao elemento Runtime que faz referência ao arquivo HTML.
• No elemento LaunchEvent , o Type é definido como OnDocumentOpened e o FunctionName atributo é definido como o nome da função JavaScript do manipulador de eventos.
• Resources Na seção, o JsRuntimeWord.Url é definido como uma subpasta \public no aplicativo Web. Em conjunto com as alterações feitas no arquivo webpack.config.js , essa URL garante que o commands.js executado no runtime somente JavaScript não seja empacotado com código que exija um runtime de navegador. Consulte Configurar webpack.config.js.

Use o seguinte código de manifesto de exemplo para atualizar seu projeto.

1. No editor de códigos, abra o projeto de início rápido que você criou.

2. Abra o arquivo manifest.xml localizado na raiz do seu projeto.

3. Selecione todo <VersionOverrides> o nó (incluindo as marcas de abertura e fechamento) e substitua-o pelo XML a seguir.

     <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. Salve suas alterações.

Implementar o manipulador de eventos

Para permitir que o suplemento atue quando o OnDocumentOpened evento ocorrer, você deve implementar um manipulador de eventos JavaScript. Nesta seção, você criará a changeHeader função, que adiciona um cabeçalho "Público" a novos documentos ou um cabeçalho "Altamente Confidencial" a documentos existentes que já tenham conteúdo.

1. Na pasta ./src/commands , abra o arquivo chamado commands.js.

2. Substitua todo o conteúdo do commands.js pelo código JavaScript a seguir.

     /*
     * 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. Salve suas alterações.

Configurar webpack.config.js

O arquivo webpack.config.js precisa ser configurado para criar pacotes distintos do código JavaScript para tempos de execução somente JavaScript e navegador. Siga as etapas a seguir.

1. Adicione a linha a seguir à parte superior do arquivo em que os outros s globais constsão declarados.

   const path = require("path");
   

2. Para garantir que o ícone do suplemento possa aparecer na lista Aplicativos Integrados no portal de Administração Microsoft 365, adicione a propriedade a seguir ao objeto próximo à devServer parte inferior do arquivo.

   allowedHosts: "all",
   

3. Para garantir que o commands.js executado no runtime somente JavaScript não seja empacotado com código que exija um runtime de navegador, adicione a propriedade a seguir static ao devServer objeto.

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

   O objeto inteiro devServer agora deve ter a seguinte aparência.

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

Instalar a amostra para teste

1. Em um prompt de comando, navegue até a raiz do projeto.
2. Execute npm run build:dev.
3. Execute npm run dev-server.
4. No portal de administração do Microsoft 365, expanda a seção Configurações no painel de navegação e selecione Aplicativos integrados.
5. Na página Aplicativos integrados , escolha a ação Carregar aplicativos personalizados .
6. Na página Carregar aplicativos para implantar , selecione Suplemento do Office na lista suspensa Tipo de aplicativo .
7. Na seção Escolher como carregar o aplicativo , selecione Carregar arquivo de manifesto (.xml) do dispositivo.
8. Use o seletor de arquivos para navegar até a raiz do projeto e, em seguida, selecione o manifest.xml arquivo.
9. Selecione Apenas eu como usuário.
10. Siga as instruções na tela para concluir a implantação.

Experimente

1. No Word na Web ou no Word no Windows, tente abrir documentos novos e existentes do Word. Se o suplemento tiver se propagado para a plataforma, os cabeçalhos deverão ser adicionados automaticamente quando o documento for aberto, e deverá haver um botão Meu Suplemento em um grupo de suplementos ativado por Evento na guia Página Inicial da faixa de opções. Se essas coisas não acontecerem, a propagação para a plataforma não foi concluída. Feche o Word e tente novamente daqui a pouco.
2. Selecione o botão Meus suplementos para abrir o painel de tarefas.
3. Selecione qualquer um dos links no painel de tarefas para adicionar ou alterar o cabeçalho.

Desinstalar o suplemento

Para desinstalar o suplemento, siga as seguintes etapas:

1. No portal de administração do Microsoft 365, expanda a seção Configurações no painel de navegação e selecione Aplicativos integrados.
2. Na página Aplicativos integrados , selecione o suplemento.
3. No submenu do suplemento, selecione Remover aplicativo.
4. Na página Remover aplicativos , confirme que deseja remover o aplicativo e selecione Remover.
5. Na página Removidos com êxito , selecione Concluído.

Confira também

• Ativar suplementos com eventos
• Depurar suplementos baseados em eventos ou relatórios de spam
• Solucionar problemas de suplementos baseados em eventos e de relatórios de spam
• Runtimes em Suplementos do Office