Tiempos de ejecución en complementos de Office

Los complementos de Office se ejecutan en tiempos de ejecución incrustados en Office. Como lenguaje interpretado, JavaScript debe ejecutarse en un entorno de ejecución de JavaScript. Node.js y los exploradores modernos son ejemplos de estos entornos de ejecución.

Tipos de tiempos de ejecución

Los complementos de Office usan dos tipos de tiempos de ejecución:

• Runtime de solo JavaScript: un motor de JavaScript complementado con compatibilidad con WebSockets, CORS completo (uso compartido de recursos entre orígenes) y almacenamiento de datos del lado cliente. No admite el almacenamiento local ni las cookies.
• Tiempo de ejecución del explorador: incluye todas las características de un entorno de ejecución solo de JavaScript y agrega compatibilidad con el almacenamiento local, un motor de representación que representa HTML y cookies.

Los detalles sobre estos tipos se detallan más adelante en este artículo en tiempo de ejecución solo para JavaScript y tiempo de ejecución del explorador.

En la tabla siguiente se muestran las posibles características de un complemento, según cada tipo de tiempo de ejecución.

En la tabla siguiente se muestra la misma información organizada por qué tipo de tiempo de ejecución se usa para las distintas características posibles de un complemento.

En Office en la web, todo se ejecuta siempre en un entorno de ejecución de tipo explorador. Con una excepción, todo lo que hay en un complemento en la web se ejecuta en el mismo proceso de explorador: el proceso del explorador en el que el usuario ha abierto Office en la web. La excepción es cuando se abre un cuadro de diálogo con una llamada de Office.ui.displayDialogAsync y la opción DialogOptions.displayInIFrameno se pasa y se establece en true. Cuando no se pasa la opción (por lo que tiene el valor predeterminado false ), el cuadro de diálogo se abre en su propio proceso. El mismo principio se aplica al método OfficeRuntime.displayWebDialog y a la opción OfficeRuntime.DisplayWebDialogOptions.displayInIFrame .

Cuando un complemento se ejecuta en una plataforma distinta de la web, se aplican los siguientes principios.

• Un cuadro de diálogo se ejecuta en su propio proceso en tiempo de ejecución.

• Un complemento de informes de correo no deseado o basado en eventos de Outlook se ejecuta en su propio proceso en tiempo de ejecución.

  Nota:

  La activación basada en eventos y las características integradas de informes de correo no deseado en Outlook deben usar el mismo tiempo de ejecución. Actualmente no se admiten varios entornos de ejecución en Outlook.

• De forma predeterminada, los paneles de tareas, los comandos de función y las funciones personalizadas de Excel se ejecutan en su propio proceso en tiempo de ejecución. Sin embargo, para algunas aplicaciones host de Office, el manifiesto del complemento se puede configurar para que dos o las tres se puedan ejecutar en el mismo tiempo de ejecución. Consulte Tiempo de ejecución compartido.

Dependiendo de la aplicación host de Office y de las características usadas en el complemento, puede haber muchos tiempos de ejecución en un complemento. Cada uno normalmente se ejecutará en su propio proceso, pero no necesariamente simultáneamente. Estos son algunos ejemplos.

• Un complemento de PowerPoint o Word que no comparte ningún entorno de ejecución, e incluye las siguientes características, tiene hasta tres tiempos de ejecución.

  • Un panel de tareas

  • Comando de función

  • Un cuadro de diálogo (se puede iniciar un cuadro de diálogo desde el panel de tareas o desde el comando de función).

    Nota:

    No es recomendable tener varios diálogos abiertos simultáneamente, pero si el complemento permite al usuario abrir uno desde el panel de tareas y otro desde el comando de función al mismo tiempo, este complemento tendría cuatro tiempos de ejecución. Un panel de tareas y una invocación determinada de un comando de función solo pueden tener un cuadro de diálogo abierto a la vez; pero si el comando de función se invoca varias veces, se abre un nuevo cuadro de diálogo encima de su predecesor con cada invocación, por lo que podría haber muchos tiempos de ejecución. El resto de esta lista omite la posibilidad de varios diálogos abiertos.

• Un complemento de Excel que no comparte ningún entorno de ejecución, e incluye las siguientes características, tiene hasta cuatro tiempos de ejecución.

  • Un panel de tareas
  • Comando de función
  • Una función personalizada
  • Un cuadro de diálogo (se puede iniciar un cuadro de diálogo desde el panel de tareas, el comando de función o una función personalizada).

• Un complemento de Excel con las mismas características y está configurado para compartir el mismo tiempo de ejecución en el panel de tareas, el comando de función y la función personalizada, tiene dos entornos de ejecución. Un entorno de ejecución compartido solo puede abrir un cuadro de diálogo a la vez.

• Un complemento de Excel con las mismas características, salvo que no tiene ningún cuadro de diálogo y está configurado para compartir el mismo tiempo de ejecución en el panel de tareas, el comando de función y la función personalizada, tiene un tiempo de ejecución.

• Un complemento de Outlook que tiene las siguientes características tiene hasta cuatro entornos de ejecución. Los entornos de ejecución compartidos no se admiten en Outlook.

  • Un panel de tareas
  • Comando de función
  • Una tarea basada en eventos o una característica integrada de informes de correo no deseado
  • Un cuadro de diálogo (un cuadro de diálogo se puede iniciar desde el panel de tareas o el comando de función, pero no desde una tarea basada en eventos).

Uso compartido de datos entre entornos de ejecución

En el caso de los complementos de Excel, PowerPoint y Word, use un entorno de ejecución compartido cuando dos o más características, excepto los cuadros de diálogo, necesiten compartir datos. En Outlook, o en escenarios en los que el uso compartido de un entorno de ejecución no es factible, necesita métodos alternativos. Las partes del complemento que están en procesos en tiempo de ejecución independientes no comparten datos globales automáticamente y son tratadas por el servidor de aplicaciones web del complemento como sesiones independientes, por lo que Window.sessionStorage no se puede usar para compartir datos entre ellos. En la siguiente guía se da por supuesto que no usa un entorno de ejecución compartido.

• Pase datos entre un cuadro de diálogo y su panel de tareas primario, comando de función o función personalizada mediante los métodos Office.ui.messageParent y Dialog.messageChild .

  Nota:

  No se puede llamar a los OfficeRuntime.storage métodos en un cuadro de diálogo, por lo que no es una opción para compartir datos entre un diálogo y otro entorno de ejecución.

• Para compartir datos entre un panel de tareas y un comando de función, almacene los datos en Window.localStorage, que se comparten en todos los entornos de ejecución que acceden al mismo origen específico.

  Nota:

  LocalStorage no es accesible en un entorno de ejecución solo de JavaScript y, por lo tanto, no está disponible en funciones personalizadas de Excel. Tampoco se puede usar para compartir datos con tareas basadas en eventos de Outlook (ya que esas tareas usan un entorno de ejecución solo javaScript en algunas plataformas).

  A partir de la versión 115 de los exploradores basados en Chromium, como Chrome y Edge, la creación de particiones de almacenamiento está habilitada para evitar el seguimiento entre sitios de canal lateral específico (consulte también las directivas del explorador Microsoft Edge). Esto significa que los datos almacenados por las API de almacenamiento, como el almacenamiento local, solo están disponibles para contextos con el mismo origen y el mismo sitio de nivel superior.

  Sugerencia

  Los datos de Window.localStorage se conservan entre sesiones del complemento y los comparten los complementos con el mismo origen. Ambas características suelen ser indeseables para un complemento.

  • Para asegurarse de que cada sesión de un complemento determinado se inicia de nuevo, llame al método Window.localStorage.clear cuando se inicie el complemento.
  • Para permitir que algunos valores almacenados se conserven, pero reinicialicen otros valores, use Window.localStorage.setItem cuando se inicie el complemento para cada elemento que se debe restablecer a un valor inicial.
  • Para eliminar un elemento por completo, llame a Window.localStorage.removeItem.

• Para compartir datos entre una función personalizada de Excel y cualquier otro entorno de ejecución, use OfficeRuntime.storage.

• Para compartir datos entre una tarea basada en eventos de Outlook y un panel de tareas o un comando de función, debe bifurcar el código por el valor de la propiedad Office.context.platform .

  • Cuando el valor es PC (Windows), almacene y recupere datos mediante las API Office.sessionData .
  • Cuando el valor sea Mac, use Window.localStorage como se describió anteriormente en esta lista.

Entre otras formas de compartir datos se incluyen las siguientes:

• Almacene datos compartidos en una base de datos en línea a la que puedan acceder todos los entornos de ejecución.
• Almacene los datos compartidos en una cookie para que el dominio del complemento los comparta entre los entornos de ejecución del explorador. Los tiempos de ejecución solo de JavaScript no admiten cookies.

Para obtener más información, vea Persist add-in state and settings (Conservar el estado y la configuración del complemento ) y Get and set add-in metadata for an Outlook add-in (Obtener y establecer metadatos de complemento para un complemento de Outlook).

Tiempo de ejecución de solo JavaScript

El tiempo de ejecución de solo JavaScript que se usa en complementos de Office es una modificación de un entorno de ejecución de código abierto creado originalmente para React Native. Contiene un motor de JavaScript complementado con compatibilidad con WebSockets, CORS completo (uso compartido de recursos entre orígenes) y OfficeRuntime.storage. No tiene un motor de representación y no admite cookies ni almacenamiento local.

Este tipo de tiempo de ejecución se usa en complementos de informes de correo no deseado y basados en eventos solo en Outlook clásico en Windows y en funciones personalizadas de Excel , excepto cuando las funciones personalizadas comparten un entorno de ejecución.

• Cuando se usa para una función personalizada de Excel, el tiempo de ejecución se inicia cuando se vuelve a calcular la hoja de cálculo o la función personalizada. No se cierra hasta que se cierra el libro.

• Cuando se usa en un complemento de informes de correo no deseado o basado en eventos de Outlook, el tiempo de ejecución se inicia cuando se produce el evento. Finaliza cuando se produce la primera de las siguientes acciones.

  • El controlador de eventos llama al completed método de su parámetro de evento.
  • Han transcurrido cinco minutos desde el evento desencadenante.
  • El usuario cambia el foco de la ventana donde se desencadenó el evento, como una ventana de redacción de mensajes (solo se aplica a complementos basados en eventos).

  Nota:

  La activación basada en eventos y las características integradas de informes de correo no deseado en Outlook deben usar el mismo tiempo de ejecución. Actualmente no se admiten varios entornos de ejecución en Outlook.

Un entorno de ejecución solo de JavaScript usa menos memoria y se inicia más rápido que un tiempo de ejecución del explorador, pero tiene menos características.

Tiempo de ejecución del explorador

Los complementos de Office usan un entorno de ejecución de tipo de explorador diferente en función de la plataforma en la que se ejecuta Office (web, Mac o Windows) y de la versión y compilación de Windows y Office. Por ejemplo, si el usuario ejecuta Office en la web en un explorador FireFox, se usa el entorno de ejecución de Firefox. Si el usuario ejecuta Office en Mac, se usa el entorno de ejecución de Safari. Si el usuario ejecuta Office en Windows, una instancia de Edge o Internet Explorer proporciona el tiempo de ejecución, en función de la versión de Windows y Office. Los detalles se pueden encontrar en Exploradores y controles de vista web que usan los complementos de Office.

Todos estos entornos de ejecución incluyen un motor de representación HTML y proporcionan compatibilidad con WebSockets, CORS completo (uso compartido de recursos entre orígenes) y almacenamiento local y cookies.

La duración del tiempo de ejecución del explorador varía en función de la característica que implemente y de si se comparte o no.

• Cuando se inicia un complemento con un panel de tareas, se inicia un tiempo de ejecución del explorador, a menos que sea un entorno de ejecución compartido que ya se esté ejecutando. Si se trata de un entorno de ejecución compartido, se cierra cuando se cierra el documento. Si no es un entorno de ejecución compartido, se cierra cuando se cierra el panel de tareas.

• Cuando se abre un cuadro de diálogo, se inicia un tiempo de ejecución del explorador. Se cierra cuando se cierra el cuadro de diálogo.

• Cuando se ejecuta un comando de función (lo que sucede cuando un usuario selecciona su botón o elemento de menú), se inicia un tiempo de ejecución del explorador, a menos que sea un entorno de ejecución compartido que ya se esté ejecutando. Si se trata de un entorno de ejecución compartido, se cierra cuando se cierra el documento. Si no es un entorno de ejecución compartido, se cierra cuando se produce el primero de los siguientes.

  • El comando function llama al completed método de su parámetro de evento.
  • Han transcurrido cinco minutos desde el evento desencadenante. (Si se abrió un cuadro de diálogo en el comando de función y sigue abierto cuando el tiempo de ejecución primario agota el tiempo de espera, el tiempo de ejecución del cuadro de diálogo permanece en ejecución hasta que se cierra el cuadro de diálogo).

• Cuando una función personalizada de Excel usa un entorno de ejecución compartido, se inicia un tiempo de ejecución de tipo explorador cuando la función personalizada calcula si el tiempo de ejecución compartido aún no se ha iniciado por algún otro motivo. Se cierra cuando se cierra el documento.

Un entorno de ejecución del explorador tiene más características que un entorno de ejecución solo de JavaScript, pero se inicia más lentamente y usa más memoria.

Tiempo de ejecución compartido

Un "tiempo de ejecución compartido" no es un tipo de tiempo de ejecución. Hace referencia a un tiempo de ejecución de tipo explorador que comparten las características del complemento que, de lo contrario, cada uno tendría su propio tiempo de ejecución. En concreto, tiene la opción de configurar el panel de tareas del complemento y los comandos de función para compartir un entorno de ejecución. En un complemento de Excel, también puede configurar funciones personalizadas para compartir el tiempo de ejecución de un panel de tareas o un comando de función o ambos. Al hacerlo, las funciones personalizadas se ejecutan en un entorno de ejecución de tipo explorador, en lugar de en un entorno de ejecución solo de JavaScript como lo haría en caso contrario. Consulte Configuración del complemento para usar un entorno de ejecución compartido para obtener información sobre las ventajas y limitaciones del uso compartido de tiempos de ejecución e instrucciones para configurar el complemento para usar un entorno de ejecución compartido. En resumen, el entorno de ejecución de solo JavaScript usa menos memoria y se inicia más rápido, pero tiene menos características.