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

• Node.js (a versão mais recente de LTS). Visite o siteNode.js para baixar e instalar a versão certa para seu sistema operacional.

• 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.

• Office conectado a uma assinatura Microsoft 365 (incluindo o Office na web).

  Observação

  Se você ainda não tiver o Office, poderá se qualificar para uma assinatura de desenvolvedor Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.

• Outlook 2016 ou posterior no Windows (conectado a uma conta do Microsoft 365), Outlook no Mac, Outlook na Web ou novo Outlook no Windows (versão prévia).

Criar o projeto do suplemento

1. Execute o comando a seguir para criar um projeto de suplemento usando o gerador Yeoman. Uma pasta que contém o projeto será adicionada ao diretório atual.

   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.

   Observação

   Se você estiver usando Node.js versão 20.0.0 ou posterior, poderá ver um aviso quando o gerador executar a instalação de que você tem um mecanismo sem suporte. Estamos trabalhando em uma correção para isso. Enquanto isso, o aviso não afeta o gerador ou o projeto que você gera, portanto, ele pode ser ignorado.

   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 editor de código, abra o arquivo ./src/taskpane/taskpane.jse adicione o código a seguir à função de execução . 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;
   

   Seu arquivotaskpane.js agora deve conter o código a seguir.

   /*
    * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
    * See LICENSE in the project root for license information.
    */
   
   /* global document, Office */
   
   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;
     }
   });
   
   export async function run() {
     // 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, não HTTP, mesmo enquanto você estiver desenvolvendo. Se você for solicitado a instalar um certificado depois de executar um dos comandos a seguir, aceite o prompt para instalar o certificado que o gerador Yeoman fornece. 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. Quando você executa esse comando, o servidor Web local é iniciado e seu suplemento é sideload.

   npm start
   

   Observação

   Se o suplemento não tiver sido carregado automaticamente, siga as instruções nos suplementos do Sideload Outlook para testar para carregar manualmente o suplemento no Outlook.

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 escolha o botão Mostrar Painel de Tarefas na faixa de opções para abrir o painel de tarefas de suplemento.

   

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 ou posterior com a carga de trabalho de desenvolvimento do Office/SharePoint instalada

  Observação

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

• Office conectado a uma assinatura Microsoft 365 (incluindo o Office na web).

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 seu suplemento, o Visual Studio hospeda o aplicativo Web no servidor IIS (Serviços de Informações da Internet) 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 recém-criado do Outlook pressionando F5 ou escolhendo o botão Iniciar . O suplemento será hospedado localmente no IIS.

2. Na caixa de diálogo Conectar-se à conta de email do Exchange , insira o endereço de email e a senha da sua conta Microsoft e 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-se à conta de email do Exchange solicitar repetidamente que você entre ou receba um erro de que não está autorizado, a autenticação básica poderá ser desativada para contas em seu locatário do Microsoft 365. Para testar esse suplemento, tente entrar novamente depois de definir a propriedade Usar auth multifator como True na seção Implantação da caixa de diálogo Propriedades do projeto do Suplemento Web ou entrar usando uma conta Microsoft .

3. Sua caixa de correio é aberta em Outlook na Web. Selecione ou abra uma mensagem.

   Dica

   Você também pode testar o suplemento no Outlook no Windows enquanto o servidor IIS estiver em execução.

4. Na mensagem, navegue até a barra de ações e selecione Aplicativos.

   

5. Na lista de suplementos, selecione Meu Suplemento do Office e escolha Mostrar painel de tarefas.

   

6. Exiba as propriedades da mensagem selecionada no painel de tarefas que é aberto.

   

   Observação

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

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.

Solução de problemas

• Verifique se o ambiente está pronto para o desenvolvimento do Office seguindo as instruções em Configurar seu ambiente de desenvolvimento.

• A etapa automática npm install que o Yo Office executa pode falhar. Se você vir erros ao tentar executar npm start, navegue até a pasta de projeto recém-criada em um prompt de comando e execute npm installmanualmente . Para obter mais informações sobre o Yo Office, consulte Criar projetos de suplemento do Office usando o Gerador yeoman.

• Se o suplemento mostrar um erro (por exemplo, "Esse suplemento não pôde ser iniciado. Feche essa caixa de diálogo para ignorar o problema ou clique em "Reiniciar" para tentar novamente.") ao pressionar F5 ou escolher Depurar>Iniciar Depuração no Visual Studio, consulte Depurar suplementos do Office no Visual Studio para outras opções de depuração.

• Alguns dos códigos de exemplo usam JavaScript ES6. Isso não é compatível com versões mais antigas do Office que usam o mecanismo do navegador Trident (Internet Explorer 11). Para obter informações sobre como dar suporte a essas plataformas em seu suplemento, consulte Suporte a versões mais antigas da Microsoft webviews e office. Se você ainda não tiver uma assinatura do Microsoft 365 a ser usada para desenvolvimento, poderá se qualificar para uma assinatura de desenvolvedor Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.

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.

Exemplos de código

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

Confira também

• Manifesto XML dos Suplementos do Office
• Usando o Visual Studio Code para publicar