Agregar encabezados al abrir un documento

Las siguientes secciones le explicarán cómo desarrollar un complemento de Word que cambie automáticamente el encabezado del documento cuando se abra un documento nuevo o existente. Aunque este complemento específico es para Word, la configuración del manifiesto y el archivo webpack.config.js es la misma para Excel y PowerPoint. Para obtener información general sobre este patrón de activación basada en eventos, consulte Activar complementos con eventos.

Crear un complemento

Cree un nuevo complemento siguiendo el Inicio rápido de complementos de Word, pero tenga en cuenta los siguientes cambios en los pasos que se describen allí.

• Siga las instrucciones para el manifiesto de solo complemento. El manifiesto unificado de Microsoft 365 aún no admite el OnDocumentOpened evento que se usa en este proyecto.
• Cuando Office le pida que elija un idioma, seleccione JavaScript.

Configuración del manifiesto

Para habilitar un complemento basado en eventos, debe configurar los siguientes elementos en el VersionOverridesV1_0 nodo del manifiesto. Tenga en cuenta lo siguiente sobre el nuevo marcado que se proporciona a continuación.

• El código que controla el OnDocumentOpened evento se ejecuta en un tiempo de ejecución del explorador en Word en la Web, pero en un tiempo de ejecución de solo JavaScript en Word en Windows. Para configurar este patrón, se agrega un elemento Runtime que señala los tiempos de ejecución del explorador al archivo commands.html del proyecto. Este elemento tiene un elemento secundario Override para Runtime que anula el tipo "javascript" y apunta los tiempos de ejecución solo de JavaScript al archivo commands.js . Para obtener más información sobre los entornos de ejecución de complementos de Office, consulte Entornos de ejecución en complementos de Office.
• En el elemento ExtensionPoint , se xsi:type establece en LaunchEvent. Esto habilita la característica de activación basada en eventos en el complemento.
• En el elemento SourceLocation del <elemento ExtensionPoint> , el resid valor se establece para que coincida con el del elemento Runtime que hace referencia al archivo HTML.
• En el elemento LaunchEvent , el Type atributo se establece en OnDocumentOpened el FunctionName nombre de función JavaScript del controlador de eventos.
• En la Resources sección, se JsRuntimeWord.Url establece en una subcarpeta \public en la aplicación web. Junto con los cambios que realizará en el archivo webpack.config.js , esta dirección URL garantiza que la commands.js que se ejecuta en el tiempo de ejecución de solo JavaScript no se incluya con código que requiera un tiempo de ejecución del explorador. Consulte Configurar webpack.config.js.

Use el siguiente código de manifiesto de ejemplo para actualizar el proyecto.

1. En el editor de código, abra el proyecto de inicio rápido que ha creado.

2. Abra el archivo manifest.xml ubicado en la raíz del proyecto.

3. Seleccione todo <VersionOverrides> el nodo (incluidas las etiquetas de apertura y cierre) y reemplácelo con el siguiente XML.

     <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. Guarde los cambios.

Implementar el controlador de eventos

Para permitir que el complemento actúe cuando se produce el OnDocumentOpened evento, debe implementar un controlador de eventos de JavaScript. En esta sección, creará la changeHeader función, que agrega un encabezado "Público" a los documentos nuevos o un encabezado "Extremadamente confidencial" a los documentos existentes que ya tienen contenido.

1. En la carpeta ./src/commands , abra el archivo denominado commands.js.

2. Reemplace todo el contenido de commands.js con el siguiente código JavaScript.

     /*
     * 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. Guarde los cambios.

Configurar webpack.config.js

El archivo webpack.config.js debe configurarse para que cree paquetes distintos del código JavaScript para los tiempos de ejecución del explorador y solo JavaScript. Ejecute los pasos siguientes.

1. Agregue la línea siguiente a la parte superior del archivo donde se declaran las otras s globales const.

   const path = require("path");
   

2. Para asegurarse de que el icono del complemento pueda aparecer en la lista Aplicaciones integradas del portal de Administración de Microsoft 365, agregue la siguiente propiedad al devServer objeto cerca de la parte inferior del archivo.

   allowedHosts: "all",
   

3. Para asegurarse de que el commands.js que se ejecuta en el tiempo de ejecución de solo JavaScript no se incluye con código que requiere un tiempo de ejecución del explorador, agregue la siguiente static propiedad al devServer objeto.

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

   Ahora todo el devServer objeto debería tener un aspecto similar al siguiente.

   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 el ejemplo para realizar pruebas

1. En un símbolo del sistema, vaya a la raíz del proyecto.
2. Ejecute npm run build:dev.
3. Ejecute npm run dev-server.
4. En el portal de administración de Microsoft 365, expanda la sección Configuración del panel de navegación y, a continuación, seleccione Aplicaciones integradas.
5. En la página Aplicaciones integradas , elija la acción Cargar aplicaciones personalizadas .
6. En la página Cargar aplicaciones para implementar , seleccione Complemento de Office en la lista desplegable Tipo de aplicación .
7. En la sección Elegir cómo cargar la aplicación , selecciona Cargar archivo de manifiesto (.xml) desde el dispositivo.
8. Use el selector de archivos para navegar a la raíz del proyecto y, a continuación, seleccione el manifest.xml archivo.
9. Seleccione Solo yo como usuario.
10. Siga las instrucciones que aparecen en pantalla para finalizar la implementación.

Pruébelo

1. En Word en la Web o en Word en Windows, intenta abrir documentos de Word nuevos y existentes. Si el complemento se ha propagado a la plataforma, los encabezados deberían agregarse automáticamente cuando se abra el documento y debería haber un botón Mi complemento en un grupo de complementos activado por evento en la pestaña Inicio de la cinta. Si estas cosas no suceden, la propagación a la plataforma no se ha completado. Cierre Word y vuelva a intentarlo más tarde.
2. Seleccione el botón Mis complementos para abrir el panel de tareas.
3. Seleccione cualquiera de los vínculos del panel de tareas para agregar o cambiar el encabezado.

Desinstalar el complemento

Para desinstalar el complemento, siga estos pasos:

1. En el portal de administración de Microsoft 365, expanda la sección Configuración del panel de navegación y, a continuación, seleccione Aplicaciones integradas.
2. En la página Aplicaciones integradas , seleccione el complemento.
3. En el control flotante del complemento, seleccione Quitar aplicación.
4. En la página Quitar aplicaciones , confirma que quieres quitar la aplicación y selecciona Quitar.
5. En la página Quitado correctamente , seleccione Listo.

Vea también

• Activar complementos con eventos
• Depurar complementos basados en eventos o de informes de correo no deseado
• Solucionar problemas de complementos basados en eventos e informes de correo no deseado
• Entornos de ejecución en complementos de Office