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 mostram como configurar o suplemento para obter a linha de assunto e o endereço de e-mail do remetente 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. Para obter mais informações sobre o comportamento de afixação do painel de tarefas em suplementos de seleção múltipla, veja Afixação do painel de tarefas em suplementos de seleção múltipla.

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-l">Get information about each selected message</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">Get information</span>
    </div>
</main>

  3. Apenas para o Outlook clássico no Windows. Substitua o elemento de script existente pela seguinte marcação. Isto faz referência à versão de pré-visualização da API JavaScript do Office.

    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>

    Observação

    A versão de pré-visualização da API javaScript do Office é utilizada porque estas instruções implementam os loadItemByIdAsync métodos e unloadAsync , que estão atualmente em pré-visualização. Se o seu suplemento de seleção múltipla não implementar estes métodos, utilize https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js antes. Para obter mais informações, veja Referenciar a biblioteca da API JavaScript do Office.

  4. 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. Substitua a Office.onReady() função pelo seguinte:

    let list;

Office.onReady((info) => {
  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;
    list = document.getElementById("selected-items");

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

  3. Salve suas alterações.

Obter propriedades e executar operações em mensagens selecionadas

Agora que registou um processador de eventos, o suplemento pode agora obter propriedades ou executar operações em várias mensagens selecionadas. Existem duas formas de processar as mensagens selecionadas. A utilização de cada opção depende das propriedades e operações necessárias para o seu cenário.

  • Chame o método getSelectedItemsAsync para obter as seguintes propriedades.

    • Booleano de anexo
    • ID de Conversação
    • ID da mensagem da Internet
    • Item ID
    • Modo de item (Read ou Compose)
    • Tipo de item (Message é o único tipo suportado neste momento)
    • Linha de assunto

  • Chame o método loadItemByIdAsync (pré-visualização) para obter propriedades que não são fornecidas pelo getSelectedItemsAsync ou para executar operações nas mensagens selecionadas. O loadItemByIdAsync método carrega uma mensagem selecionada de cada vez através do ID dos Serviços Web exchange (EWS) da mensagem. Para obter os IDs do EWS das mensagens selecionadas, recomendamos que chame getSelectedItemsAsync. Depois de processar uma mensagem selecionada com loadItemByIdAsynco , tem de chamar o método unloadAsync (pré-visualização) antes de chamar loadItemByIdAsync outra mensagem selecionada.

    Dica

    Antes de utilizar o loadItemByIdAsync método , determine se já pode aceder às propriedades de que precisa com getSelectedItemsAsync. Se puder, não precisa de ligar loadItemByIdAsyncpara .

O exemplo seguinte implementa os getSelectedItemsAsync métodos e loadItemByIdAsync para obter a linha de assunto e o endereço de e-mail do remetente de cada mensagem selecionada.

Observação

O loadItemByIdAsync método está atualmente em pré-visualização no Outlook clássico no Windows. Para pré-visualizar esta API, instale a Versão 2405 (Compilação 17606.10000) ou posterior. Em seguida, adira ao programa Microsoft 365 Insider e selecione a opção Canal Beta .

  1. No taskpane.js, substitua a função existente run pelo seguinte código.

    export async function run() {
  // Clear the list of previously selected messages, if any.
  clearList(list);

  // Get the subject line and sender's email address of each selected message 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;
    }

    const selectedItems = asyncResult.value;
    getItemInfo(selectedItems);
  });
}

// Gets the subject line and sender's email address of each selected message.
async function getItemInfo(selectedItems) {
  for (const item of selectedItems) {
    addToList(item.subject);
    // The loadItemByIdAsync method is currently only available to preview in classic Outlook on Windows.
    if (Office.context.diagnostics.platform === Office.PlatformType.PC) {
      await getSenderEmailAddress(item);
    }
  }
}

// Gets the sender's email address of each selected message.
async function getSenderEmailAddress(item) {
  const itemId = item.itemId;
  await new Promise((resolve) => {
    Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        return;
      }

      const loadedItem = result.value;
      const sender = loadedItem.from.emailAddress;
      appendToListItem(sender);

      // Unload the current message before processing another selected message.
      loadedItem.unloadAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        resolve();
      });
    });
  });
}

// Clears the list in the task pane.
function clearList(list) {
  while (list.firstChild) {
    list.removeChild(list.firstChild);
  }
}

// Adds an item to a list in the task pane.
function addToList(item) {
  const listItem = document.createElement("li");
  listItem.textContent = item;
  list.appendChild(listItem);
}

// Appends data to the last item of the list in the task pane.
function appendToListItem(data) {
  const listItem = list.lastChild;
  listItem.textContent += ` (${data})`;
}

  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. A localização do suplemento varia consoante o seu cliente do Outlook. Para obter orientações, consulte Utilizar suplementos no Outlook.

  5. No painel de tarefas, selecione Obter informações. É apresentada uma lista das linhas de assunto e endereços de e-mail do remetente das mensagens selecionadas no painel de tarefas.

    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.
  • O loadItemByIdAsync método só processa uma mensagem selecionada de cada vez. Lembre-se de chamar unloadAsync depois loadItemByIdAsync de concluir o processamento da mensagem. Desta forma, o suplemento pode carregar e processar a próxima mensagem selecionada.
  • Normalmente, só pode executar operações get numa mensagem selecionada que é carregada com o loadItemByIdAsync método . No entanto, gerir as categorias de uma mensagem carregada é uma exceção. Pode adicionar, obter e remover categorias de uma mensagem carregada.
  • O loadItemByIdAsync método é suportado no painel de tarefas e nos suplementos do comando de função. Este método não é suportado em suplementos de ativação baseados em eventos .

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