Ativar suplementos com eventos

A ativação baseada em eventos dispara automaticamente seu suplemento para concluir suas tarefas sem iniciá-lo explicitamente. Isso permite que o suplemento valide, insira ou atualize conteúdo crítico sem nenhuma operação manual. O suplemento é aberto em segundo plano para evitar perturbar o usuário. Você 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 as etapas específicas para adicionar a funcionalidade baseada em eventos ao seu suplemento variem de acordo com a plataforma e o tipo de manifesto, o fluxo geral é o seguinte.

1. Atualize o manifesto com uma extensão para o evento.
2. Conecte o evento no manifesto com uma função JavaScript para manipular o evento.
3. Faça com que a função do manipulador de eventos execute suas ações e chame event.completed quando terminar.
4. Chame Office.actions.associate para conectar a função do manipulador de eventos com a ID especificada no manifesto.

Experimente a ativação baseada em eventos

Descubra como simplificar fluxos de trabalho e melhorar as experiências do usuário com a ativação baseada em eventos. Experimente os exemplos para ver o recurso em ação.

Exemplos do Outlook

• Definir automaticamente o assunto de uma nova mensagem ou compromisso
• Marque automaticamente um anexo antes do envio de uma mensagem
• Atualize automaticamente sua assinatura ao alternar entre contas de email
• Criptografar anexos, processar participantes de solicitação de reunião e reagir a alterações de data/hora do compromisso usando a ativação baseada em eventos do Outlook
• Definir 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 enviá-la usando Alertas Inteligentes
• Verificar o rótulo de confidencialidade de uma mensagem

Exemplos do Word

• Adicionar cabeçalhos quando um documento for aberto

Eventos com suporte

As tabelas a seguir listam 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 do tipo de evento. A coluna Descrição inclui um link para o objeto relacionado, quando aplicável.

Eventos do Excel, PowerPoint e Word

Eventos do Outlook

O suporte para esse recurso no Outlook foi introduzido no conjunto de requisitos 1.10, com eventos adicionais agora disponíveis em conjuntos de requisitos subsequentes. A tabela a seguir lista o conjunto de requisitos mínimos de cada evento e os clientes e plataformas que dão suporte a ele. Para obter mais informações sobre clientes do Outlook e os conjuntos de requisitos que eles suportam, consulte Conjuntos de requisitos suportados por servidores Exchange e clientes Outlook.

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

O Outlook em dispositivos móveis dá suporte a APIs até o requisito de Caixa de correio definido 1.5. No entanto, o suporte agora está habilitado para APIs e recursos adicionais introduzidos em conjuntos de requisitos posteriores, como o OnNewMessageCompose evento. Para saber mais, consulte Implementar a ativação baseada em eventos nos suplementos móveis do Outlook.

Comportamento e limitações

Ao desenvolver um suplemento baseado em eventos, lembre-se dos seguintes comportamentos e limitações de recursos.

• Suplementos baseados em eventos funcionam somente quando implantados por um administrador. Se os usuários os instalarem diretamente do Microsoft Marketplace ou da Office Store, eles não serão iniciados automaticamente (para soluções alternativas à limitação do Microsoft Marketplace, consulte Opções de listagem do Microsoft Marketplace para seu suplemento baseado em eventos). Administração implantações são feitas carregando o manifesto no Centro de administração do Microsoft 365.

• As APIs que interagem com a interface do usuário ou com elementos da interface do usuário de exibição não são compatíveis com o Word, o PowerPoint e o Excel no Windows. Isso ocorre porque o manipulador de eventos é executado em um runtime somente JavaScript. Para obter mais informações, consulte Runtimes em Suplementos do Office.

• Suplementos baseados em eventos exigem uma conexão com a Internet para serem iniciados quando ocorre um evento específico. Espera-se que os manipuladores de eventos de suplemento sejam de execução curta, leves e o menos invasivos possível. Após a ativação, o suplemento atingirá o tempo limite em aproximadamente 300 segundos, o tempo máximo permitido para a execução de suplementos baseados em eventos. 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 não há garantia de execução do código incluído após a event.completed instrução.) Sempre que um evento manipulado pelo suplemento é disparado, o suplemento é reativado e executa o manipulador de eventos associado, e a janela de tempo limite é redefinida. O suplemento termina depois que atinge o tempo limite ou o usuário fecha a janela de redação ou envia o item.

• O comportamento de vários suplementos que assinam o mesmo evento não é determinístico. O Outlook inicia os suplementos em nenhuma ordem específica. Para Excel, PowerPoint e Word, apenas um suplemento aleatório será ativado. Por exemplo, se vários suplementos do Word que manipulam OnDocumentOpened, apenas um desses manipuladores será executado.

• Atualmente, apenas cinco suplementos baseados em eventos podem estar em execução ativamente.

• Em todos os clientes Outlook com suporte, o usuário deve permanecer no item de email atual em que o suplemento foi ativado para que ele conclua a execução. Sair do item atual (por exemplo, alternar para outra janela de redação ou guia) encerra a operação do suplemento. No entanto, um suplemento que é ativado no evento lida com a OnMessageSend alternância de itens de forma diferente, dependendo do cliente Outlook em que está sendo executado. Para saber mais, confira a seção "O usuário navega para fora da mensagem atual" de Lidar com eventos OnMessageSend e OnAppointmentSend no suplemento do Outlook com Alertas Inteligentes.

• Além da alternância de itens, um suplemento baseado em eventos também deixa de operar quando o usuário envia a mensagem ou o compromisso que está redigindo.

Limitações do suplemento baseado em eventos no Excel, PowerPoint, Word e Outlook clássico no Windows

Ao desenvolver um suplemento baseado em eventos para ser executado em um cliente Windows, lembre-se do seguinte:

• Não há suporte para as importações no arquivo JavaScript em que você implementa a manipulação para ativação baseada em eventos.

• Somente o arquivo JavaScript referenciado no manifesto tem suporte para ativação baseada em eventos. Você deve agrupar seu código JavaScript de manipulação de eventos nesse único arquivo. A localização do arquivo JavaScript referenciado no manifesto varia dependendo do tipo de manifesto que seu suplemento usa.

  • Manifesto somente do suplemento: <Override> elemento filho do <Runtime> nó
  • Manifesto unificado para o Microsoft 365: "script" propriedade do "code" objeto

  Observe que um grande pacote JavaScript pode causar problemas com o desempenho do seu suplemento. É recomendável pré-processar operações pesadas, para que elas não sejam incluídas no código de manipulação de eventos.

• Quando a função JavaScript especificada no manifesto para manipular um evento é executada, o código é Office.onReady() inserido e Office.initialize não é executado. É recomendável adicionar qualquer lógica de inicialização necessária aos manipuladores de eventos, como verificar a versão do cliente do usuário, aos manipuladores de eventos.

• No Outlook, ao redigir uma mensagem iniciada por um link de email de retorno (mailto link), recuperar os destinatários do campo Para, Cc ou Cco no OnNewMessageCompose manipulador de eventos pode retornar uma matriz vazia. Isso acontece se o Outlook não tiver concluído a resolução dos endereços de email dos destinatários no momento em que o OnNewMessageCompose evento ocorrer. Para contornar isso, marque os OnMessageRecipientsChanged destinatários no manipulador de eventos.

Limitações do suplemento baseado em eventos no Excel, no PowerPoint e no Word

Ainda não há suporte para as plataformas ou recursos a seguir.

• Office no Mac

Limitações do suplemento baseado em eventos no Outlook na Web e no novo Outlook no Windows

No Outlook na Web e no novo Outlook no Windows, a ativação baseada em eventos só tem suporte em superfícies padrão de ler e redigir mensagens e compromissos. A ativação baseada em eventos pode não funcionar ao compor em algumas superfícies não padrão. Por exemplo:

• Respondendo a um convite de reunião usando a opção RSVP com anotação .
• Encaminhar uma reunião do calendário.

APIs sem suporte

Algumas APIs Office.js que alteram ou alteram a IU não são permitidas em suplementos baseados em eventos. A seguir estão as APIs bloqueadas.

Visualize recursos em manipuladores de eventos (Outlook clássico no Windows)

O Outlook clássico no Windows inclui uma cópia local das versões beta e de produção do Office.js em vez de ser carregado pela CDN (Rede de Distribuição 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 clássico no Windows.

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

2. Crie uma entrada chamada e defina seu valor como EnableBetaAPIsInJavaScript1.

   

Habilitar logon único (SSO)

Para habilitar o SSO no seu suplemento baseado em eventos, você deve adicionar seu arquivo JavaScript a um URI conhecido. Para obter orientações sobre como configurar esse recurso, confira Usar SSO (logon único) ou CORS (compartilhamento de recurso entre origens) no seu Suplemento do Office baseado em eventos ou com relatórios de 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 Política de Mesmo Origem e CORS (Compartilhamento de Recursos entre Origens).

Para fazer solicitações CORS de seu suplemento baseado em evento, você deve adicionar o suplemento e seu arquivo JavaScript a um URI conhecido. Para obter orientações sobre como configurar esse recurso, confira Usar SSO (logon único) ou CORS (compartilhamento de recurso entre origens) no seu Suplemento do Office baseado em eventos ou com relatórios de spam.

Solucionar problemas do seu suplemento

Ao desenvolver seu suplemento baseado em eventos, talvez seja necessário solucionar problemas, como o suplemento que não carrega ou o evento não ocorre. Para obter instruções sobre como solucionar problemas de um suplemento baseado em eventos, consulte Solucionar problemas de suplementos baseados em eventos e de relatórios de spam.

Implantar seu suplemento

Dependendo do aplicativo do Office, os suplementos baseados em eventos podem ser implantados por meio de uma das opções a seguir.

• Administração implantação gerenciada: o suplemento é implantado por meio 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 suplemento requer uma URL de código de pré-lançamento. O suplemento ainda deve ser implantado por um administrador para que o recurso de ativação baseada em eventos funcione.
• Listagem irrestrita no Microsoft Marketplace: o suplemento é publicado no Microsoft Marketplace e pode ser pesquisado por usuários e administradores usando o nome ou a ID do suplemento. Administração implantação não é necessária para que o recurso de ativação baseada em evento funcione. O suplemento deve atender a determinados requisitos de listagem irrestrita.

A tabela a seguir descreve as opções de implantação para ativação baseada em evento pelo aplicativo do Office.

Para obter instruções sobre como implantar um suplemento por meio do Centro de administração do Microsoft 365, consulte Implantação gerenciada pelo Administrador. Para saber mais sobre como listar seu suplemento baseado em evento no Microsoft Marketplace, consulte Opções de listagem do Microsoft Marketplace para seu suplemento baseado em evento.

Implantação gerenciada pelo Administrador

Administração implantações são feitas carregando o manifesto no Centro de administração do Microsoft 365. Para fazer isso, siga estas etapas.

1. No portal de administração, expanda a seção Configurações no painel de navegação e selecione Aplicativos integrados.
2. Na página Aplicativos integrados , escolha a ação Carregar aplicativos personalizados .

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

Implantar atualizações de manifesto

Se um suplemento baseado em evento foi implantado pelo administrador, qualquer alteração feita 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 Consentimento do Administrador para instalar suplementos baseados em eventos.

Confira também

• Solucionar problemas de suplementos baseados em eventos e de relatórios de spam
• Depurar suplementos baseados em eventos e relatórios de spam
• Opções de listagem do Microsoft Marketplace para seu suplemento baseado em evento
• Lidar com eventos OnMessageSend e OnAppointmentSend no suplemento do Outlook com Alertas Inteligentes