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 transferir e instalar a versão certa para o seu sistema operativo.

• 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 ainda não tiver o Office, poderá qualificar-se para uma subscrição de programador do Microsoft 365 E5 através do Programa para Programadores do Microsoft 365; para obter detalhes, veja as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.

• Outlook na Web, novo Outlook no Windows (pré-visualização), Outlook 2016 ou posterior no Windows (ligado a uma conta do Microsoft 365) ou Outlook no Mac.

Criar o projeto do suplemento

1. Execute o comando a seguir para criar um projeto de suplemento usando o gerador Yeoman. Será adicionada uma pasta que contém o projeto 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

   • Que manifesto gostaria de utilizar? - Escolha ou unified manifest for Microsoft 365XML manifest

   Observação

   O manifesto unificado do Microsoft 365 permite-lhe combinar um Suplemento do Outlook com uma aplicação do Teams como uma única unidade de desenvolvimento e implementação. Estamos a trabalhar para expandir o suporte para o manifesto unificado para o Excel, PowerPoint, Word, desenvolvimento copilot personalizado e outras extensões do Microsoft 365. Para obter mais informações, consulte Suplementos do Office com o manifesto unificado. Para obter um exemplo de uma aplicação combinada do Teams e suplemento do Outlook, consulte Ofertas de Desconto.

   Adoramos receber o seu feedback sobre o manifesto unificado. Se tiver alguma sugestão, crie um problema no repositório da Biblioteca JavaScript do Office.

   Consoante a sua escolha de manifesto, os pedidos e as respostas devem ter um aspeto semelhante ao seguinte.

   

   

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

   Observação

   Se estiver a utilizar Node.js versão 20.0.0 ou posterior, poderá ver um aviso quando o gerador executar a instalação de que tem um motor não suportado. Estamos a trabalhar numa correção para isto. Entretanto, o aviso não afeta o gerador ou o projeto que gera, pelo que 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 gerador Yeoman cria um projeto numa pasta com o nome do projeto que escolheu. O projeto contém código de exemplo para um suplemento de painel de tarefas muito básico. Seguem-se os ficheiros mais importantes.

• O ficheiro ./manifest.json ou ./manifest.xml no diretório de raiz do projeto define as definições e capacidades 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 ficheiro ./src/taskpane/taskpane.html e substitua todo <o elemento principal> (dentro do <elemento do corpo> ) pela seguinte marcação. 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 ficheiro ./src/taskpane/taskpane.jse, em seguida, adicione o seguinte código à função run . 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;
   

   O seu ficheiro detaskpane.js deve conter agora o seguinte código.

   /*
    * 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 utilizar HTTPS e não HTTP, mesmo quando estiver a desenvolver. Se lhe for pedido para instalar um certificado depois de executar um dos seguintes comandos, aceite o pedido 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 executa este comando, o servidor Web local é iniciado e o suplemento é sideloaded.

   npm start
   

   Observação

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

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

3. Selecione o separador Base (ou o separador Mensagem se abriu a mensagem numa nova janela) e, em seguida, selecione o botão Mostrar Painel de Tarefas no friso para abrir o painel de tarefas do 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 já instalou o Visual Studio 2019 ou posterior, utilize o Instalador do Visual Studio para garantir que a carga de trabalho de desenvolvimento do Office/SharePoint está 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.

Project	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 desenvolve o seu suplemento, o Visual Studio aloja a aplicação Web no servidor local dos Serviços de Informação Internet (IIS). 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. No MessageRead.html, substitua o <elemento do corpo> pela seguinte marcação e guarde o ficheiro.

   <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 marcador de posição. Substitua-o com seu nome.

3. O atributo DefaultValue do <elemento DisplayName> tem um marcador de posição. Substitua-o por My Office Add-in.

4. O atributo DefaultValue do <elemento Description> tem um marcador de posição. 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. Com o Visual Studio, teste o suplemento do Outlook recentemente criado ao premir F5 ou ao selecionar o botão Iniciar . O suplemento será hospedado localmente no IIS.

2. Na caixa de diálogo Ligar à conta de e-mail do Exchange , introduza o endereço de e-mail e a palavra-passe da sua conta Microsoft e, em seguida, selecione Ligar. 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 Ligar à conta de e-mail do Exchange lhe pedir repetidamente para iniciar sessão ou receber um erro de que não está autorizado, a autenticação Básica poderá ser desativada para contas no seu inquilino do Microsoft 365. Para testar este suplemento, tente iniciar sessão novamente depois de definir a propriedade Utilizar autenticação multifator como Verdadeiro na secção Implementação da caixa de diálogo propriedades do projeto do Suplemento Web ou, em alternativa, inicie sessão com uma conta Microsoft .

3. A sua caixa de correio é aberta no Outlook na Web. Selecione ou abra uma mensagem.

   Dica

   Também pode testar o suplemento no Outlook no Windows, desde que o servidor IIS esteja em execução.

4. Na mensagem, navegue para a barra de ação e, em seguida, selecione Aplicações.

   

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

   

6. Veja 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

• Certifique-se de que o seu ambiente está pronto para o desenvolvimento do Office ao seguir as instruções em Configurar o seu ambiente de desenvolvimento.

• O passo automático npm install que o Yo Office executa pode falhar. Se vir erros ao tentar executar npm start, navegue para a pasta do projeto recentemente criada numa linha de comandos e execute npm installmanualmente . Para obter mais informações sobre o Yo Office, consulte Criar projetos de Suplementos do Office com o Yeoman Generator.

• Se o suplemento mostrar um erro (por exemplo, "Não foi possível iniciar este suplemento. Feche esta caixa de diálogo para ignorar o problema ou clique em "Reiniciar" para tentar novamente.") quando prime F5 ou seleciona Depurar>Iniciar Depuração no Visual Studio, consulte Depurar Suplementos do Office no Visual Studio para obter outras opções de depuração.

• Alguns dos códigos de exemplo utilizam JavaScript ES6. Isto não é compatível com versões mais antigas do Office que utilizam o motor de browser Trident (Internet Explorer 11). Para obter informações sobre como suportar essas plataformas no seu suplemento, consulte Suportar webviews mais antigos da Microsoft e versões do Office. Se ainda não tiver uma subscrição do Microsoft 365 para utilizar para desenvolvimento, poderá qualificar-se para uma subscrição de programador do Microsoft 365 E5 através do Programa para Programadores do Microsoft 365; para obter detalhes, veja as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um 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 "Hello world" do Outlook: saiba como criar um suplemento do Office simples com apenas um manifesto, uma página Web HTML e um logótipo.

Confira também

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