Compartilhar via

Ativar suplementos com eventos

A ativação baseada em eventos aciona automaticamente o suplemento para concluir as respetivas tarefas sem a iniciar explicitamente. Isto permite que o suplemento valide, insira ou atualize conteúdo crítico sem quaisquer operações manuais. O suplemento é aberto em segundo plano para evitar perturbar o utilizador. Também pode integrar a ativação baseada em eventos com o painel de tarefas e os comandos de função.

Visão Geral

Embora os passos específicos para adicionar funcionalidades baseadas em eventos ao seu suplemento variem consoante a plataforma e o tipo de manifesto, o fluxo geral é o seguinte.

  1. Atualize o manifesto com uma extensão para o evento.
  2. Ligue o evento no manifesto a uma função JavaScript para processar o evento.
  3. Peça à função de processador de eventos que execute as ações e, em seguida, chame event.completed quando terminar.
  4. Chame Office.actions.associate para ligar a função de processador de eventos ao ID especificado no manifesto.

Experimentar a ativação baseada em eventos

Descubra como simplificar os fluxos de trabalho e melhorar as experiências de utilizador com a ativação baseada em eventos. Experimente os exemplos para ver a funcionalidade em ação.

Exemplos do Outlook

exemplos de Word

Eventos com suporte

As tabelas seguintes listam 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.

Eventos do Excel, PowerPoint Word

Nome canónico
do evento e nome de manifesto apenas do suplemento		 Manifesto unificado para o nome do Microsoft 365 Descrição Clientes e canais suportados
OnDocumentOpened Ainda não suportado Ocorre quando um utilizador abre um documento ou cria um novo documento, folha de cálculo ou apresentação.
  • Windows (Compilação >= 16.0.18324.20032)
  • Office na Web
  • O Office no Mac estará disponível mais tarde

Eventos do Outlook

O suporte para esta funcionalidade no Outlook foi introduzido no conjunto de requisitos 1.10, com eventos adicionais agora disponíveis em conjuntos de requisitos subsequentes. A tabela seguinte lista o conjunto de requisitos mínimos de cada evento e os clientes e plataformas que o suportam. Para obter mais informações sobre os clientes do Outlook e os conjuntos de requisitos que suportam, veja Conjuntos de requisitos suportados pelos servidores exchange e clientes do Outlook.

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 IUdo Mac 2
  • Android23
  • iOS23
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 IUdo Mac 2
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 IUdo Mac 2
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 IUdo Mac 2
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 IUdo Mac 2
  • Android23
  • iOS23
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 IUdo Mac 2
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 IUdo Mac 2
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 IUdo Mac 2
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 IUdo Mac 2
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 IUdo Mac 2
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 IUdo Mac 2
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 IUdo Mac 2
OnAppointmentOrganizer appointmentOrganizerOpened Ao criar um novo compromisso ou editar um existente. 1.12
  • Navegador da Web
  • Windows (novo e clássico1)
  • Nova IUdo Mac 2
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
  • Browser4
  • Windows (novo4 e clássico1)
  • Nova IUdo Mac 2
  • Android23
  • iOS23
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
  • Nova IUdo Mac 2
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
  • Browser4
  • Windows (novo4 e clássico1)
  • Nova IUdo Mac 2
OnMessageReadWithCustomAttachment Não disponível Ao abrir uma mensagem que contém um tipo de anexo específico no modo de leitura. Pré-visualização5
  • 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ção5
  • Windows (clássico1)
OnMessageRead (visualização) Não disponível Ao corresponder o cabeçalho de uma mensagem encriptada à chave de cabeçalho no manifesto de um suplemento. Para saber mais, consulte Criar um suplemento do Outlook de encriptação. Visualização
  • 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 versão 1903 de 2019 para execução.

2 Os suplementos que utilizam o manifesto unificado para o Microsoft 365 não são suportados diretamente no Outlook para Mac e em dispositivos móveis. Para executar este tipo de suplemento no Mac e em plataformas móveis, o suplemento tem primeiro de ser publicado no Microsoft Marketplace e, em seguida, implementado no Centro de Administração Microsoft 365. Para obter mais informações, consulte a secção "Suporte de cliente e plataforma" dos Suplementos do Office com o manifesto de aplicação unificada para o Microsoft 365.

3 Para obter mais informações, veja Implementar a ativação baseada em eventos em suplementos móveis do Outlook.

4 Os OnMessageFromChanged eventos e OnSensitivityLabelChanged não estão atualmente disponíveis com o manifesto unificado do Microsoft 365 no Outlook na Web e o novo Outlook no Windows. Para processar estes eventos, implemente um manifesto apenas de suplemento. Para obter informações sobre os tipos de manifestos, consulte Manifesto de Suplementos do Office.

5 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.

Ativação baseada em eventos no Outlook em dispositivos móveis

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.

Comportamento e limitações

À medida que desenvolve um suplemento baseado em eventos, tenha em atenção os seguintes comportamentos e limitações de funcionalidades.

  • Os suplementos baseados em eventos só funcionam quando implementados por um administrador. Se os utilizadores os instalarem diretamente a partir do Microsoft Marketplace ou da Loja Office, não serão iniciados automaticamente (para obter soluções para a limitação do Microsoft Marketplace, consulte Opções de listagem do Microsoft Marketplace para o seu suplemento baseado em eventos). Administração implementações são efetuadas ao carregar o manifesto para o Centro de administração do Microsoft 365.

  • As APIs que interagem com a IU ou os elementos de IU de apresentação não são suportadas para Word, PowerPoint e Excel no Windows. Isto deve-se ao facto de o processador de eventos ser executado num runtime apenas em JavaScript. Para obter mais informações, consulte Runtimes nos Suplementos do Office.

  • Os suplementos baseados em eventos requerem que uma ligação à Internet possa ser iniciada quando ocorre um evento específico. Espera-se que os processadores de eventos de suplementos sejam de execução curta, leves e tão não invasivos quanto 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.

  • O comportamento de vários suplementos que subscrevem o mesmo evento não é determinista. O Outlook inicia os suplementos sem nenhuma ordem específica. Para o Excel, PowerPoint e Word, só será ativado um suplemento aleatório. Por exemplo, se vários Word suplementos que processam OnDocumentOpenedo , apenas um desses processadores será executado.

  • 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.

Limitações de suplementos baseados em eventos no Excel, PowerPoint, Word e Outlook clássico no Windows

Ao desenvolver um suplemento baseado em eventos para ser executado num cliente 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.

  • 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: <Override> elemento subordinado do <Runtime> nó
    • Manifesto unificado para o Microsoft 365: "script" propriedade do "code" objeto

    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.

  • Quando a função JavaScript especificada no manifesto para processar uma execução de evento, o código no Office.onReady() e Office.initialize não é executado. Recomendamos que adicione qualquer lógica de arranque necessária aos processadores de eventos, como verificar a versão do cliente do utilizador, aos processadores de eventos.

Limitações de suplementos baseados em eventos no Excel, PowerPoint e Word

As seguintes plataformas ou funcionalidades ainda não são suportadas.

  • Office no Mac
  • O manifesto unificado do Microsoft 365

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 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, consulte Utilizar o início de sessão único (SSO) ou a partilha de recursos de várias origens (CORS) no seu Suplemento do Office 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 Office na Web, Mac e Windows (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, consulte Utilizar o início de sessão único (SSO) ou a partilha de recursos de várias origens (CORS) no seu Suplemento do Office baseado em eventos ou relatórios de spam.

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 o suplemento

Consoante a aplicação do Office, os suplementos baseados em eventos podem ser implementados através de uma das seguintes opções.

  • implementação gerida Administração: o suplemento é implementado através do Centro de administração do Microsoft 365.
  • Listagem restrita no Microsoft Marketplace: o suplemento é publicado no Microsoft Marketplace, mas não aparece nos resultados da pesquisa. A aquisição de suplementos requer um URL de código de voo. O suplemento ainda tem de ser implementado por um administrador para que a funcionalidade de ativação baseada em eventos funcione.
  • Listagem sem restrições no Microsoft Marketplace: o suplemento é publicado no Microsoft Marketplace e pode ser procurado por utilizadores e administradores através do nome ou ID do suplemento. Administração implementação não é necessária para que a funcionalidade de ativação baseada em eventos funcione. O suplemento tem de cumprir determinados requisitos de listagem sem restrições.

A tabela seguinte descreve as opções de implementação para ativação baseada em eventos por aplicação do Office.

Aplicativo do Office implementação gerida Administração Microsoft Marketplace
Excel Com suporte Opção de listagem restrita
Outlook Com suporte Opções de listagem restritas e sem restrições
PowerPoint Com suporte Opção de listagem restrita
Word Com suporte Opção de listagem restrita

Para obter instruções sobre como implementar um suplemento através do Centro de administração do Microsoft 365, veja implementação gerida Administração. Para saber mais sobre como listar o seu suplemento baseado em eventos no Microsoft Marketplace, consulte Opções de listagem do Microsoft Marketplace para o seu suplemento baseado em eventos.

Importante

Os suplementos que utilizam a funcionalidade Alertas Inteligentes só podem ser publicados no Microsoft Marketplace se a propriedade modo de envio do manifesto estiver definida para a opção de pedido de utilizador ou de bloqueio 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 Microsoft Marketplace.

implementação gerida Administração

Administração implementações são efetuadas ao carregar o manifesto para o Centro de administração do Microsoft 365. Para fazer isso, siga estas etapas.

  1. No portal de administração, expanda a secção Definições no painel de navegação e, em seguida, selecione Aplicações integradas.
  2. 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.

Para obter mais informações sobre como implementar um suplemento, consulte Implementar e publicar Suplementos do Office no Centro de administração do Microsoft 365.

Implementar atualizações de manifesto

Se um suplemento baseado em eventos tiver sido implementado pelo administrador, 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.

Confira também

  • Last updated on