Configurar o suplemento do Outlook para ativação baseada em eventos
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 verificarem 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 do manifesto 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
|
OnNewAppointmentOrganizer |
newAppointmentOrganizerCreated | Ao criar um novo compromisso, mas não ao editar um existente. |
1.10
|
OnMessageAttachmentsChanged |
messageAttachmentsChanged | Ao adicionar ou remover anexos ao compor uma mensagem. Objeto de dados específico do evento: AttachmentsChangedEventArgs |
1.11
|
OnAppointmentAttachmentsChanged |
appointmentAttachmentsChanged | Ao adicionar ou remover anexos ao compor um compromisso. Objeto de dados específico do evento: AttachmentsChangedEventArgs |
1.11
|
OnMessageRecipientsChanged |
messageRecipientsChanged | Ao adicionar ou remover destinatários ao compor uma mensagem. Objeto de dados específico do evento: DestinatáriosChangedEventArgs |
1.11
|
OnAppointmentAttendeesChanged |
appointmentAttendeesChanged | Ao adicionar ou remover participantes ao compor um compromisso. Objeto de dados específico do evento: DestinatáriosChangedEventArgs |
1.11
|
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
|
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
|
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
|
OnMessageSend |
messageSending | Ao enviar um item de mensagem. Para saber mais, experimente as instruções de Alertas Inteligentes. |
1.12
|
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
|
OnMessageCompose |
messageComposeOpened | Ao compor uma nova mensagem (inclui responder, responder a todos e reencaminhar) ou editar um rascunho. |
1.12
|
OnAppointmentOrganizer |
appointmentOrganizerOpened | Ao criar um novo compromisso ou editar um existente. |
1.12
|
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
|
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
|
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
|
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
|
Observação
1 Os suplementos baseados em eventos no Outlook clássico no Windows necessitam de 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.
As implementações de administrador 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 .
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 por 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 Consentimento do administrador 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.initializenoOffice.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 |
|
Office.context.auth* |
getAccessTokenAsync |
Office.context.mailbox |
|
Office.context.mailbox.item |
|
Office.context.ui |
|
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.
No registo, navegue para
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Se a chave não existir, crie-a.Crie uma entrada com o nome
EnableBetaAPIsInJavaScripte defina o respetivo valor como1.
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 cors completo está disponível nos 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
- Resolver problemas de suplementos baseados em eventos e relatórios de spam
- Depurar suplementos baseados em eventos e relatórios de spam
- Opções de listagem do AppSource para o seu suplemento do Outlook baseado em eventos
- Processar eventos OnMessageSend e OnAppointmentSend no seu suplemento do Outlook com Alertas Inteligentes
- Definir automaticamente o assunto de uma nova mensagem ou compromisso
- Verificar automaticamente um anexo antes de uma mensagem ser enviada
- Atualizar automaticamente a sua assinatura ao alternar entre contas de correio
- Exemplos de código de Suplementos do Office:
- Encriptar anexos, processar participantes de pedidos de reunião e reagir a alterações de data/hora de compromisso com a ativação baseada em eventos do Outlook
- Definir a sua assinatura com a ativação baseada em eventos do Outlook
- Identificar e etiquetar destinatários externos com a ativação baseada em eventos do Outlook
- Verifique as categorias de cores de uma mensagem ou compromisso antes de ser enviado através de Alertas Inteligentes
- Verificar a etiqueta de confidencialidade de uma mensagem