Activar complementos con eventos

La activación basada en eventos permite que el complemento se inicie automáticamente en respuesta a eventos, de modo que pueda validar, insertar o actualizar contenido crítico sin la acción directa del usuario. El complemento se activa en segundo plano para evitar molestar al usuario. También puede integrar la activación basada en eventos con los paneles de tareas y los comandos de función.

Información general

Aunque los pasos concretos para agregar funcionalidad basada en eventos al complemento varían según la plataforma y el tipo de manifiesto, el flujo general es el siguiente.

1. Actualice el manifiesto para asignar una acción para controlar el evento.
2. Cree una función JavaScript y asegúrese de que llama al método event.completed .
3. Use el método Office.actions.associate para asignar la función a la acción especificada en el manifiesto.

Probar la activación basada en eventos

Descubre cómo simplificar los flujos de trabajo y mejorar las experiencias de los usuarios con la activación basada en eventos. Pruebe los ejemplos para ver la característica en acción.

Ejemplos de Outlook

• Establecer automáticamente el asunto de un nuevo mensaje o cita
• Buscar automáticamente datos adjuntos antes de enviar un mensaje
• Actualizar automáticamente la firma al cambiar entre cuentas de correo
• Cifre datos adjuntos, procese asistentes a convocatorias de reunión y reaccione a los cambios de fecha y hora de las citas mediante la activación basada en eventos de Outlook
• Establecer la firma usando la activación basada en eventos de Outlook
• Identificar y etiquetar destinatarios externos con la activación basada en eventos de Outlook
• Verificar las categorías de color de un mensaje o cita antes de enviarlo mediante alertas inteligentes
• Comprobar la etiqueta de confidencialidad de un mensaje

Ejemplos de Word

• Agregar encabezados al abrir un documento

Eventos compatibles

En las tablas siguientes se enumeran los eventos que están disponibles actualmente y los clientes admitidos para cada evento. Cuando se genera un evento, el controlador recibe un event objeto que puede incluir detalles específicos para el tipo de evento. La columna Descripción incluye un vínculo al objeto relacionado cuando corresponde.

Eventos de Excel, PowerPoint y Word

Nombre canónico del evento y nombre del manifiesto solo del complemento	Nombre del manifiesto unificado para Microsoft 365	Description	Clientes y canales admitidos
OnDocumentOpened	No compatible aún`	Se produce cuando un usuario abre un documento o crea un nuevo documento, hoja de cálculo o presentación.	Office en la web Office en Windows Office en Mac estará disponible más adelante

Para obtener un ejemplo de un complemento que se activa con este evento, vea word-add-label-on-open.

Sugerencia

Al usar el OnDocumentOpened evento, se puede configurar un complemento en el manifiesto para ejecutar código cuando se abra cualquier documento. Esta característica tiene ámbito de aplicación de Office. Una vez instalado el complemento por un administrador de Microsoft 365 en el portal de Administración del inquilino de Microsoft 365, el complemento se inicia y ejecuta código en cada documento de Office que se abre en las aplicaciones de Office para las que el complemento, en el manifiesto, está configurado. Esta característica es distinta de tres características similares:

• Un complemento puede configurarse a sí mismo mediante programación para ejecutar código cuando se abre un documento. La técnica tiene alcance documental, lo que significa que debe aplicarse a cada documento individualmente. Para obtener más información, vea Configurar un documento para que ejecute el código cuando se abre.
• Un complemento puede configurar mediante programación un documento para abrir automáticamente el panel de tareas del complemento cuando se abra el documento. Esta característica también debe aplicarse a cada documento individualmente. Para obtener más información, vea Abrir automáticamente un panel de tareas con un documento.
• Se puede configurar un complemento en el manifiesto para abrir su panel de tareas cuando un usuario final instala el complemento . Esta característica se limita a un único documento: el que está abierto cuando se instala el complemento. Para obtener más información, vea Abrir automáticamente un panel de tareas cuando se instala un complemento.

Eventos de Outlook

La compatibilidad con esta característica en Outlook se introdujo en el conjunto de requisitos 1.10, con eventos adicionales ahora disponibles en conjuntos de requisitos posteriores. En la tabla siguiente se enumeran los requisitos mínimos establecidos para cada evento, así como los clientes y plataformas que lo admiten. Para obtener más información sobre los clientes de Outlook y los conjuntos de requisitos que admiten, consulte Conjuntos de requisitos admitidos por servidores Exchange y clientes de Outlook.

Nombre canónico del evento y nombre del manifiesto solo del complemento	Nombre del manifiesto unificado para Microsoft 365	Description	Conjunto de requisitos mínimos y clientes compatibles
OnNewMessageCompose	newMessageComposeCreated	Al redactar un mensaje nuevo (incluye responder, responder a todos y reenviar), pero no al editar, por ejemplo, un borrador.	1.10 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac Android23 iOS23
OnNewAppointmentOrganizer	newAppointmentOrganizerCreated	Al crear una nueva cita pero no al editar una existente.	1.10 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnMessageAttachmentsChanged	messageAttachmentsChanged	Sobre cómo agregar o quitar datos adjuntos al redactar un mensaje. Objeto de datos específico del evento: AttachmentsChangedEventArgs	1.11 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnAppointmentAttachmentsChanged	appointmentAttachmentsChanged	Sobre cómo agregar o quitar datos adjuntos al redactar una cita. Objeto de datos específico del evento: AttachmentsChangedEventArgs	1.11 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnMessageRecipientsChanged	messageRecipientsChanged	Sobre cómo agregar o quitar destinatarios al redactar un mensaje. Objeto de datos específicos del evento: RecipientsChangedEventArgs	1.11 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac Android23 iOS23
OnAppointmentAttendeesChanged	appointmentAttendeesChanged	Sobre agregar o quitar asistentes durante la redacción de una cita. Objeto de datos específicos del evento: RecipientsChangedEventArgs	1.11 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnAppointmentTimeChanged	appointmentTimeChanged	Al cambiar la fecha y la hora al redactar una cita. Objeto de datos específico del evento: AppointmentTimeChangedEventArgs Importante: Si arrastra y coloca una cita en una franja horaria de fecha y hora diferente en el calendario, el OnAppointmentTimeChanged evento no se produce. Solo se produce cuando la fecha y la hora se cambian directamente de una cita.	1.11 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnAppointmentRecurrenceChanged	appointmentRecurrenceChanged	Al agregar, cambiar o quitar los detalles de periodicidad al redactar una cita. Si se cambia la fecha y la hora, el OnAppointmentTimeChanged evento también se produce. Objeto de datos específico del evento: RecurrenceChangedEventArgs	1.11 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnInfoBarDismissClicked	infoBarDismissClicked	Al descartar una notificación mientras se redacta un mensaje o un elemento de cita. Solo se notificará al complemento que agregó la notificación. Objeto de datos específico del evento: InfobarClickedEventArgs	1.11 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnMessageSend	mensajeSending	Al enviar un elemento de mensaje. Para obtener más información, pruebe el tutorial de alertas inteligentes.	1.12 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnAppointmentSend	appointmentSending	Al enviar un elemento de cita. Para obtener más información, consulte Controlar eventos OnMessageSend y OnAppointmentSend en el complemento de Outlook con alertas inteligentes.	1.12 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnMessageCompose	messageComposeOpened	Al redactar un mensaje nuevo (incluye responder, responder a todos y reenviar) o editar un borrador.	1.12 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnAppointmentOrganizer	appointmentOrganizerOpened	Al crear una cita nueva o editar una existente.	1.12 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnMessageFromChanged	messageFromChanged	Al cambiar la cuenta de correo en el campo "De " de un mensaje que se está redactando. Para obtener más información, consulte Actualizar automáticamente la firma al cambiar entre cuentas de Exchange.	1.13 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac Android23 iOS23
OnAppointmentFromChanged	appointmentFromChanged	Al cambiar la cuenta de correo en el campo organizador de una cita que se está redactando. Para obtener más información, consulte Actualizar automáticamente la firma al cambiar entre cuentas de Exchange.	1.13 Nueva interfaz de usuario2 de Mac
OnSensitivityLabelChanged	sensitivityLabelChanged	Al cambiar la etiqueta de confidencialidad al redactar un mensaje o una cita. Para obtener información sobre cómo administrar la etiqueta de confidencialidad de un elemento de correo, vea Administrar la etiqueta de confidencialidad de su mensaje o cita en modo de redacción. Objeto de datos específico del evento: SensitivityLabelChangedEventArgs	1.13 Explorador web Windows (nuevo y clásico1) Nueva interfaz de usuario2 de Mac
OnMessageReadWithCustomAttachment	No disponible	Al abrir un mensaje que contiene un tipo de datos adjuntos específico en modo lectura.	Vista previa4 Windows (clásico1)
OnMessageReadWithCustomHeader	No disponible	Al abrir un mensaje que contiene un nombre de encabezado de Internet específico en modo lectura.	Vista previa4 Windows (clásico1)
OnMessageDecrypt	messageDecrypt	Al hacer coincidir el encabezado de un mensaje cifrado con la clave de encabezado en el manifiesto de un complemento. Para obtener más información, consulte Crear un complemento de cifrado de Outlook.	1.16 Explorador web Windows (nuevo y clásico1)

Nota:

¹ Para ejecutar los complementos basados en eventos en Outlook en Windows clásico, se requiere un mínimo de Windows 10 versión 1903 (compilación 18362) o Windows Server versión 1903 de 2019.

² Los complementos que usan el manifiesto unificado para Microsoft 365 no son compatibles con Outlook en Mac y en dispositivos móviles. Para que el complemento esté disponible en Mac y en plataformas móviles, debe crear una segunda versión que use únicamente el manifiesto del complemento. Para obtener más información, consulte la sección "Soporte técnico de cliente y plataforma" de Complementos de Office con el manifiesto de aplicación unificado para Microsoft 365.

³ Para obtener más información, vea Implementar la activación basada en eventos en complementos móviles de Outlook.

⁴ Para obtener una vista previa de los OnMessageReadWithCustomAttachment eventos y OnMessageReadWithCustomHeader , debe instalar Outlook clásico en Windows versión 2312 (compilación 17110.10000) o posterior. A continuación, únase al programa Microsoft 365 Insider y seleccione la opción de canal beta para acceder a las compilaciones beta de Office.

Activación basada en eventos en Outlook para dispositivos móviles

Outlook en dispositivos móviles admite API hasta el conjunto de requisitos de buzón 1.5. Sin embargo, ahora se ha habilitado la compatibilidad con API y características adicionales que se introdujeron en conjuntos de requisitos posteriores, como el OnNewMessageCompose evento. Para obtener más información, consulte Implementar la activación basada en eventos en complementos móviles de Outlook.

Comportamiento y limitaciones

Al desarrollar un complemento basado en eventos, tenga en cuenta los siguientes comportamientos y limitaciones de características.

• Los complementos basados en eventos solo funcionan cuando los implementa un administrador. Si los usuarios los instalan directamente desde Microsoft Marketplace o la Tienda Office, no se iniciarán automáticamente (para obtener soluciones alternativas a la limitación de Microsoft Marketplace, consulte Opciones de lista de Microsoft Marketplace para el complemento basado en eventos). Las implementaciones de Administración se realizan cargando el manifiesto en el Centro de administración de Microsoft 365.

• Las API que interactúan con la interfaz de usuario o muestran elementos de la interfaz de usuario no son compatibles con Word, PowerPoint y Excel. Esto se debe a que el controlador de eventos se ejecuta en un tiempo de ejecución de solo JavaScript. Para obtener más información, vea Entornos de ejecución en complementos de Office.

• Los complementos basados en eventos requieren una conexión a Internet para poder iniciarse cuando se produce un evento específico. Se espera que los controladores de eventos de complemento sean de corta duración, ligeros y lo menos invasivos posible. Después de la activación, el complemento agotará el tiempo de espera en aproximadamente 300 segundos, el período máximo de tiempo permitido para ejecutar complementos basados en eventos. Para indicar que el complemento ha completado el procesamiento de un evento de lanzamiento, el controlador de eventos asociado debe llamar al método event.completed . (Tenga en cuenta que no se garantiza que el código que se incluye después de la event.completed instrucción se ejecute). Cada vez que se desencadena un evento que controla el complemento, se reactiva el complemento y se ejecuta el controlador de eventos asociado, y se restablece la ventana de tiempo de espera. El complemento finaliza después de que se agote el tiempo de espera, o cuando el usuario cierre la ventana de redacción o envíe el elemento.

• El comportamiento de varios complementos que se suscriben al mismo evento no es determinista. Outlook inicia los complementos sin ningún orden en particular. Para Excel, PowerPoint y Word, solo se activará un complemento aleatorio. Por ejemplo, si hay varios complementos de Word que controlan OnDocumentOpened, solo se ejecutará uno de esos controladores.

• Actualmente, solo se pueden ejecutar activamente cinco complementos basados en eventos.

• En todos los clientes de Outlook compatibles, el usuario debe permanecer en el elemento de correo actual en el que se activó el complemento para que se complete la ejecución. La navegación fuera del elemento actual (por ejemplo, cambiar a otra ventana o pestaña de redacción) finaliza la operación del complemento. Sin embargo, un complemento que se activa en el evento controla el OnMessageSend cambio de elemento de forma diferente en función del cliente de Outlook en el que se ejecute. Para obtener más información, consulte la sección "El usuario se aleja del mensaje actual" de los eventos Controlar OnMessageSend y OnAppointmentSend en el complemento de Outlook con alertas inteligentes.

• Además del cambio de elemento, un complemento basado en eventos también deja de funcionar cuando el usuario envía el mensaje o la cita que está redactando.

Limitaciones de complementos basados en eventos en Excel, PowerPoint, Word y Outlook clásico en Windows

Al desarrollar un complemento basado en eventos para que se ejecute en un cliente Windows, tenga en cuenta lo siguiente:

• Las importaciones no se admiten en el archivo JavaScript, donde implementa el control para la activación basada en eventos.

• Solo se admite el archivo JavaScript al que se hace referencia en el manifiesto para la activación basada en eventos. Debe agrupar el código JavaScript de control de eventos en este único archivo. La ubicación del archivo JavaScript al que se hace referencia en el manifiesto varía en función del tipo de manifiesto que use el complemento.

  • Manifiesto solo de complemento: <Override> elemento secundario del <Runtime> nodo
  • Manifiesto unificado para Microsoft 365: "script" propiedad del "code" objeto

  Ten en cuenta que un paquete grande de JavaScript puede causar problemas con el rendimiento del complemento. Se recomienda preprocesar las operaciones pesadas para que no se incluyan en el código de control de eventos.

• Cuando se ejecuta la función de JavaScript especificada en el manifiesto para controlar un evento, se codifica Office.onReady() y Office.initialize no se ejecuta. En su lugar, recomendamos agregar a los controladores de eventos cualquier lógica de inicio que necesiten los controladores de eventos, como comprobar la versión de cliente del usuario.

• En Outlook, al redactar un mensaje iniciado por un vínculo de correo electrónico de retorno (mailto vínculo), recuperar los destinatarios del campo Para, CC o CCO en el controlador de OnNewMessageCompose eventos puede devolver una matriz vacía. Esto sucede si Outlook no ha completado la resolución de las direcciones de correo electrónico de los destinatarios en el momento en que se produce el OnNewMessageCompose evento. Para solucionar este problema, compruebe si hay destinatarios en el controlador de OnMessageRecipientsChanged eventos.

Limitaciones de complementos basados en eventos en Excel, PowerPoint y Word

Las siguientes plataformas o características aún no son compatibles.

• Office en Mac

Limitaciones de complementos basados en eventos en Outlook en la Web y en el nuevo Outlook en Windows

En Outlook en la Web y en el nuevo Outlook en Windows, la activación basada en eventos solo se admite en superficies estándar de lectura y redacción de mensajes y citas. Es posible que la activación basada en eventos no funcione al redactar en algunas superficies no estándar. Por ejemplo:

• Responder a una invitación a una reunión mediante la opción RSVP with note .
• Reenviar una reunión desde el calendario.

API no compatibles

Algunas API de Office.js que cambian o alteran la interfaz de usuario no están permitidas en los controladores de eventos de complementos basados en eventos. Las siguientes son API bloqueadas.

API	Métodos
Office.devicePermission	requestPermissionsAsync
Office.context.auth*	getAccessToken getAccessTokenAsync
Office.context.mailbox	displayAppointmentForm displayMessageForm displayNewAppointmentForm displayNewMessageForm
Office.context.mailbox.item	close
Office.context.ui	displayDialogAsync messageParent

Nota:

* OfficeRuntime.auth se admite en todas las versiones que admiten la activación basada en eventos y el inicio de sesión único (SSO), mientras que Office.auth solo se admite en determinadas compilaciones de Outlook. Para obtener más información, consulte Usar el inicio de sesión único (SSO) o el uso compartido de recursos entre orígenes (CORS) en el complemento de Outlook basado en eventos o de informes de spam.

Características de vista previa en controladores de eventos (Outlook clásico en Windows)

Outlook en Windows clásico incluye una copia local de las versiones beta y de producción de Office.js en lugar de cargarse desde la red de entrega de contenido (CDN). De forma predeterminada, se hace referencia a la copia de producción local de la API. Para hacer referencia a la copia beta local de la API, debe configurar el Registro del equipo. Esto le permitirá probar las características de vista previa de los controladores de eventos en Outlook clásico de Windows.

1. En el registro, vaya a HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Si la clave no existe, créela.

2. Crea una entrada con nombre EnableBetaAPIsInJavaScript y establece su valor en 1.

   

Habilitar el inicio de sesión único (SSO)

Para habilitar el SSO en el complemento basado en eventos, debe agregar su archivo JavaScript a un URI conocido. Para obtener instrucciones sobre cómo configurar este recurso, consulte Usar el inicio de sesión único (SSO) o el uso compartido de recursos entre orígenes (CORS) en el complemento de Office basado en eventos o de informes de spam.

Solicitar datos externos

Puede solicitar datos externos mediante una API como Fetch o mediante XMLHttpRequest (XHR), una API web estándar que emite solicitudes HTTP para interactuar con los servidores.

Nota:

Si el complemento va a funcionar en un tiempo de ejecución de solo JavaScript, use direcciones URL absolutas en las llamadas a la API de recuperación. Las direcciones URL relativas en las llamadas a la API de recuperación no se admiten en un tiempo de ejecución de solo JavaScript.

Tenga en cuenta que debe usar medidas de seguridad adicionales al usar objetos XMLHttpRequest, lo que requiere una directiva de mismo origen y CORS (uso compartido de recursos entre orígenes).

Nota:

La compatibilidad completa con CORS está disponible en clientes de Office en la Web, Mac y Windows (a partir de la versión 2201, compilación 16.0.14813.10000).

Para realizar solicitudes CORS desde el complemento basado en eventos, debe agregar el complemento y su archivo JavaScript a un URI conocido. Para obtener instrucciones sobre cómo configurar este recurso, consulte Usar el inicio de sesión único (SSO) o el uso compartido de recursos entre orígenes (CORS) en el complemento de Office basado en eventos o de informes de spam.

Solucionar problemas con el complemento

A medida que desarrolle el complemento basado en eventos, es posible que tenga que solucionar problemas, como que el complemento no se cargue o que el evento no se produzca. Para obtener instrucciones sobre cómo solucionar problemas de un complemento basado en eventos, vea Solucionar problemas de complementos basados en eventos y de informes de spam.

Implementación del complemento

Dependiendo de la aplicación de Office, los complementos basados en eventos se pueden implementar a través de una de las siguientes opciones.

• Implementación administrada por el Administrador: el complemento se implementa a través del Centro de administración de Microsoft 365.
• Lista restringida en Microsoft Marketplace: el complemento se publica en Microsoft Marketplace, pero no aparece en los resultados de la búsqueda. La adquisición de complementos requiere una dirección URL del código de vuelo. Un administrador debe implementar el complemento para que la característica de activación basada en eventos funcione.
• Lista sin restricciones en Microsoft Marketplace: el complemento se publica en Microsoft Marketplace y los usuarios y administradores pueden buscarlo mediante el nombre o el id. del complemento. La implementación del Administrador no es necesaria para que la característica de activación basada en eventos funcione. El complemento debe cumplir ciertos requisitos para la lista sin restricciones.

En la tabla siguiente se describen las opciones de implementación para la activación basada en eventos por parte de la aplicación de Office.

Aplicación de Office	Implementación administrada por el Administrador	Microsoft Marketplace
Excel	Compatible	Opción de lista restringida
Outlook	Compatible	Opciones de lista restringidas y sin restricciones
PowerPoint	Compatible	Opción de lista restringida
Word	Compatible	Opción de lista restringida

Para obtener instrucciones sobre cómo implementar un complemento a través del Centro de administración de Microsoft 365, vea Implementación administrada por el Administrador. Para obtener más información sobre cómo enumerar el complemento basado en eventos en Microsoft Marketplace, consulte Opciones de lista de Microsoft Marketplace para el complemento basado en eventos.

Importante

Los complementos que usan la característica de alertas inteligentes solo pueden publicarse en Microsoft Marketplace si la propiedad de modo de envío del manifiesto está establecida en la opción de usuario de indicación o bloqueo suave . Si la propiedad Modo de envío de un complemento se establece en bloque, solo puede implementarla el administrador de una organización, ya que no se superará la validación de Microsoft Marketplace.

Implementación administrada por el Administrador

Las implementaciones de Administración se realizan cargando el manifiesto en el Centro de administración de Microsoft 365. Para hacerlo, siga estos pasos:

1. En el portal de administración, 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 , elija la acción Cargar aplicaciones personalizadas .

3. Los pasos siguientes dependen del manifiesto que se use.

   • Manifiesto unificado para Microsoft 365:

     1. En el cuadro desplegable Tipo de aplicación , seleccione Aplicación de Teams. Noes un complemento de Office.
     2. Use el control de selector de archivos para navegar y seleccionar el archivo zip del paquete de la aplicación.
     3. Siga las instrucciones de la página para completar la instalación.

   • Manifiesto solo complemento:

     1. En el cuadro desplegable Tipo de aplicación , seleccione Complemento de Office.
     2. Use el control de selector de archivos para navegar hasta el manifiesto y seleccionarlo.
     3. Siga las instrucciones de la página para completar la instalación.

Para obtener más información acerca de cómo implementar un complemento, consulte Implementar y publicar complementos de Office en el Centro de administración de Microsoft 365.

Implementar actualizaciones de manifiestos

Si se implementó un complemento basado en eventos, cualquier cambio que realice en el manifiesto requiere el consentimiento del administrador a través del Centro de administración de Microsoft 365. Hasta que el administrador acepte los cambios, los usuarios de su organización no podrán usar el complemento. Para obtener más información sobre el proceso de consentimiento del administrador, consulte Consentimiento del administrador para instalar complementos basados en eventos.

Vea también

• Solucionar problemas de complementos basados en eventos e informes de correo no deseado
• Depurar complementos basados en eventos e informes de correo no deseado
• Opciones de lista de Microsoft Marketplace para el complemento basado en eventos
• Controle los eventos OnMessageSend y OnAppointmentSend en el complemento de Outlook con alertas inteligentes