Ativar seu suplemento do Outlook em várias mensagens

Com o recurso de seleção múltipla de item, seu suplemento do Outlook agora pode ativar e executar operações em várias mensagens selecionadas de uma só vez. Certas operações, como carregar mensagens para o sistema CRM (Gerenciamento de Relacionamento com o Cliente) ou categorizar vários itens, agora podem ser facilmente concluídas com um único clique.

As seções a seguir mostram como configurar seu suplemento para recuperar a linha do assunto e o endereço de email do remetente de várias mensagens no modo de leitura.

Observação

O suporte para o recurso de seleção múltipla de itens foi introduzido no conjunto de requisitos 1.13, com propriedades de item 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 início rápido do Outlook para criar um projeto de suplemento com o gerador Yeoman para Suplementos do Office.

Configurar o manifesto

Observação

Atualmente, a implementação do recurso de seleção múltipla de itens com um manifesto unificado para o Microsoft 365 só tem suporte no Outlook clássico no Windows. Para outras plataformas compatíveis, use o manifesto somente do suplemento.

  1. No editor de código de sua preferência, abra o projeto de início rápido do Outlook que você criou.

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

  3. "authorization.permissions.resourceSpecific" Na matriz, altere o valor da "name" propriedade para "Mailbox.ReadWrite.User". Deve ser semelhante ao seguinte quando você terminar.

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

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

    1. Altere a "requirements.capabilities.minVersion" propriedade para "1.15". Embora o recurso de seleção múltipla de item tenha sido introduzido no conjunto de requisitos 1.13, este exemplo usa aprimoramentos de conjuntos de requisitos posteriores.
    2. No mesmo "actions" objeto, adicione a propriedade e defina-a "supportsNoItemContext" como true.
    3. No mesmo objeto "actions", adicione a "multiselect" propriedade e defina-a como true.

    Seu código deve se parecer com o seguinte depois de fazer as alterações.

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

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

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

  7. Salve suas alterações.

Observação

Se você ativar o recurso de seleção múltipla de item em seu suplemento, seu suplemento dará suporte automaticamente ao recurso de contexto sem item , mesmo que não esteja explicitamente configurado no manifesto. Para obter mais informações sobre o comportamento de fixação do painel de tarefas em suplementos de seleção múltipla, consulte Fixação do painel de tarefas em suplementos de seleção múltipla.

Configurar o painel de tarefas

A seleção múltipla de item depende do evento SelectedItemsChanged para determinar quando as mensagens são selecionadas ou desmarcadas. Esse evento requer a implementação de um painel de tarefas.

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

  2. <body> No elemento, substitua todo o <main> elemento 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. Salve suas alterações.

Implementar um manipulador para o evento SelectedItemsChanged

Para alertar seu suplemento quando o SelectedItemsChanged evento ocorrer, você deve registrar um manipulador de eventos usando 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 você registrou um manipulador de eventos, seu suplemento agora pode obter propriedades ou executar operações em várias mensagens selecionadas. Existem duas maneiras de processar mensagens selecionadas. O uso de cada opção depende das propriedades e operações necessárias para seu cenário.

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

    • Anexo booleano
    • ID da conversa
    • ID da mensagem de Internet
    • Item ID
    • Modo de item (Read ou Compose)
    • Tipo de item (Message é o único tipo com suporte no momento)
    • Linha de assunto

  • Chame o método loadItemByIdAsync para obter propriedades que não são fornecidas por getSelectedItemsAsync ou para executar operações nas mensagens selecionadas. O loadItemByIdAsync método carrega uma mensagem selecionada por vez usando a ID do Exchange Web Services (EWS) da mensagem. Para obter as IDs EWS das mensagens selecionadas, recomendamos chamar getSelectedItemsAsync. Depois de processar uma mensagem selecionada usando loadItemByIdAsync, você deve chamar o método unloadAsync antes de chamar loadItemByIdAsync outra mensagem selecionada.

    Dica

    • Os loadItemByIdAsync métodos and unloadAsync foram introduzidos no conjunto de requisitos 1.15. Saiba mais sobre as plataformas e clientes com suporte.
    • Antes de usar o método, determine se você já pode acessar as propriedades necessárias usando getSelectedItemsAsynco loadItemByIdAsync . Se puder, você não precisará chamar loadItemByIdAsync.

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

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

    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 them 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);
    if (Office.context.requirements.isSetSupported("Mailbox", "1.15")) {
      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. Em um terminal, execute o código a seguir no diretório raiz do seu projeto. Isso inicia o servidor Web local e faz o sideload do suplemento.

    npm start

    Observação

    • Quando você usa o gerador Yeoman pela primeira vez para desenvolver um suplemento do Office, seu navegador padrão abre uma janela onde você será solicitado a entrar em sua conta do Microsoft 365. Se uma janela de entrada não for exibida e você encontrar um erro de sideload ou tempo limite de logon, execute atk auth login m365 antes de executar npm start novamente.

    • Se o suplemento não foi carregado automaticamente, siga as instruções em Fazer sideload de suplementos do Outlook para testar o sideload manual do suplemento no Outlook.

  2. No Outlook, verifique se o Painel de Leitura está habilitado. Para habilitar o Painel de Leitura, confira Usar e configurar o Painel de Leitura para visualizar mensagens.

  3. Navegue até sua caixa de entrada e escolha várias mensagens segurando a tecla Ctrl enquanto seleciona as mensagens.

  4. Selecione Mostrar Painel de Tarefas. A localização do suplemento varia de acordo com o cliente Outlook. Para obter orientação, consulte Usar suplementos no Outlook.

  5. No painel de tarefas, selecione Obter informações. Uma lista das linhas de assunto das mensagens selecionadas e dos endereços de email do remetente é exibida no painel de tarefas.

    Uma lista de exemplo de linhas de assunto recuperadas de várias mensagens selecionadas.

  6. Quando você 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 você usou npm start, o comando a seguir também deve desinstalar o suplemento.

      npm stop

    • Se você carregou manualmente o suplemento, consulte Remover um suplemento com sideload.

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

A seleção múltipla de itens só dá suporte a mensagens em uma caixa de correio do Exchange nos modos de leitura e redação. Um suplemento do Outlook só é ativado em várias mensagens se as condições a seguir forem atendidas.

  • As mensagens devem ser selecionadas de uma caixa de correio do Exchange por vez. Não há suporte para caixas de correio que não são do Exchange.
  • As mensagens devem ser selecionadas de uma pasta de caixa de correio por vez. Um suplemento não é ativado em várias mensagens se elas estiverem localizadas em pastas diferentes, a menos que o modo de exibição de conversas esteja habilitado. Para obter mais informações, consulte Seleção múltipla em conversas.
  • Um suplemento deve implementar um painel de tarefas para detectar o SelectedItemsChanged evento.
  • O Painel de Leitura no Outlook deve estar habilitado. Uma exceção a isso é se o recurso de seleção múltipla de item estiver habilitado por meio do recurso de contexto sem item no manifesto. Para saber mais, consulte Ativar seu suplemento do Outlook sem o Painel de Leitura habilitado ou uma mensagem selecionada.
  • Um máximo de 100 mensagens podem ser selecionadas por vez.
  • O loadItemByIdAsync método processa apenas uma mensagem selecionada por vez. Lembre-se de ligar unloadAsync depois loadItemByIdAsync de concluir o processamento da mensagem. Dessa forma, o suplemento pode carregar e processar a próxima mensagem selecionada.
  • Normalmente, você só pode executar operações get em uma mensagem selecionada carregada usando o loadItemByIdAsync método. No entanto, gerenciar as categorias de uma mensagem carregada é uma exceção. Você pode adicionar, obter e remover categorias de uma mensagem carregada.
  • O loadItemByIdAsync método tem suporte no painel de tarefas e suplementos de comando de função. Não há suporte para esse método em suplementos de ativação baseada em eventos .

Observação

Convites e respostas para reuniões são considerados mensagens, não compromissos, e por isso podem ser incluídos em uma seleção.

Seleção múltipla em conversas

A seleção múltipla de itens dá suporte ao modo de exibição Conversas , esteja ele habilitado na sua caixa de correio ou em pastas específicas. A tabela a seguir descreve os comportamentos esperados quando as conversas são expandidas ou recolhidas, quando o cabeçalho da conversa é selecionado e quando as mensagens de conversa estão localizadas em uma pasta diferente da que está em exibição no momento.

Seleção Exibição de conversa expandida Exibição de conversa recolhida
O cabeçalho da conversa está selecionado Se o cabeçalho da conversa for o único item selecionado, um suplemento com suporte para seleção múltipla não será ativado. No entanto, se outras mensagens que não forem de cabeçalho também forem selecionadas, o suplemento só será ativado nelas e não no cabeçalho selecionado. O comportamento é diferente dependendo do cliente Outlook.

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

Se a mensagem mais recente da conversa estiver localizada em outra pasta da que está em exibição no momento, a mensagem subsequente na pilha localizada na pasta atual será incluída na seleção.

Outlook na Web e novo Outlook no Windows:
Todas as mensagens na pilha de conversas são selecionadas. Isso inclui mensagens na conversa que estão localizadas em pastas diferentes da que está sendo exibida no momento.
Várias mensagens selecionadas em uma pilha de conversas estão localizadas na mesma pasta que a que está sendo exibida no momento Todas as mensagens escolhidas na mesma conversa estão incluídas na seleção. Não aplicável. Você deve expandir a pilha de conversas para selecionar várias mensagens dela.
Várias mensagens selecionadas em uma pilha de conversas estão localizadas em pastas diferentes daquela atualmente em exibição Todas as mensagens escolhidas na mesma conversa estão incluídas na seleção. Não aplicável. Você deve expandir a pilha de conversas para selecionar várias mensagens dela.

Observação

Em todos os clientes Outlook, você não pode selecionar várias mensagens que pertencem a conversas diferentes. Se você expandir uma conversa diferente enquanto outra conversa é expandida, a visualização da conversa expandida no momento é recolhida e todas as mensagens selecionadas são desmarcadas. No entanto, você pode selecionar várias mensagens da mesma conversa expandida e mensagens que não fazem parte de nenhuma conversa ao mesmo tempo.

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

Quando você seleciona vários itens de email e inicia o painel de tarefas do suplemento de seleção múltipla, o comportamento de fixação do painel de tarefas varia dependendo do cliente Outlook.

  • Mac: o painel de tarefas permanece aberto mesmo quando um usuário alterna para um item de email diferente. O painel de tarefas só pode ser fechado selecionando o botão Fechar no painel de tarefas.
  • Windows (novo e clássico) e Web: o painel de tarefas não fica aberto quando o usuário alterna para um novo item. Para manter o painel de tarefas aberto, selecione o ícone de fixar no painel de tarefas.

Próximas etapas

Agora que você habilitou seu suplemento para operar em várias mensagens selecionadas, você pode estender os recursos do suplemento e aprimorar ainda mais a experiência do usuário. Explore a execução de operações mais complexas usando as IDs de item das mensagens selecionadas com serviços, como o Microsoft Graph.

Confira também

  • Last updated on