Configuración del complemento de Office para usar un entorno de ejecución compartido

Importante

El entorno de ejecución compartido solo se admite en algunas aplicaciones de Office. Para obtener más información, vea Conjuntos de requisitos de runtime compartido.

Puede configurar el complemento de Office para ejecutar todo su código en un único entorno de ejecución compartido. Esto permite una mayor coordinación para todo el complemento y el acceso a DOM y CORS desde todas las partes del complemento. Esto también habilita características adicionales como ejecutar el código cuando se abre el documento, o habilitar o deshabilitar los botones de la cinta de opciones. Para configurar el complemento para que use un tiempo de ejecución compartido, siga las instrucciones de este artículo.

Creación del proyecto de complemento

Si va a iniciar un proyecto nuevo, use el generador Yeoman para complementos de Office, con el fin de crear un proyecto de complemento de Excel o PowerPoint.

Ejecute el comando yo office --projectType taskpane --name "my office add in" --host <host> --js true, donde <host> es uno de los valores siguientes.

• Excel
• PowerPoint
• Word

Importante

El valor del argumento --name debe estar entre comillas dobles, incluso si no tiene espacios.

Puede usar diferentes opciones para las opciones de línea de comandos --projecttype, --name y --js. Para obtener la lista completa de opciones, consulte Generador de Yeoman para complementos de Office.

El generador creará el proyecto e instalará los componentes auxiliares de Node. También puede usar los pasos de este artículo para actualizar un proyecto de Visual Studio y usar el entorno de ejecución compartido. Sin embargo, es posible que tenga que actualizar los esquemas XML para el manifiesto. Para obtener más información, vea Solucionar errores de desarrollo con complementos de Office.

Configuración del manifiesto

Siga estos pasos para configurar un proyecto nuevo o existente para que use un tiempo de ejecución compartido. En estos pasos, se supone que ya ha generado el proyecto con el generador Yeoman para complementos de Office.

1. Inicie Visual Studio Code y abra el proyecto de complemento de Excel o PowerPoint que ha generado.

2. Abra el archivo manifest.xml.

3. Para un complemento de Excel o PowerPoint, actualice la sección de requisitos para incluir el entorno de ejecución compartido. Asegúrese de quitar el requisito CustomFunctionsRuntime si este está presente. El archivo XML debería aparecer de la siguiente manera.

   <Hosts>
     <Host Name="Workbook"/>
   </Hosts>
   <Requirements>
     <Sets DefaultMinVersion="1.1">
       <Set Name="SharedRuntime" MinVersion="1.1"/>
     </Sets>
   </Requirements>
   <DefaultSettings>
   

4. Busque la <sección VersionOverrides> y agregue la siguiente <sección Runtimes> . El ciclo de vida debe establecerse en long para que el código del complemento pueda ejecutarse incluso cuando se cierre el panel de tareas. El valor resid es Taskpane.Url, lo que hace referencia a la ubicación del archivo taskpane.html especificada en la sección <bt:Urls> cerca de la parte inferior del archivo manifest.xml.

   Importante

   El tiempo de ejecución compartido no se cargará si usa resid valores diferentes en el manifiesto. Si cambia el valor a algo distinto de Taskpane.Url, asegúrese de cambiar también el valor en todas las ubicaciones que se muestran en los pasos siguientes de este artículo.

   Además, la <sección Runtimes> debe especificarse después del <elemento Host> en el orden exacto que se muestra en el siguiente XML.

   <VersionOverrides ...>
     <Hosts>
       <Host ...>
         <Runtimes>
           <Runtime resid="Taskpane.Url" lifetime="long" />
         </Runtimes>
       ...
       </Host>
   

5. Si ha generado un complemento de Excel con funciones personalizadas, busque el <elemento Page> . Luego, cambie la ubicación de origen de Functions.Page.Url a TaskPane.Url.

   <AllFormFactors>
   ...
   <Page>
     <SourceLocation resid="Taskpane.Url"/>
   </Page>
   ...
   

6. Busque la <etiqueta FunctionFile> y cambie resid de Commands.Url a Taskpane.Url. Tenga en cuenta que si no tiene comandos de acción, no tendrá una <entrada FunctionFile> y puede omitir este paso.

   </GetStarted>
   ...
   <FunctionFile resid="Taskpane.Url"/>
   ...
   

7. Guarde el archivo manifest.xml.

Configuración del archivo webpack.config.js

El archivo webpack.config.js generará varios cargadores de tiempo de ejecución. Debe modificarlo para cargar solo el entorno de ejecución compartido a través del archivo taskpane.html .

1. Inicie Visual Studio Code y abra el proyecto de complemento de Excel o PowerPoint que ha generado.

2. Abra el archivo webpack.config.js.

3. Si el archivo webpack.config.js tiene el siguiente código de complemento functions.html, quítelo.

   new HtmlWebpackPlugin({
       filename: "functions.html",
       template: "./src/functions/functions.html",
       chunks: ["polyfill", "functions"]
     })
   

4. Si el archivo webpack.config.js tiene el siguiente código de complemento commands.html, quítelo.

   new HtmlWebpackPlugin({
       filename: "commands.html",
       template: "./src/commands/commands.html",
       chunks: ["polyfill", "commands"]
     })
   

5. Si su proyecto ha usado los segmentos functions o commands, agréguelos a la lista de fragmentos como se muestra a continuación (el siguiente código se usa si el proyecto usa ambos fragmentos).

     new HtmlWebpackPlugin({
       filename: "taskpane.html",
       template: "./src/taskpane/taskpane.html",
       chunks: ["polyfill", "taskpane", "commands", "functions"]
     })
   

6. Guarde los cambios y recompile el proyecto.

   npm run build
   

Nota:

Si su proyecto tiene un archivo functions.html o commands.html, ambos se pueden quitar. El taskpane.html cargará el códigofunctions.js y commands.js en el entorno de ejecución compartido a través de las actualizaciones de webpack que acaba de realizar.

Prueba de los cambios en el complemento de Office

Puede confirmar que usa el entorno de ejecución compartido correctamente mediante las siguientes instrucciones.

1. Abra el archivo CustomStrings.js.

2. Reemplace todo el contenido del archivo por el siguiente código. Esto mostrará un recuento del número de veces que se ha abierto el panel de tareas. Agregar el evento onVisibilityModeChanged solo se admite en un entorno de ejecución compartido.

   /*global document, Office*/
   
   let _count = 0;
   
   Office.onReady(() => {
     document.getElementById("sideload-msg").style.display = "none";
     document.getElementById("app-body").style.display = "flex";
   
     updateCount(); // Update count on first open.
     Office.addin.onVisibilityModeChanged(function (args) {
       if (args.visibilityMode === "Taskpane") {
         updateCount(); // Update count on subsequent opens.
       }
     });
   });
   
   function updateCount() {
     _count++;
     document.getElementById("run").textContent = "Task pane opened " + _count + " times.";
   }
   

3. Guarde los cambios y ejecute el proyecto.

   npm start
   

Cada vez que abra el panel de tareas, se incrementará el recuento de veces que se ha abierto. El valor de _count no se perderá porque el tiempo de ejecución compartido mantiene el código en ejecución incluso cuando se cierra el panel de tareas.

Cuando esté listo para detener el servidor de desarrollo y desinstalar el complemento, ejecute el siguiente comando.

npm stop

Duración de tiempo de ejecución

Al agregar el <elemento Runtime> , también se especifica una duración con un valor de long o short. Configure este valor en long para aprovechar características, por ejemplo, para iniciar el complemento al abrir el documento, seguir ejecutando el código después de cerrar el panel de tareas o usar CORS y DOM desde las funciones personalizadas.

Nota:

El valor de duración predeterminado es short, pero se recomienda usar long en los complementos de Excel, PowerPoint y Word. Si ajusta su runtime a short en este ejemplo, su complemento se iniciará cuando se pulse uno de sus botones de la cinta de opciones, pero podría cerrarse después de que se haya terminado de ejecutar el controlador de la cinta de opciones. De forma similar, el complemento se iniciará cuando se abra el panel de tareas, pero puede apagarse cuando se cierre el mismo.

<Runtimes>
  <Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>

Nota:

Si el complemento incluye el <elemento Runtimes> en el manifiesto (necesario para un entorno de ejecución compartido) y se cumplen las condiciones para usar WebView2 (basado en Microsoft Edge Chromium), usa ese control. Si no se cumplen las condiciones, usa el control de vista web Trident (Internet Explorer 11), independientemente de la versión de Windows o Microsoft 365. Para obtener más información, vea Runtimes and Browsers and webview controls used by Office Add-ins.

Acerca del entorno de ejecución compartido

En Windows o en Mac, el complemento ejecutará código para botones de cinta de opciones, funciones personalizadas y el panel de tareas en entornos en tiempo de ejecución independientes. Esto crea limitaciones, como el no poder compartir fácilmente datos globales y no poder acceder a todas las funcionalidades de CORS desde una función personalizada.

Sin embargo, puede configurar el complemento de Office para que comparta código en el mismo tiempo de ejecución (también denominado tiempo de ejecución compartido). Esto permite una mayor coordinación para todo el complemento y el acceso al panel de tareas DOM y CORS desde todas las partes del complemento.

La configuración de un tiempo de ejecución compartido habilita los siguientes escenarios.

• El complemento de Office puede usar características adicionales de la interfaz de usuario:
  • Habilitar y deshabilitar comandos de complementos
  • Ejecutar código en el complemento de Office cuando se abre el documento
  • Mostrar u ocultar el panel de tareas de su complemento de Office
• Las siguientes opciones solo están disponibles para Excel complementos.
  • Agregar métodos abreviados de teclado personalizados a los complementos de Office
  • Creación de pestañas contextuales personalizadas en complementos de Office
  • Las funciones personalizadas tendrán el soporte técnico completo de CORS.
  • Las funciones personalizadas pueden llamar a las API de Office.js para leer datos de los documentos de hojas de cálculo.

Para Office en Windows, el entorno de ejecución compartido usa WebView2 (basado en microsoft Edge Chromium) si se cumplen las condiciones para usarlo, como se explica en Exploradores y controles de vista web que usan los complementos de Office. De lo contrario, usa Trident (Internet Explorer 11). Además, todos los botones que muestre su complemento en la cinta de opciones se ejecutarán en el mismo tiempo de ejecución compartido. En la imagen siguiente se muestra cómo se ejecutarán todas las funciones personalizadas, la interfaz de usuario de la cinta de opciones y el código del panel de tareas en el mismo tiempo de ejecución.

Paneles de tareas múltiples

No diseñe el complemento para usar paneles de tareas múltiples si piensa usar un tiempo de ejecución compartido. Un tiempo de ejecución compartido solo admite el uso de un panel de tareas. Tenga en cuenta que todos los paneles de tareas que no tengan <TaskpaneID> se consideran como un panel de tareas distinto.

Vea también

• Llamar a las API de Excel desde una función personalizada
• Agregar métodos abreviados de teclado personalizados a los complementos de Office
• Creación de pestañas contextuales personalizadas en complementos de Office
• Habilitar y deshabilitar comandos de complementos
• Ejecutar código en el complemento de Office cuando se abre el documento
• Mostrar u ocultar el panel de tareas de su complemento de Office
• Tutorial: compartir datos y eventos entre funciones personalizadas de Excel y el panel de tareas
• Tiempos de ejecución en complementos de Office