Compartilhar via

Configurar o suplemento do Outlook para ativação baseada em eventos

  • Artigo

A funcionalidade de ativação baseada em eventos permite que um utilizador utilize o seu suplemento para concluir as tarefas sem iniciar explicitamente o suplemento. O suplemento executará tarefas quando determinados eventos ocorrerem, como atualizar automaticamente os anexos de um item de correio quando os destinatários alterarem ou marcar para um determinado anexo antes de um item de correio ser enviado. Também pode integrar a ativação baseada em eventos com o painel de tarefas e os comandos de função.

Observação

O suporte para esta funcionalidade foi introduzido no conjunto de requisitos 1.10, com eventos adicionais agora disponíveis em conjuntos de requisitos subsequentes. Para obter detalhes sobre o conjunto de requisitos mínimos de um evento e os clientes e plataformas que o suportam, veja Eventos suportados e Conjuntos de requisitos suportadospor servidores exchange e clientes do Outlook.

Para saber como implementar um suplemento baseado em eventos que é executado no Outlook em dispositivos móveis, consulte Implementar a ativação baseada em eventos nos suplementos móveis do Outlook.

Eventos com suporte

A tabela seguinte lista os eventos atualmente disponíveis e os clientes suportados para cada evento. Quando um evento é gerado, o processador recebe um event objeto que pode incluir detalhes específicos do tipo de evento. A coluna Descrição inclui uma ligação para o objeto relacionado, quando aplicável.

Nome canónico
do evento e nome de manifesto apenas do suplemento		 Manifesto unificado para o nome do Microsoft 365 Descrição Conjunto de requisitos mínimo e clientes suportados
OnNewMessageCompose newMessageComposeCreated Ao compor uma nova mensagem (inclui responder, responder a todos e reencaminhar), mas não ao editar, por exemplo, um rascunho. 1.10
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
  • Android2
  • iOS2
OnNewAppointmentOrganizer newAppointmentOrganizerCreated Ao criar um novo compromisso, mas não ao editar um existente. 1.10
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnMessageAttachmentsChanged messageAttachmentsChanged Ao adicionar ou remover anexos ao compor uma mensagem.

Objeto de dados específico do evento: AttachmentsChangedEventArgs		 1.11
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnAppointmentAttachmentsChanged appointmentAttachmentsChanged Ao adicionar ou remover anexos ao compor um compromisso.

Objeto de dados específico do evento: AttachmentsChangedEventArgs		 1.11
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnMessageRecipientsChanged messageRecipientsChanged Ao adicionar ou remover destinatários ao compor uma mensagem.

Objeto de dados específico do evento: DestinatáriosChangedEventArgs		 1.11
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
  • Android2
  • iOS2
OnAppointmentAttendeesChanged appointmentAttendeesChanged Ao adicionar ou remover participantes ao compor um compromisso.

Objeto de dados específico do evento: DestinatáriosChangedEventArgs		 1.11
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnAppointmentTimeChanged appointmentTimeChanged Ao alterar a data/hora ao compor um compromisso.

Objeto de dados específico do evento: AppointmentTimeChangedEventArgs

Importante: se arrastar e largar um compromisso para um intervalo de data/hora diferente no calendário, o OnAppointmentTimeChanged evento não ocorre. Só ocorre quando a data/hora é alterada diretamente de um compromisso.		 1.11
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnAppointmentRecurrenceChanged appointmentRecurrenceChanged Ao adicionar, alterar ou remover os detalhes de periodicidade ao compor um compromisso. Se a data/hora for alterada, o OnAppointmentTimeChanged evento também ocorrerá.

Objeto de dados específico do evento: RecurrenceChangedEventArgs		 1.11
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnInfoBarDismissClicked infoBarDismissClicked Ao dispensar uma notificação ao compor uma mensagem ou item de compromisso. Apenas o suplemento que adicionou a notificação será notificado.

Objeto de dados específico do evento: InfobarClickedEventArgs		 1.11
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnMessageSend messageSending Ao enviar um item de mensagem. Para saber mais, experimente as instruções de Alertas Inteligentes. 1.12
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnAppointmentSend appointmentSending Ao enviar um item de compromisso. Para saber mais, consulte Processar eventos OnMessageSend e OnAppointmentSend no seu suplemento do Outlook com Alertas Inteligentes. 1.12
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnMessageCompose messageComposeOpened Ao compor uma nova mensagem (inclui responder, responder a todos e reencaminhar) ou editar um rascunho. 1.12
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnAppointmentOrganizer appointmentOrganizerOpened Ao criar um novo compromisso ou editar um existente. 1.12
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnMessageFromChanged messageFromChanged Ao alterar a conta de correio no campo De de de uma mensagem a ser composta. Para saber mais, consulte Atualizar automaticamente a sua assinatura ao alternar entre contas do Exchange. 1.13
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnAppointmentFromChanged appointmentFromChanged Ao alterar a conta de correio no campo organizador de um compromisso que está a ser composto. Para saber mais, consulte Atualizar automaticamente a sua assinatura ao alternar entre contas do Exchange. 1.13
OnSensitivityLabelChanged sensitivityLabelChanged Ao alterar a etiqueta de confidencialidade ao compor uma mensagem ou compromisso. Para saber como gerir a etiqueta de confidencialidade de um item de correio, consulte Gerir a etiqueta de confidencialidade da sua mensagem ou compromisso no modo de composição.

Objeto de dados específico do evento: SensitivityLabelChangedEventArgs		 1.13
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IU do Mac
OnMessageReadWithCustomAttachment Não disponível Ao abrir uma mensagem que contém um tipo de anexo específico no modo de leitura. Pré-visualização3
  • Windows (clássico1)
OnMessageReadWithCustomHeader Não disponível Ao abrir uma mensagem que contém um nome de cabeçalho de Internet específico no modo de leitura. Pré-visualização3
  • Windows (clássico1)

Observação

1 Os suplementos baseados em eventos no Outlook clássico no Windows requerem um mínimo de Windows 10 Versão 1903 (Compilação 18362) ou Windows Server 2019 Versão 1903 para execução.

2 O Outlook em dispositivos móveis suporta APIs até ao conjunto de requisitos da Caixa de Correio 1.5. No entanto, o suporte está agora ativado para APIs e funcionalidades adicionais introduzidas em conjuntos de requisitos posteriores, como o OnNewMessageCompose evento. Para saber mais, veja Implementar a ativação baseada em eventos nos suplementos móveis do Outlook.

3 Para pré-visualizar os eventos eOnMessageReadWithCustomHeader, tem de instalar o OnMessageReadWithCustomAttachment Outlook clássico no Windows Versão 2312 (Compilação 17110.10000) ou posterior. Em seguida, adira ao programa Microsoft 365 Insider e selecione a opção Canal Beta para aceder às compilações beta do Office.

Resolver problemas do suplemento

À medida que desenvolve o seu suplemento baseado em eventos, poderá ter de resolver problemas, como o suplemento não estar a carregar ou o evento não estar a ocorrer. Para obter orientações sobre como resolver problemas de um suplemento baseado em eventos, veja Resolver problemas de suplementos baseados em eventos e relatórios de spam.

Implementar em utilizadores

Os suplementos baseados em eventos estão restritos apenas a implementações geridas pelo administrador, mesmo que sejam adquiridos no AppSource. Se os utilizadores adquirirem o suplemento no AppSource ou na Loja Office na aplicação, não poderão ativar a função baseada em eventos do suplemento. Para saber mais sobre como listar o seu suplemento baseado em eventos no AppSource, consulte Opções de listagem do AppSource para o seu suplemento do Outlook baseado em eventos.

Administração implementações são efetuadas ao carregar o manifesto para o Centro de administração do Microsoft 365. No portal de administração, expanda a secção Definições no painel de navegação e, em seguida, selecione Aplicações integradas. Na página Aplicações integradas, selecione a ação Carregar aplicações personalizadas .

A página Aplicações integradas no Centro de administração do Microsoft 365 com a ação Carregar aplicações personalizadas realçada.

Importante

Os suplementos que utilizam a funcionalidade Alertas Inteligentes só podem ser publicados no AppSource se a propriedade modo de envio do manifesto estiver definida para a opção de pedido de utilizador ou de bloco suave . Se a propriedade de modo de envio de um suplemento estiver definida para bloquear, só pode ser implementada pelo administrador de uma organização, uma vez que irá falhar a validação do AppSource.

Implementar atualizações de manifesto

Uma vez que os suplementos baseados em eventos são implementados pelos administradores, qualquer alteração efetuada ao manifesto requer o consentimento do administrador através do Centro de administração do Microsoft 365. Até que o administrador aceite as suas alterações, os utilizadores na respetiva organização são impedidos de utilizar o suplemento. Para saber mais sobre o processo de consentimento do administrador, veja Administração consentimento para instalar suplementos baseados em eventos.

Comportamento e limitações da ativação baseada em eventos

Espera-se que os processadores de eventos de início de suplemento sejam de execução curta, leves e o mais não invasivos possível. Após a ativação, o suplemento excederá o limite de tempo em aproximadamente 300 segundos, o período máximo de tempo permitido para executar suplementos baseados em eventos. Para sinalizar que o suplemento concluiu o processamento de um evento de início, o processador de eventos associado tem de chamar o método event.completed . (Tenha em atenção que o código incluído após a event.completed instrução não está garantido para ser executado.) Sempre que um evento que o suplemento processa é acionado, o suplemento é reativado e executa o processador de eventos associado e a janela de tempo limite é reposta. O suplemento termina depois de exceder o limite de tempo ou o utilizador fecha a janela de composição ou envia o item.

Se o utilizador tiver vários suplementos que subscrevem o mesmo evento, a plataforma outlook inicia os suplementos sem nenhuma ordem específica. Atualmente, apenas cinco suplementos baseados em eventos podem ser executados ativamente.

Em todos os clientes do Outlook suportados, o utilizador tem de permanecer no item de correio atual onde o suplemento foi ativado para que seja concluído em execução. Navegar para fora do item atual (por exemplo, mudar para outra janela ou separador de composição) termina a operação de suplemento. No entanto, um suplemento que é ativado no evento processa a OnMessageSend mudança de item de forma diferente consoante o cliente do Outlook em que está a ser executado. Para saber mais, consulte a secção "O utilizador navega para fora da mensagem atual" de Handle OnMessageSend e OnAppointmentSend events in your Outlook add-in with Smart Alerts (Processar Eventos OnMessageSend e OnAppointmentSend no seu suplemento do Outlook com Alertas Inteligentes).

Além da mudança de itens, um suplemento baseado em eventos também deixa de funcionar quando o utilizador envia a mensagem ou compromisso que está a compor.

Suplementos baseados em eventos no Outlook clássico no Windows

Ao desenvolver um suplemento baseado em eventos para ser executado no cliente clássico do Outlook no Windows, tenha em atenção o seguinte:

  • As importações não são suportadas no ficheiro JavaScript onde implementa o processamento da ativação baseada em eventos.

  • Os suplementos não executam o código incluído no e Office.initializeno Office.onReady() . Recomendamos que adicione qualquer lógica de arranque, como verificar a versão do Outlook do utilizador, aos processadores de eventos.

  • Apenas o ficheiro JavaScript referenciado no manifesto é suportado para ativação baseada em eventos. Tem de agrupar o código JavaScript de processamento de eventos neste único ficheiro. A localização do ficheiro JavaScript referenciado no manifesto varia consoante o tipo de manifesto utilizado pelo suplemento.

    • Manifesto apenas de suplemento: <Substituir> elemento subordinado do <nó Runtime>
    • Manifesto unificado para o Microsoft 365: propriedade "script" do objeto "code"

    Tenha em atenção que um pacote JavaScript grande pode causar problemas com o desempenho do suplemento. Recomendamos o pré-processamento de operações pesadas, para que não sejam incluídas no código de processamento de eventos.

APIs sem suporte

Algumas Office.js APIs que alteram ou alteram a IU não são permitidas a partir de suplementos baseados em eventos. Seguem-se APIs 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

Observação

* O OfficeRuntime.auth é suportado em todas as versões do Outlook que suportam a ativação baseada em eventos e o início de sessão único (SSO), enquanto o Office.auth só é suportado em determinadas compilações do Outlook. Para obter mais informações, veja Utilizar o início de sessão único (SSO) ou a partilha de recursos de várias origens (CORS) no seu suplemento do Outlook baseado em eventos ou relatórios de spam.

Funcionalidades de pré-visualização em processadores de eventos (Outlook clássico no Windows)

O Outlook Clássico no Windows inclui uma cópia local das versões de produção e beta do Office.js em vez de carregar a partir da rede de entrega de conteúdos (CDN). Por predefinição, a cópia de produção local da API é referenciada. Para referenciar a cópia beta local da API, tem de configurar o registo do computador. Isto irá permitir-lhe testar as funcionalidades de pré-visualização nos processadores de eventos no Outlook clássico no Windows.

  1. No registo, navegue para HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Se a chave não existir, crie-a.

  2. Crie uma entrada com o nome EnableBetaAPIsInJavaScript e defina o respetivo valor como 1.

    O valor do registo EnableBetaAPIsInJavaScript está definido como 1.

Ativar o início de sessão único (SSO)

Para ativar o SSO no seu suplemento baseado em eventos, tem de adicionar o respetivo ficheiro JavaScript a um URI conhecido. Para obter orientações sobre como configurar este recurso, veja Utilizar o início de sessão único (SSO) ou a partilha de recursos de várias origens (CORS) no seu suplemento do Outlook baseado em eventos ou relatórios de spam.

Pedir dados externos

Pode pedir dados externos através de uma API como a Fetch ou através de XMLHttpRequest (XHR), uma API Web padrão que emite pedidos HTTP para interagir com servidores.

Observação

Se o suplemento funcionar num runtime apenas em JavaScript, utilize URLs absolutos nas chamadas à API Fetch. Os URLs relativos nas chamadas à API de Obtenção não são suportados num runtime apenas em JavaScript.

Tenha em atenção que tem de utilizar medidas de segurança adicionais ao utilizar objetos XMLHttpRequest, que requerem a Mesma Política de Origem e CORS (Partilha de Recursos Transversais à Origem).

Observação

O suporte completo do CORS está disponível em clientes Outlook na Web, Mac e Windows (novo e clássico (a partir da Versão 2201, Compilação 16.0.14813.10000).

Para fazer pedidos CORS a partir do suplemento baseado em eventos, tem de adicionar o suplemento e o respetivo ficheiro JavaScript a um URI conhecido. Para obter orientações sobre como configurar este recurso, veja Utilizar o início de sessão único (SSO) ou a partilha de recursos de várias origens (CORS) no seu suplemento do Outlook baseado em eventos ou relatórios de spam.

Confira também