Configurar o suplemento do Outlook para ativação baseada em eventos
O recurso de ativação baseado em evento permite que um usuário use seu suplemento para concluir suas tarefas sem iniciar explicitamente o suplemento. Seu suplemento executará tarefas quando determinados eventos ocorrerem, como atualizar automaticamente os anexos de um item de email quando os destinatários alterarem ou marcar para um anexo específico antes que um item de email seja enviado. Você 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 esse recurso 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 dão suporte a ele, consulte Eventos com suporte e conjuntos de requisitos com suporte por servidores do Exchange e clientes do Outlook.
Para saber como implementar um suplemento baseado em eventos que é executado no Outlook em dispositivos móveis, confira Implementar ativação baseada em eventos em suplementos móveis do Outlook.
Eventos com suporte
A tabela a seguir lista os eventos que estão disponíveis no momento e os clientes com suporte para cada evento. Quando um evento é gerado, o manipulador recebe um event objeto que pode incluir detalhes específicos para o tipo de evento. A coluna Description inclui um link para o objeto relacionado, quando aplicável.
| Nome canônico do evento e nome do manifesto XML |
Manifesto unificado para o nome do Microsoft 365 | Descrição | Requisitos mínimos definidos e clientes com suporte |
|---|---|---|---|
OnNewMessageCompose |
newMessageComposeCreated | Ao compor uma nova mensagem (inclui resposta, responder tudo e encaminhar), mas não na edição, por exemplo, de um rascunho. | 1.10 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac - Android2 - iOS2 |
OnNewAppointmentOrganizer |
newAppointmentOrganizerCreated | Ao criar um novo compromisso, mas não na edição de um existente. | 1.10 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnMessageAttachmentsChanged |
messageAttachmentsChanged | Ao adicionar ou remover anexos ao compor uma mensagem. Objeto de dados específico do evento: AttachmentsChangedEventArgs |
1.11 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnAppointmentAttachmentsChanged |
appointmentAttachmentsChanged | Ao adicionar ou remover anexos durante a composição de um compromisso. Objeto de dados específico do evento: AttachmentsChangedEventArgs |
1.11 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário 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 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnAppointmentAttendeesChanged |
appointmentAttendeesChanged | Ao adicionar ou remover participantes durante a composição de um compromisso. Objeto de dados específico do evento: DestinatáriosChangedEventArgs |
1.11 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnAppointmentTimeChanged |
appointmentTimeChanged | Ao alterar a data/hora durante a composição de um compromisso. Objeto de dados específico do evento: AppointmentTimeChangedEventArgs Importante: se você arrastar e soltar um compromisso para um slot de data/hora diferente no calendário, o OnAppointmentTimeChanged evento não ocorrerá. Ela só ocorre quando a data/hora é alterada diretamente de um compromisso. |
1.11 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnAppointmentRecurrenceChanged |
appointmentRecurrenceChanged | Ao adicionar, alterar ou remover os detalhes de recorrência durante a composição de um compromisso. Se a data/hora for alterada, o OnAppointmentTimeChanged evento também ocorrerá.Objeto de dados específico do evento: RecurrenceChangedEventArgs |
1.11 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnInfoBarDismissClicked |
infoBarDismissClicked | Ao descartar uma notificação ao compor uma mensagem ou item de compromisso. Somente o suplemento que adicionou a notificação será notificado. Objeto de dados específico do evento: InfobarClickedEventArgs |
1.11 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnMessageSend |
messageSending | Ao enviar um item de mensagem. Para saber mais, experimente o passo a passo alertas inteligentes. | 1.12 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnAppointmentSend |
appointmentSending | Ao enviar um item de compromisso. Para saber mais, confira Manipular eventos OnMessageSend e OnAppointmentSend no suplemento do Outlook com alertas inteligentes. | 1.12 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnMessageCompose |
messageComposeOpened | Ao compor uma nova mensagem (inclui responder, responder tudo e encaminhar) ou editar um rascunho. | 1.12 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnAppointmentOrganizer |
appointmentOrganizerOpened | Ao criar um novo compromisso ou editar um existente. | 1.12 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnMessageFromChanged |
messageFromChanged | Ao alterar a conta de email no campo De uma mensagem que está sendo composta. Para saber mais, confira Atualizar automaticamente sua assinatura ao alternar entre contas do Exchange. | 1.13 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnAppointmentFromChanged |
appointmentFromChanged | Ao alterar a conta de email no campo organizador de um compromisso que está sendo composto. Para saber mais, confira Atualizar automaticamente sua assinatura ao alternar entre contas do Exchange. | 1.13 - novo Outlook no Windows (versão prévia) – Navegador da Web - Nova interface do usuário do Mac |
OnSensitivityLabelChanged |
sensitivityLabelChanged | Ao alterar o rótulo de confidencialidade ao compor uma mensagem ou compromisso. Para saber como gerenciar o rótulo de confidencialidade de um item de email, consulte Gerenciar o rótulo de confidencialidade de sua mensagem ou compromisso no modo de composição. Objeto de dados específico do evento: SensitivityLabelChangedEventArgs |
1.13 - Windows (clássico1 e novo (versão prévia)) – Navegador da Web - Nova interface do usuário do Mac |
OnMessageReadWithCustomAttachment |
Não disponível | Ao abrir uma mensagem que contém um tipo de anexo específico no modo de leitura. | Versão prévia3 - Windows1 |
OnMessageReadWithCustomHeader |
Não disponível | Ao abrir uma mensagem que contém um nome de cabeçalho da Internet específico no modo de leitura. | Versão prévia3 - Windows1 |
Observação
1 Os suplementos baseados em eventos no Outlook no Windows exigem um mínimo de Windows 10 versão 1903 (Build 18362) ou Windows Server 2019 Versão 1903 para execução.
2 O Outlook no celular dá suporte a APIs até o conjunto de requisitos da caixa de correio 1.5. No entanto, o suporte agora está habilitado para APIs adicionais e recursos introduzidos em conjuntos de requisitos posteriores, como o OnNewMessageCompose evento. Para saber mais, confira Implementar ativação baseada em eventos nos suplementos móveis do Outlook.
3 Para visualizar os eventos eOnMessageReadWithCustomHeader, você deve instalar o OnMessageReadWithCustomAttachment Outlook no Windows Versão 2312 (Build 17110.10000) ou posterior. Em seguida, insira o programa Microsoft 365 Insider e selecione a opção Canal Beta para acessar builds beta do Office.
Solucionar problemas do suplemento
À medida que você desenvolve seu suplemento baseado em eventos, talvez seja necessário solucionar problemas, como o suplemento que não está sendo carregado ou o evento que não está ocorrendo. Para obter diretrizes sobre como solucionar problemas de um suplemento baseado em evento, consulte Solucionar problemas de suplementos baseados em eventos e de relatório de spam.
Implantar em usuários
Os suplementos baseados em eventos são restritos apenas a implantações gerenciadas por administradores, mesmo que sejam adquiridos do AppSource. Se os usuários adquirirem o suplemento do AppSource ou da Office Store no aplicativo, eles não poderão ativar a função baseada em eventos do suplemento. Para saber mais sobre como listar seu suplemento baseado em eventos no AppSource, confira Opções de listagem do AppSource para seu suplemento do Outlook baseado em evento.
Administração implantações são feitas carregando o manifesto no Centro de administração do Microsoft 365. No portal de administração, expanda a seção Configurações no painel de navegação e selecione Aplicativos integrados. Na página Aplicativos integrados , escolha a ação Carregar aplicativos personalizados .
Importante
Os suplementos que usam o recurso Alertas Inteligentes só poderão ser publicados no AppSource se a propriedade de modo de envio do manifesto estiver definida como a opção prompt user ou soft block . Se a propriedade de modo de envio de um suplemento estiver definida como bloqueada, ela só poderá ser implantada pelo administrador de uma organização, pois falhará na validação do AppSource.
Implantar atualizações de manifesto
Como os suplementos baseados em evento são implantados por administradores, qualquer alteração que você fizer no manifesto requer o consentimento do administrador por meio do Centro de administração do Microsoft 365. Até que o administrador aceite suas alterações, os usuários em sua organização serão impedidos de usar o suplemento. Para saber mais sobre o processo de consentimento do administrador, consulte Administração consentimento para instalar suplementos baseados em evento.
Comportamento e limitações de ativação baseados em eventos
Espera-se que os manipuladores de eventos de lançamento de suplemento sejam de execução curta, leve e o mais não invasivo possível. Após a ativação, o suplemento terá um tempo limite em aproximadamente 300 segundos, o tempo máximo permitido para executar suplementos baseados em evento. Para sinalizar que o suplemento concluiu o processamento de um evento de inicialização, o manipulador de eventos associado deve chamar o método event.completed . (Observe que o código incluído após a event.completed instrução não tem garantia de execução.) Sempre que um evento que seu suplemento manipula é disparado, o suplemento é reativado e executa o manipulador de eventos associado e a janela de tempo limite é redefinida. O suplemento termina após o tempo limite ou o usuário fecha a janela de composição ou envia o item.
Se o usuário tiver vários suplementos que assinam o mesmo evento, a plataforma do Outlook iniciará os suplementos em nenhuma ordem específica. Atualmente, apenas cinco suplementos baseados em eventos podem estar em execução ativa.
Em todos os clientes do Outlook com suporte, o usuário deve permanecer no item de email atual em que o suplemento foi ativado para que ele seja concluído em execução. Navegar para longe do item atual (por exemplo, alternar para outra janela ou guia de composição) encerra a operação de suplemento. No entanto, um suplemento que é ativado no evento manipula a OnMessageSend alternância de item de forma diferente, dependendo de qual cliente do Outlook ele está em execução. Para saber mais, confira a seção "Usuário navega para longe da mensagem atual" dos eventos Handle OnMessageSend e OnAppointmentSend no suplemento do Outlook com alertas inteligentes.
Além da troca de itens, um suplemento baseado em evento também interrompe a operação quando o usuário envia a mensagem ou compromisso que está compondo.
Ao desenvolver um suplemento baseado em evento para ser executado no cliente do Outlook no Windows, fique atento ao seguinte:
Não há suporte para importações no arquivo JavaScript em que você implementa o tratamento para ativação baseada em eventos.
Os suplementos não executam o código incluído em
Office.onReady()eOffice.initialize. Recomendamos adicionar qualquer lógica de inicialização, como verificar a versão do Outlook do usuário, aos manipuladores de eventos.Há suporte apenas para o arquivo JavaScript referenciado no manifesto para ativação baseada em evento. Você deve empacotar seu código JavaScript de tratamento de eventos neste único arquivo. O local do arquivo JavaScript referenciado no manifesto varia dependendo do tipo de manifesto que seu suplemento usa.
- Manifesto XML: <substituir> o elemento filho do <nó Runtime>
- Manifesto unificado para o Microsoft 365 (versão prévia): propriedade "script" do objeto "code"
Observe que um grande pacote JavaScript pode causar problemas com o desempenho do seu suplemento. Recomendamos pré-processar operações pesadas para que elas não sejam incluídas no código de tratamento de eventos.
Algumas APIs Office.js que alteram ou alteram a interface do usuário não são permitidas de suplementos baseados em eventos. A seguir estão as APIs bloqueadas.
- Em
Office.context.auth:getAccessTokengetAccessTokenAsyncObservação
O OfficeRuntime.auth tem suporte em todas as versões do Outlook que dão suporte a ativação baseada em evento e SSO (logon único), enquanto o Office.auth só tem suporte em determinados builds do Outlook. Para obter mais informações, consulte Usar o SSO (logon único) ou o CORS (compartilhamento de recursos de origem cruzada) no suplemento do Outlook baseado em eventos ou spam.
- Em
Office.context.mailbox:displayAppointmentFormdisplayMessageFormdisplayNewAppointmentFormdisplayNewMessageForm
- Em
Office.context.mailbox.item:close
- Em
Office.context.ui:displayDialogAsyncmessageParent
Visualizar recursos em manipuladores de eventos (Outlook no Windows)
O Outlook no Windows inclui uma cópia local das versões beta e de produção de Office.js em vez de carregar da CDN (rede de entrega de conteúdo). Por padrão, a cópia de produção local da API é referenciada. Para fazer referência à cópia beta local da API, você deve configurar o registro do computador. Isso permitirá que você teste recursos de visualização em seus manipuladores de eventos no Outlook no Windows.
No registro, navegue até
HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Se a chave não existir, crie-a.Crie uma entrada nomeada
EnableBetaAPIsInJavaScripte defina seu valor como1.
Habilitar o SSO (logon único)
Para habilitar o SSO em seu suplemento baseado em evento, você deve adicionar seu arquivo JavaScript a um URI bem conhecido. Para obter diretrizes sobre como configurar esse recurso, consulte Usar o SSO (logon único) ou o CORS (compartilhamento de recursos de origem cruzada) no suplemento do Outlook baseado em eventos ou spam.
Solicitar dados externos
Você pode solicitar dados externos usando uma API como Fetch ou usando XMLHttpRequest (XHR), uma API Web padrão que emite solicitações HTTP para interagir com servidores.
Lembre-se de que você deve usar medidas de segurança adicionais ao usar objetos XMLHttpRequest, exigindo a Mesma Política de Origem e CORS (Compartilhamento de Recursos entre Origens).
Observação
O suporte completo do CORS está disponível em Outlook na Web, Mac e Windows (a partir da versão 2201, Build 16.0.14813.10000).
Para fazer solicitações cors de seu suplemento baseado em evento, você deve adicionar o suplemento e seu arquivo JavaScript a um URI bem conhecido. Para obter diretrizes sobre como configurar esse recurso, consulte Usar o SSO (logon único) ou o CORS (compartilhamento de recursos de origem cruzada) no suplemento do Outlook baseado em eventos ou spam.
Confira também
- Solucionar 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 seu suplemento do Outlook baseado em evento
- Manipular eventos OnMessageSend e OnAppointmentSend no suplemento do Outlook com alertas inteligentes
- Definir automaticamente o assunto de uma nova mensagem ou compromisso
- Marcar automaticamente para um anexo antes que uma mensagem seja enviada
- Atualize automaticamente sua assinatura ao alternar entre contas de email
- Exemplos de código de suplementos do Office:
- Criptografar anexos, processar os participantes da solicitação de reunião e reagir às alterações de data/hora do compromisso usando a ativação baseada em eventos do Outlook
- Defina sua assinatura usando a ativação baseada em eventos do Outlook
- Identificar e marcar destinatários externos usando a ativação baseada em eventos do Outlook
- Verifique as categorias de cores de uma mensagem ou compromisso antes de ser enviada usando alertas inteligentes
- Verificar o rótulo de confidencialidade de uma mensagem
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de