Partilhar via

Ativar o seu suplemento do Outlook em várias mensagens

  • Artigo

Com a funcionalidade de seleção múltipla de itens, o seu suplemento do Outlook pode agora ativar e realizar operações em várias mensagens selecionadas de uma só vez. Determinadas operações, como carregar mensagens para o seu sistema de Gestão de Relações com Os Clientes (CRM) ou categorizar vários itens, podem agora ser facilmente concluídas com um único clique.

As secções seguintes explicam como configurar o suplemento para obter o assunto de várias mensagens no modo de leitura.

Observação

O suporte para a funcionalidade de seleção múltipla de itens foi introduzido no conjunto de requisitos 1.13, com propriedades de itens adicionais agora disponíveis em conjuntos de requisitos subsequentes. Confira, clientes e plataformas que oferecem suporte a esse conjunto de requisitos.

Configurar seu ambiente

Conclua o guia de introdução do Outlook para criar um projeto de suplemento com o gerador Yeoman para Suplementos do Office.

Configurar o manifesto

  1. No seu editor de código preferido, abra o projeto de início rápido do Outlook que criou.

  2. Abra o ficheiro manifest.json localizado na raiz do projeto.

  3. Na matriz "authorization.permissions.resourceSpecific", altere o valor da propriedade "name" para "Mailbox.ReadWrite.User". Deverá ter o seguinte aspeto quando terminar.

    "authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "Mailbox.ReadWrite.User",
                "type": "Delegated"
            }
        ]
    }
},

  4. No primeiro objeto da matriz "extensions.runtimes", faça as seguintes alterações.

    1. Altere a propriedade "requirements.capabilities.minVersion" para "1.13".
    2. No mesmo objeto "actions", adicione a propriedade "supportsNoItemContext" e defina-a como true.
    3. No mesmo objeto "actions", adicione a propriedade "multiselect" e defina-a como true.

    O código deverá ter o seguinte aspeto depois de ter feito as alterações.

    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ]
        },
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "TaskPaneRuntimeShow",
                "type": "openPage",
                "pinnable": false,
                "view": "dashboard",
                "supportsNoItemContext": true,
                "multiselect": true
            }
        ]
    },
    ...
]

  5. Elimine o segundo objeto da matriz "extensions.runtimes", cujo "id" é "CommandsRuntime".

  6. Na matriz "extensions.ribbons.tabs.controls", elimine o segundo objeto, cujo "id" é "ActionButton".

  7. Salve suas alterações.

Observação

Se ativar a funcionalidade de seleção múltipla de itens no seu suplemento, o suplemento suportará automaticamente a funcionalidade de contexto sem item , mesmo que não esteja explicitamente configurado no manifesto.

Configurar o painel de tarefas

O item multi-select baseia-se no evento SelectedItemsChanged para determinar quando as mensagens são selecionadas ou desselecionadas. Este evento requer uma implementação do painel de tarefas.

  1. Na pasta ./src/taskpane , abra taskpane.html.

  2. No elemento do< corpo>, substitua todo <o elemento main> pela seguinte marcação.

    <main id="app-body" class="ms-welcome__main">
    <h2 class="ms-font-xl">Retrieve the subject line of multiple messages with one click!</h2>
    <ul id="selected-items"></ul>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Run</span>
    </div>
</main>

  3. Salve suas alterações.

Implementar um processador para o evento SelectedItemsChanged

Para alertar o suplemento quando o SelectedItemsChanged evento ocorrer, tem de registar um processador de eventos com o addHandlerAsync método .

  1. Na pasta ./src/taskpane , abra taskpane.js.

  2. Na função Office.onReady() de chamada de retorno, substitua o código existente pelo seguinte:

    if (info.host === Office.HostType.Outlook) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
    document.getElementById("run").onclick = run;

    // Register an event handler to identify when messages are selected.
    Office.context.mailbox.addHandlerAsync(Office.EventType.SelectedItemsChanged, run, asyncResult => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      console.log("Event handler added.");
    });
}

Obter a linha de assunto das mensagens selecionadas

Agora que registou um processador de eventos, chama o método getSelectedItemsAsync para obter a linha de assunto das mensagens selecionadas e registá-las no painel de tarefas. O getSelectedItemsAsync método também pode ser utilizado para obter outras propriedades da mensagem, como o ID do item, o tipo de item (Message é o único tipo suportado neste momento) e o modo de item (Read ou Compose).

  1. No taskpane.js, navegue para a run função e insira o seguinte código.

    // Clear list of previously selected messages, if any.
const list = document.getElementById("selected-items");
while (list.firstChild) {
    list.removeChild(list.firstChild);
}

// Retrieve the subject line of the selected messages and log it to a list in the task pane.
Office.context.mailbox.getSelectedItemsAsync(asyncResult => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;      
    }

    asyncResult.value.forEach(item => {
        const listItem = document.createElement("li");
        listItem.textContent = item.subject;
        list.appendChild(listItem);
    });
});

  2. Salve suas alterações.

Experimente

  1. Num terminal, execute o seguinte código no diretório de raiz do projeto. Esta ação inicia o servidor Web local e efetua sideloads do seu suplemento.

    npm start

    Dica

    Se o seu suplemento não carregar automaticamente em sideload, siga as instruções em Sideload Suplementos do Outlook para testar para o sideload manualmente no Outlook.

  2. No Outlook, certifique-se de que o Painel de Leitura está ativado. Para ativar o Painel de Leitura, consulte Utilizar e configurar o Painel de Leitura para pré-visualizar mensagens.

  3. Navegue para a sua caixa de entrada e selecione múltiplas mensagens ao premir Ctrl enquanto seleciona mensagens.

  4. Selecione Mostrar Painel de Tarefas no friso.

  5. No painel de tarefas, selecione Executar para ver uma lista das linhas de assunto das mensagens selecionadas.

    Uma lista de exemplo das linhas de assunto obtidas a partir de várias mensagens selecionadas.

  6. Quando quiser parar o servidor Web local e desinstalar o suplemento, siga as instruções aplicáveis:

    • Para parar o servidor, execute o seguinte comando. Se tiver utilizado npm start, o seguinte comando também deve desinstalar o suplemento.

      npm stop

    • Se tiver carregado manualmente o suplemento em sideload, consulte Remover um suplemento sideloaded.

Comportamento e limitações de seleção múltipla de itens

A seleção múltipla de itens só suporta mensagens numa caixa de correio do Exchange nos modos de leitura e composição. Um suplemento do Outlook só é ativado em várias mensagens se forem cumpridas as seguintes condições.

  • As mensagens têm de ser selecionadas a partir de uma caixa de correio do Exchange de cada vez. As caixas de correio que não sejam do Exchange não são suportadas.
  • As mensagens têm de ser selecionadas a partir de uma pasta de caixa de correio de cada vez. Um suplemento não é ativado em várias mensagens se estiverem localizadas em pastas diferentes, a menos que a vista Conversações esteja ativada. Para obter mais informações, consulte Seleção múltipla em conversações.
  • Um suplemento tem de implementar um painel de tarefas para detetar o SelectedItemsChanged evento.
  • O Painel de Leitura no Outlook tem de estar ativado. Uma exceção é se a funcionalidade de seleção múltipla do item estiver ativada através da funcionalidade de contexto sem item no manifesto. Para saber mais, consulte Ativar o seu suplemento do Outlook sem o Painel de Leitura ativado ou uma mensagem selecionada.
  • Pode selecionar um máximo de 100 mensagens de cada vez.

Observação

Os convites para reuniões e respostas são considerados mensagens, não compromissos, pelo que podem ser incluídos numa seleção.

Seleção múltipla em conversações

A seleção múltipla de itens suporta a vista Conversações , quer esteja ativada na sua caixa de correio ou em pastas específicas. A tabela seguinte descreve os comportamentos esperados quando as conversações são expandidas ou fechadas, quando o cabeçalho da conversação é selecionado e quando as mensagens de conversação estão localizadas numa pasta diferente daquela que está atualmente em vista.

Seleção Vista de conversação expandida Vista de conversação fechada
O cabeçalho de conversação está selecionado Se o cabeçalho da conversação for o único item selecionado, não é ativado um suplemento que suporte seleção múltipla. No entanto, se também estiverem selecionadas outras mensagens que não sejam de cabeçalho, o suplemento só será ativado nessas mensagens e não no cabeçalho selecionado. O comportamento difere consoante o cliente do Outlook.

Outlook no Windows (clássico) e no Mac:
A mensagem mais recente (ou seja, a primeira mensagem na pilha de conversação) é incluída na seleção da mensagem.

Se a mensagem mais recente na conversação estiver localizada noutra pasta a partir da que está atualmente em vista, a mensagem subsequente na pilha localizada na pasta atual é incluída na seleção.

Outlook na Web e o novo Outlook no Windows:
Todas as mensagens na pilha de conversação estão selecionadas. Isto inclui mensagens na conversação que estão localizadas em pastas diferentes das que estão atualmente visíveis.
Várias mensagens selecionadas numa pilha de conversação estão localizadas na mesma pasta que atualmente em vista Todas as mensagens escolhidas na mesma conversação estão incluídas na seleção. Não aplicável. Tem de expandir a pilha de conversação para selecionar várias mensagens a partir da mesma.
Várias mensagens selecionadas numa pilha de conversação estão localizadas em pastas diferentes das que estão atualmente visíveis Todas as mensagens escolhidas na mesma conversação estão incluídas na seleção. Não aplicável. Tem de expandir a pilha de conversação para selecionar várias mensagens a partir da mesma.

Observação

Em todos os clientes do Outlook, não pode selecionar várias mensagens que pertencem a conversações diferentes. Se expandir uma conversação diferente enquanto outra conversação é expandida, a vista da conversação atualmente expandida é fechada e todas as mensagens selecionadas são desselecionadas. No entanto, pode selecionar múltiplas mensagens da mesma conversação expandida e mensagens que não fazem parte de qualquer conversação ao mesmo tempo.

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

No Outlook na Web e no novo Outlook no Windows, quando o painel de tarefas de um suplemento de seleção múltipla é 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 no Windows (clássico) e no Mac, o painel de tarefas não é afixado automaticamente e fecha quando um utilizador muda para um item de correio diferente.

Próximas etapas

Agora que ativou o suplemento para funcionar em várias mensagens selecionadas, pode expandir as capacidades do suplemento e melhorar ainda mais a experiência do utilizador. Explore a execução de operações mais complexas com os IDs de itens das mensagens selecionadas com serviços, como o Microsoft Graph.

Confira também