Implementar um painel de tarefas fixável no Outlook

A forma UX do painel de tarefas para comandos de suplemento abre um painel de tarefas vertical à direita de uma mensagem aberta ou pedido de reunião. Isto permite que um suplemento forneça IU para interações mais detalhadas, como preencher vários campos de texto. Este painel de tarefas pode ser apresentado no Painel de Leitura ao visualizar uma lista de mensagens, permitindo o processamento rápido de uma mensagem.

No entanto, por predefinição, se um utilizador tiver um painel de tarefas de suplemento aberto para uma mensagem no Painel de Leitura e, em seguida, selecionar uma nova mensagem, o painel de tarefas é 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 os painéis de tarefas afixáveis, o suplemento pode dar essa opção ao utilizador.

Modos suportados do Outlook

Os painéis de tarefas afixáveis são suportados nos modos Mensagem Compose e Leitura de Mensagens no Outlook. No entanto, a afixação não é suportada em diferentes modos. Isto acontece porque um suplemento pode ter UIs diferentes para botões e painéis de tarefas em cada modo. Por exemplo, se um utilizador afixar o painel de tarefas de um suplemento ao ler uma mensagem e, em seguida, criar uma nova mensagem, não verá o painel de tarefas do suplemento a partir da mensagem que está a compor. Para ver o painel de tarefas, o utilizador tem de ativar o suplemento a partir da mensagem que está a compor. Se o utilizador afixar o painel de tarefas, o painel de tarefas permanecerá afixado da próxima vez que o utilizador compor outra mensagem.

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 consoante o tipo de manifesto utilizado pelo suplemento.

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

<!-- Task pane button. -->
<Control xsi:type="Button" id="msgReadOpenPaneButton">
  <Label resid="paneReadButtonLabel" />
  <Supertip>
    <Title resid="paneReadSuperTipTitle" />
    <Description resid="paneReadSuperTipDescription" />
  </Supertip>
  <Icon>
    <bt:Image size="16" resid="green-icon-16" />
    <bt:Image size="32" resid="green-icon-32" />
    <bt:Image size="80" resid="green-icon-80" />
  </Icon>
  <Action xsi:type="ShowTaskpane">
    <SourceLocation resid="readTaskPaneUrl" />
    <SupportsPinning>true</SupportsPinning>
  </Action>
</Control>

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

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);
}

// 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. Isto 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);
  });
});

Afixação do painel de tarefas em seleção múltipla

No Outlook na Web e no novo Outlook no Windows, quando o painel de tarefas de um suplemento que implementa a funcionalidade de seleção múltipla de itens é aberto, é automaticamente afixado ao cliente do Outlook. Permanece afixado mesmo quando um utilizador muda para um item de correio diferente ou seleciona o ícone afixar no painel de tarefas. O painel de tarefas só pode ser fechado ao selecionar 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 seleção múltipla não é automaticamente afixado e fecha quando um utilizador muda para um item de correio diferente.

Implementar em utilizadores

Se planear publicar o seu suplemento do Outlook no AppSource e este estiver configurado com um painel de tarefas afixável, o conteúdo afixado do suplemento não pode ser estático. Ou seja, o conteúdo afixado tem de ser alterado consoante a mensagem ou compromisso que está atualmente aberto ou selecionado na caixa de correio. Isto garante que o seu suplemento passará na 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.