Implementar um painel de tarefas fixável no Outlook

  • Artigo

A forma de UX do painel de tarefas para comandos de suplemento abre um painel de tarefas vertical à direita de uma mensagem aberta ou solicitação de reunião. Isso permite que um suplemento forneça a interface do usuário para interações mais detalhadas, como preencher vários campos de texto. Esse painel de tarefas pode ser mostrado no Painel de Leitura ao exibir uma lista de mensagens, permitindo o processamento rápido de uma mensagem.

No entanto, por padrão, se um usuário tiver um painel de tarefas de suplemento aberto para uma mensagem no Painel de Leitura e selecionar uma nova mensagem, o painel de tarefas será fechado automaticamente. Para um suplemento bastante usado, o usuário pode optar por manter esse painel aberto, eliminando a necessidade de reativar o suplemento em cada mensagem. Com painéis de tarefa fixáveis, seu suplemento pode dar ao usuário essa opção.

Observação

Embora o recurso de painel de tarefas fixável tenha sido introduzido no conjunto de requisitos 1.5, ele está atualmente disponível apenas para assinantes do Microsoft 365 usando o seguinte:

  • Outlook na Web moderno
  • Novo Outlook no Windows (versão prévia)
  • Clássico Outlook 2016 ou posterior no Windows (Build 7668.2000 ou posterior para usuários nos Canais Internos atuais ou do Microsoft 365, Build 7900.xxxx ou posterior para usuários em canais adiados)
  • Outlook no Mac (versão 16.13.503 ou posterior)

Importante

Os painéis de tarefa fixados não estão disponíveis para o seguinte:

  • Compromissos/Reuniões
  • Outlook.com

Suporte para fixação do painel de tarefas

A primeira etapa consiste em adicionar o suporte para fixação no manifesto do suplemento. A marcação varia dependendo do tipo de manifesto que seu suplemento usa.

Adicione uma propriedade "pinnable", definida como true, para o objeto na matriz "actions" que define o botão ou item de menu que abre o painel de tarefas. Apresentamos um exemplo a seguir.

"actions": [
    {
        "id": "OpenTaskPane",
        "type": "openPage",
        "view": "TaskPaneView",
        "displayName": "OpenTaskPane",
        "pinnable": true
    }
]

Para ver um exemplo completo, confira o controle msgReadOpenPaneButton na amostra de manifesto command-demo.

Observação

A fixação do painel de tarefas tem suporte automaticamente em um suplemento que é ativado sem o Painel de Leitura habilitado ou uma mensagem selecionada pela primeira vez. Para saber mais, confira Ativar seu suplemento do Outlook sem o Painel de Leitura habilitado ou uma mensagem selecionada.

Atualizações de tratamento da interface do usuário com base na mensagem atualmente selecionada

Para atualizar a interface do usuário ou as variáveis internas do painel de tarefas com base no item atual, você deve registrar um manipulador de eventos para receber notificações das alterações.

Implementar o manipulador de eventos

O manipulador de eventos deve aceitar um parâmetro exclusivo, que é um objeto literal. A propriedade type desse objeto será definida como Office.EventType.ItemChanged. Ao chamar o evento, o objeto Office.context.mailbox.item já estará atualizado para refletir o item atualmente selecionado.

function itemChanged(eventArgs) {
  // Update UI based on the new current item.
  updateTaskPaneUI(Office.context.mailbox.item);
}

Importante

A implementação de manipuladores de eventos para um evento ItemChanged deve verificar se o Office.content.mailbox.item é nulo.

// Example implementation.
function updateTaskPaneUI(item) {
  // Assuming that item is always a read item (instead of a compose item).
  if (item != null) console.log(item.subject);
}

Registrar o manipulador de eventos

Use o método Office.context.mailbox.addHandlerAsync para registrar o manipulador de eventos para o evento Office.EventType.ItemChanged. Isso deve ser feito na Office.onReady função do painel de tarefas.

Office.onReady(() => {
  $(document).ready(() => {
    // Set up the ItemChanged event.
    Office.context.mailbox.addHandlerAsync(Office.EventType.ItemChanged, itemChanged);
    updateTaskPaneUI(Office.context.mailbox.item);
  });
});

Fixação do painel de tarefas em várias seleções

No Outlook na Web e no novo Outlook no Windows (versão prévia), quando o painel de tarefas de um suplemento que implementa o recurso de seleção múltipla do item é aberto, ele é automaticamente fixado no cliente do Outlook. Ele permanece fixado mesmo quando um usuário alterna para um item de email diferente ou seleciona o ícone de fixação no painel de tarefas. O painel de tarefas só pode ser fechado selecionando o botão Fechar no painel de tarefas.

Por outro lado, no Outlook clássico no Windows e no Outlook no Mac, o painel de tarefas de um suplemento de várias seleções não é fixado automaticamente e fecha quando um usuário muda para um item de email diferente.

Implantar em usuários

Se você planeja publicar o suplemento do Outlook no AppSource e ele está configurado com um painel de tarefas fixável, o conteúdo do suplemento não deve ser estático e deve exibir claramente dados relacionados à mensagem aberta ou selecionada na caixa de correio. Isso garante que seu suplemento passe pela validação do AppSource.

Confira também

Para obter um exemplo de suplemento que implementa um painel de tarefas fixável, confira command-demo no GitHub.