Criar seu primeiro suplemento do Outlook

Neste artigo, você acompanhará o processo de criação de um suplemento do painel de tarefas do Outlook que exibe pelo menos uma propriedade da mensagem selecionada.

Criar o suplemento

Você pode criar um suplemento do Office usando o Gerador Yeoman para suplementos do Office ou Visual Studio. O gerador Yeoman cria um projeto Node.js que pode ser gerenciado com o Visual Studio Code ou com qualquer outro editor, enquanto o Visual Studio cria uma solução do Visual Studio. Selecione a guia do que você deseja usar e, em seguida, siga as instruções para criar o suplemento e testá-lo localmente.

Gerador do Yeoman

Pré-requisitos

Observação

Se você não conhece o Node.js ou o npm, deve começar configurando seu ambiente de desenvolvimento.

• Node.js (a versão mais recente de LTS).

• A versão mais recente do Yeoman e do Yeoman gerador de Suplementos do Office. Para instalar essas ferramentas globalmente, execute o seguinte comando por meio do prompt de comando.

  npm install -g yo generator-office
  

  Observação

  Mesmo se você já instalou o gerador Yeoman, recomendamos atualizar seu pacote para a versão mais recente do npm.

• Visual Studio Code (VS Code) ou seu editor de código preferido

• Outlook 2016 ou posterior no Windows (conectado a uma conta do Microsoft 365) ou Outlook na Web

Criar o projeto do suplemento

1. Execute o comando a seguir para criar um projeto de suplemento usando o gerador Yeoman.

   yo office
   

   Observação

   Ao executar o comando yo office, você receberá informações sobre as políticas de coleta de dados de Yeoman e as ferramentas da CLI do suplemento do Office. Use as informações fornecidas para responder às solicitações como achar melhor.

   Quando solicitado, forneça as informações a seguir para criar seu projeto de suplemento.

   • Escolha o tipo de projeto - Office Add-in Task Pane project

   • Escolha o tipo de script - JavaScript

   • Qual será o nome do suplemento? - My Office Add-in

   • Você gostaria de proporcionar suporte para qual aplicativo cliente do Office? - Outlook

   

   Depois que você concluir o assistente, o gerador criará o projeto e instalará os componentes Node de suporte.

   Dica

   Você pode ignorar as orientações da próximas etapas fornecidas pelo gerador Yeoman após a criação do projeto de suplemento. As instruções passo a passo deste artigo fornecem todas as orientações necessárias para concluir este tutorial.

2. Navegue até a pasta raiz do projeto do aplicativo Web.

   cd "My Office Add-in"
   

Explore o projeto

O projeto de suplemento que você criou com o gerador do Yeoman contém um exemplo de código para um suplemento de painel de tarefas bem básico.

• O arquivo ./manifest.xml no diretório raiz do projeto define as configurações e os recursos do suplemento.
• O arquivo ./src/taskpane/taskpane.html contém a marcação HTML do painel de tarefas.
• O arquivo ./src/taskpane/taskpane.css contém o CSS que é aplicado ao conteúdo no painel de tarefas.
• O arquivo ./src/taskpane/taskpane.js contém o código da API JavaScript do Office que facilita a interação entre o painel de tarefas e o Outlook.

Atualizar o código

1. Abra o projeto no VS Code ou no seu editor de código preferido.

   Dica

   No Windows, navegue até o diretório raiz do projeto por meio da linha de comando e, em seguida, insira code . para abrir essa pasta no VS Code. No Mac, você precisará adicionar o comando code ao caminho antes de poder usá-lo para abrir a pasta do projeto no VS Code.

2. Abra o arquivo ./src/taskpane/taskpane.html e substitua todo <o elemento main> (dentro do <elemento body>) pela marcação a seguir. A próxima marcação adiciona uma etiqueta onde o script no ./src/taskpane/taskpane.js gravará os dados.

   <main id="app-body" class="ms-welcome__main" style="display: none;">
       <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
       <p><label id="item-subject"></label></p>
       <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. No seu editor de código, abra o arquivo ./src/taskpane/taskpane.js e adicione o seguinte código dentro da função executar. Este código usa a API JavaScript do Office para obter uma referência da mensagem atual e gravar o seu valor de propriedade subject no painel de tarefas.

   // Get a reference to the current message
   const item = Office.context.mailbox.item;
   
   // Write message property value to the task pane
   document.getElementById("item-subject").innerHTML = "<b>Subject:</b> <br/>" + item.subject;
   

Experimente

Observação

Os Suplementos do Office devem usar HTTPS, e não HTTP, mesmo durante o desenvolvimento. Se você for solicitado a instalar um certificado após executar um dos seguintes comandos, aceite a solicitação para instalar o certificado que o gerador do Yeoman fornecer. Você também pode executar o prompt de comando ou terminal como administrador para que as alterações sejam feitas.

1. Execute o seguinte comando no diretório raiz do seu projeto. Ao executar esse comando, o servidor Web local será iniciado e seu complemento será sideload.

   npm start
   

2. No Outlook, exiba uma mensagem no Painel de leitura ou abra a mensagem em sua própria janela.

3. Escolha a guia Página Inicial (ou a guia Mensagem, se você abriu a mensagem em uma nova janela), e em seguida o botão Mostrar Painel de Tarefas na faixa de opções para abrir o painel de tarefas do suplemento.

   

   Observação

   Se você receber a mensagem de erro "Não é possível abrir este suplemento do localhost" no painel de tarefas, siga as etapas descritas no artigo de solução de problemas.

4. Quando solicitado com a caixa de diálogo Parar na Carga do Modo de Exibição da Web, selecione OK.

   Observação

   Se você selecionar Cancelar, a caixa de diálogo não será mostrada novamente enquanto esta instância do suplemento estiver em execução. No entanto, se você reiniciar o suplemento, você verá a caixa de diálogo novamente.

5. Role para parte inferior do painel de tarefas e escolha o link Executar para escrever o assunto da mensagem no painel de tarefas.

   

   

Próximas etapas

Parabéns, você criou o seu primeiro suplemento do painel de tarefas do Outlook! Em seguida, saiba mais sobre os recursos de um suplemento do Outlook e crie um suplemento mais complexo seguindo as etapas deste tutorial de suplemento do Word.

Visual Studio

Pré-requisitos

• Visual Studio 2019 com a carga de trabalho de desenvolvimento do Office/SharePoint instalada

  Observação

  Se você já instalou o Visual Studio 2019, use o Instalador do Visual Studio para garantir que a carga de trabalho de desenvolvimento do Office/SharePoint seja instalada.

• Microsoft 365

  Observação

  Se você não tiver uma assinatura do Microsoft 365, poderá obter uma assinatura gratuita inscrevendo-se no programa para desenvolvedores do Microsoft 365.

Criar o projeto do suplemento

1. Na barra de menus do Visual Studio, selecione Arquivo>Novo>Projeto.

2. Na lista de tipos de projeto sob Visual C# ou Visual Basic, expanda a opção Office/SharePoint, escolha Suplementos e depois Suplemento da Web do Outlook como o tipo de projeto.

3. Dê um nome ao projeto e escolha OK.

4. O Visual Studio cria uma solução, e os dois projetos dele aparecem no Gerenciador de Soluções. O arquivo MessageRead.html é aberto no Visual Studio.

Explorar a solução do Visual Studio

Ao concluir o assistente, o Visual Studio cria uma solução que contém dois projetos.

Projeto	Descrição
Projeto de suplemento	Contém somente um arquivo de manifesto XML, que contém todas as configurações que descrevem o suplemento. As configurações ajudam o aplicativo do Office a determinar quando o suplemento deverá ser ativado e onde ele deverá aparecer. O Visual Studio gera o conteúdo desse arquivo para que você possa executar o projeto e usar o suplemento imediatamente. Você pode alterar essas configurações a qualquer momento modificando o arquivo XML.
Projeto de aplicativo Web	Contém as páginas de conteúdo do suplemento, incluindo todos os arquivos e referências de arquivo de que você precisa para desenvolver páginas HTML e JavaScript com reconhecimento do Office. Enquanto você desenvolve o suplemento, o Visual Studio hospeda o aplicativo Web no servidor IIS local. Quando estiver pronto para publicar, você precisará implantar este projeto de aplicativo Web em um servidor Web.

Atualizar o código

1. MessageRead.html especifica o HTML que será renderizado no painel de tarefas do suplemento. Em MessageRead.html, substitua o <elemento body> pela marcação a seguir e salve o arquivo.

   <body class="ms-font-m ms-welcome">
       <div class="ms-Fabric content-main">
           <h1 class="ms-font-xxl">Message properties</h1>
           <table class="ms-Table ms-Table--selectable">
               <thead>
                   <tr>
                       <th>Property</th>
                       <th>Value</th>
                   </tr>
               </thead>
               <tbody>
                   <tr>
                       <td><strong>Id</strong></td>
                       <td class="prop-val"><code><label id="item-id"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>Subject</strong></td>
                       <td class="prop-val"><code><label id="item-subject"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>Message Id</strong></td>
                       <td class="prop-val"><code><label id="item-internetMessageId"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>From</strong></td>
                       <td class="prop-val"><code><label id="item-from"></label></code></td>
                   </tr>
               </tbody>
           </table>
       </div>
   </body>
   

2. Abra o arquivo MessageRead.js na raiz do projeto do aplicativo Web. Este arquivo especifica o script do suplemento. Substitua todo o conteúdo pelo código a seguir e salve o arquivo.

   'use strict';
   
   (function () {
   
       Office.onReady(function () {
           // Office is ready
           $(document).ready(function () {
               // The document is ready
               loadItemProps(Office.context.mailbox.item);
           });
       });
   
       function loadItemProps(item) {
           // Write message property values to the task pane
           $('#item-id').text(item.itemId);
           $('#item-subject').text(item.subject);
           $('#item-internetMessageId').text(item.internetMessageId);
           $('#item-from').html(item.from.displayName + " <" + item.from.emailAddress + ">");
       }
   })();
   

3. Abra o arquivo MessageRead.css na raiz do projeto do aplicativo Web. Este arquivo especifica os estilos personalizados para o suplemento. Substitua todo o conteúdo pelo código a seguir e salve o arquivo.

   html,
   body {
       width: 100%;
       height: 100%;
       margin: 0;
       padding: 0;
   }
   
   td.prop-val {
       word-break: break-all;
   }
   
   .content-main {
       margin: 10px;
   }
   

Atualizar o manifesto

1. Abra o arquivo de manifesto XML do projeto do Suplemento. Este arquivo define as configurações e os recursos do suplemento.

2. O <elemento ProviderName> tem um valor de espaço reservado. Substitua-o com seu nome.

3. O atributo DefaultValue do <elemento DisplayName> tem um espaço reservado. Substitua-o por My Office Add-in.

4. O atributo DefaultValue do <elemento Description> tem um espaço reservado. Substitua-o por My First Outlook add-in.

5. Salve o arquivo.

   ...
   <ProviderName>John Doe</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <!-- The display name of your add-in. Used on the store and various places of the Office UI such as the add-ins dialog. -->
   <DisplayName DefaultValue="My Office Add-in" />
   <Description DefaultValue="My First Outlook add-in"/>
   ...
   

Experimente

1. Usando o Visual Studio, teste o suplemento do Outlook recém-criado ao pressionar F5 ou o botão Iniciar. O suplemento será hospedado localmente no IIS.

2. Na caixa de diálogoConectar-se à conta de email do Exchange, digite o endereço de email e senha da sua conta da Microsoft e, em seguida, escolha Conectar. Quando a página de login do Outlook.com for aberta em um navegador, entre em sua conta de email com as mesmas credenciais que você inseriu anteriormente.

   Observação

   Se a caixa de diálogo Conectar à conta de email Exchange solicitar repetidamente que você faça o login ou se você receber um erro de que não está autorizado, o Basic Auth pode ser desativado para contas em seu locatário Microsoft 365. Para testar este suplemento, tente entrar novamente após definir a propriedade Usar multi-fator auth para True no diálogo de propriedades do projeto Web Add-in, ou entre usando uma conta Microsoft em seu lugar.

3. No Outlook na Web, escolha ou abra uma mensagem.

4. Dentro da mensagem, localize as reticências do menu de estouro que contém o botão do suplemento.

   

5. No menu excedente, localize o botão do suplemento.

   

6. Clique no botão para abrir o painel de tarefas do suplemento.

   

   Observação

   Se o painel de tarefas não carregar, tente verificar abrindo-o em um navegador no mesmo computador.

Exemplos de código

• Suplemento do Outlook "Olá mundo": saiba como criar um suplemento simples do Office com apenas um manifesto, uma página da Web HTML e um logotipo.

Próximas etapas

Parabéns, você criou o seu primeiro suplemento do painel de tarefas do Outlook! Em seguida, saiba mais sobre como desenvolver suplementos do Office com o Visual Studio.

Confira também

• Usando o Visual Studio Code para publicar