Tutorial: Criar um suplemento do PowerPoint com o Visual Studio

Se você quiser aprender os Suplementos do Office criando algo prático, este tutorial o orientará na criação de um suplemento do painel de tarefas do PowerPoint no Visual Studio.

Em cerca de 20 minutos, você criará um suplemento que pode:

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, 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).

  Observação

  Se você ainda não tem o Office, pode se qualificar para uma assinatura de desenvolvedor do Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365. Para obter detalhes, consulte as Perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou adquirir um plano do Microsoft 365.

Criar seu projeto do suplemento

Conclua as etapas a seguir para criar um projeto de suplemento do PowerPoint usando o Visual Studio.

1. Escolha Criar um novo projeto.

2. Usando a caixa de pesquisa, insira suplemento. Escolha Suplemento do PowerPoint Web , em seguida, selecione Próximo.

3. Nomeie o projeto como HelloWorld e selecione Criar.

4. Na caixa de diálogo Criar suplementos do Office, escolha Adicionar novas funcionalidades ao PowerPointe depois Concluir para criar o projeto.

5. O Visual Studio cria uma solução, e os dois projetos dele são exibidos no Gerenciador de Soluções. O arquivo Home.html é aberto no Visual Studio.

   

6. Os seguintes pacotes NuGet devem ser instalados. Instale-os no projeto HelloWorldWeb usando o Gerenciador de Pacotes NuGet no Visual Studio. Consulte a ajuda do Visual Studio para obter instruções. O segundo deles pode ser instalado automaticamente quando você instala o primeiro.

   • Microsoft.AspNet.WebApi.WebHost
   • Microsoft.AspNet.WebApi.Core

   Importante

   Quando você estiver usando o Gerenciador de Pacotes NuGet para instalar esses pacotes, não instale a atualização recomendada para o jQuery. A versão do jQuery instalada com sua solução do Visual Studio corresponde à chamada do jQuery nos arquivos da solução.

7. Use o Gerenciador de Pacotes NuGet para atualizar o pacote Newtonsoft.Json para a versão 13.0.3 ou posterior. Em seguida, exclua o arquivo app.config se ele foi adicionado ao projeto HelloWorld .

Explorar a solução do Visual Studio

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

Adicionar marcação inicial e script

Edite o código do suplemento como mostrado a seguir para criar a estrutura que você usará para implementar a funcionalidade do suplemento nas etapas subsequentes deste tutorial.

1. Home.html especifica o HTML que será renderizado no painel de tarefas do suplemento. Em Home.html, encontre a div com id="content-main", substitua toda essa div pela marcação a seguir e salve o arquivo.

   <!-- TODO2: Create the content-header div. -->
   <div id="content-main">
       <div class="padding">
           <!-- TODO1: Create the insert-image button. -->
           <!-- TODO3: Create the insert-text button. -->
           <!-- TODO4: Create the get-slide-metadata button. -->
           <!-- TODO5: Create the add-slides and go-to-slide buttons. -->
       </div>
   </div>
   

2. Abra o arquivo Home.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.

   (function () {
       "use strict";
   
       let messageBanner;
   
       Office.onReady(function () {
           $(document).ready(function () {
               // Initialize the FabricUI notification mechanism and hide it.
               const element = document.querySelector('.MessageBanner');
               messageBanner = new components.MessageBanner(element);
               messageBanner.hideBanner();
   
               // TODO1: Assign event handler for insert-image button.
               // TODO4: Assign event handler for insert-text button.
               // TODO6: Assign event handler for get-slide-metadata button.
               // TODO8: Assign event handlers for add-slides and the four navigation buttons.
           });
       });
   
       // TODO2: Define the insertImage function.
   
       // TODO3: Define the insertImageFromBase64String function.
   
       // TODO5: Define the insertText function.
   
       // TODO7: Define the getSlideMetadata function.
   
       // TODO9: Define the addSlides and navigation functions.
   
       // Helper function for displaying notifications.
       function showNotification(header, content) {
           $("#notification-header").text(header);
           $("#notification-body").text(content);
           messageBanner.showBanner();
           messageBanner.toggleExpansion();
       }
   })();
   

Inserir uma imagem

Conclua as seguintes etapas para adicionar o código que recupera a foto do dia do Bing e inserir as imagens em um slide.

1. Usando o Explorador de soluções, adicione uma nova pasta chamada Controladores ao projeto HelloWorldWeb.

   

2. Clique com o botão direito do mouse (ou selecione e segure) a pasta Controladores e selecione Adicionar>Novo Item de Scaffolded....

3. Na janela da caixa de diálogo Adicionar Scaffold, selecione Controlador da Web API 2 – vazio e escolha o botão Adicionar.

4. Na janela da caixa de diálogo Adicionar Controlador, insira PhotoController como nome do controlador e escolha o botão Adicionar. O Visual Studio criará e abrirá o arquivo PhotoController.cs.

   Importante

   O processo de scaffolding não é concluído corretamente em algumas versões do Visual Studio após a versão 16.10.3. Se você tiver os arquivos Global.asax e ./App_Start/WebApiConfig.cs , pule para a etapa 6.

   

5. Se não houver arquivos de scaffolding do projeto HelloWorldWeb , adicione-os da seguinte maneira.

   1. Usando Gerenciador de Soluções, adicione uma nova pasta chamada App_Start ao projeto HelloWorldWeb.

   2. Clique com o botão direito do mouse (ou selecione e segure) a pasta App_Start e selecione Adicionar>Classe....

   3. Na caixa de diálogo Adicionar Novo Item , nomeie o arquivo WebApiConfig.cs escolha o botão Adicionar .

   4. Substitua todo o conteúdo do arquivo WebApiConfig.cs pelo código a seguir.

      using System;
      using System.Collections.Generic;
      using System.Linq;
      using System.Web;
      using System.Web.Http;
      
      namespace HelloWorldWeb.App_Start
      {
          public static class WebApiConfig
          {
              public static void Register(HttpConfiguration config)
              {
                  config.MapHttpAttributeRoutes();
      
                  config.Routes.MapHttpRoute(
                      name: "DefaultApi",
                      routeTemplate: "api/{controller}/{id}",
                      defaults: new { id = RouteParameter.Optional }
                  );
              }
          }
      }
      

   5. No Gerenciador de Soluções, clique com o botão direito do mouse (ou selecione e segure) no projeto HelloWorldWeb e selecione Adicionar>Novo Item....

   6. Na caixa de diálogo Adicionar Novo Item , pesquise por "global", selecione Classe de Aplicação Global e, em seguida, escolha o botão Adicionar . Por padrão, o arquivo é denominado Global.asax.

   7. Substitua todo o conteúdo do arquivo Global.asax.cs pelo código a seguir.

      using HelloWorldWeb.App_Start;
      using System;
      using System.Collections.Generic;
      using System.Linq;
      using System.Web;
      using System.Web.Http;
      using System.Web.Security;
      using System.Web.SessionState;
      
      namespace HelloWorldWeb
      {
          public class WebApiApplication : System.Web.HttpApplication
          {
              protected void Application_Start()
              {
                  GlobalConfiguration.Configure(WebApiConfig.Register);
              }
          }
      }
      

   8. No Gerenciador de Soluções, clique com o botão direito do mouse (ou selecione e segure) no arquivo Global.asax e escolha Exibir Marcação.

   9. Substitua todo o conteúdo do arquivo Global.asax pelo código a seguir.

      <%@ Application Codebehind="Global.asax.cs" Inherits="HelloWorldWeb.WebApiApplication" Language="C#" %>
      

6. Substitua todo o conteúdo do arquivo PhotoController.cs pelo código a seguir que chama o serviço Bing para recuperar a foto do dia como uma cadeia de caracteres codificada em Base64. Quando você usa a API JavaScript do Office para inserir uma imagem em um documento, os dados da imagem devem ser especificados como uma cadeia de caracteres codificada em Base64.

   using System;
   using System.IO;
   using System.Net;
   using System.Text;
   using System.Web.Http;
   using System.Xml;
   
   namespace HelloWorldWeb.Controllers
   {
       public class PhotoController : ApiController
       {
           public string Get()
           {
               string url = "http://www.bing.com/HPImageArchive.aspx?format=xml&idx=0&n=1";
   
               // Create the request.
               HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
               WebResponse response = request.GetResponse();
   
               using (Stream responseStream = response.GetResponseStream())
               {
                   // Process the result.
                   StreamReader reader = new StreamReader(responseStream, Encoding.UTF8);
                   string result = reader.ReadToEnd();
   
                   // Parse the XML response and get the URL.
                   XmlDocument doc = new XmlDocument();
                   doc.LoadXml(result);
                   string photoURL = "http://bing.com" + doc.SelectSingleNode("/images/image/url").InnerText;
   
                   // Fetch the photo and return it as a Base64-encoded string.
                   return getPhotoFromURL(photoURL);
               }
           }
   
           private string getPhotoFromURL(string imageURL)
           {
               var webClient = new WebClient();
               byte[] imageBytes = webClient.DownloadData(imageURL);
               return Convert.ToBase64String(imageBytes);
           }
       }
   }
   

7. No arquivo Home.html, substitua TODO1 pela marcação a seguir. Essa marcação define o botão Inserir Imagem que aparecerá no painel de tarefas do suplemento.

   <button class="Button Button--primary" id="insert-image">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Insert Image</span>
       <span class="Button-description">Gets the photo of the day that shows on the Bing home page and adds it to the slide.</span>
   </button>
   

8. No arquivo Home.js, substitua TODO1 pelo código a seguir para atribuir o manipulador de eventos ao botão Inserir Imagem.

   $('#insert-image').on("click", insertImage);
   

9. No arquivo Home.js, substitua TODO2 pelo código a seguir para definir a função insertImage. Esta função busca a imagem do serviço Web Bing e chama a função insertImageFromBase64String para inserir a imagem no documento.

   function insertImage() {
       // Get image from web service (as a Base64-encoded string).
       $.ajax({
           url: "/api/photo/",
           dataType: "text",
           success: function (result) {
               insertImageFromBase64String(result);
           }, error: function (xhr, status, error) {
               showNotification("Error", "Oops, something went wrong.");
           }
       });
   }
   

10. No arquivo Home.js, substitua TODO3 pelo código a seguir para definir a função insertImageFromBase64String. Esta função usa a API JavaScript do Office para inserir a imagem no documento. Observação:

    • A opção coercionType especificada como segundo parâmetro da solicitação setSelectedDataAsync indica o tipo de dados inserido.

    • O objeto asyncResult encapsula o resultado da solicitação setSelectedDataAsync, incluindo informações de status e de erro caso a solicitação tenha falhado.

    function insertImageFromBase64String(image) {
        // Call Office.js to insert the image into the document.
        Office.context.document.setSelectedDataAsync(image, {
            coercionType: Office.CoercionType.Image
        },
            function (asyncResult) {
                if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                    showNotification("Error", asyncResult.error.message);
                }
            });
    }
    

Testar o suplemento

1. Usando o Visual Studio, teste o suplemento do PowerPoint recém-criado pressionando F5 ou escolhendo o botão Iniciar para iniciar o PowerPoint com o botão do suplemento Mostrar Painel de Tarefas exibido na faixa de opções. O suplemento será hospedado localmente no IIS.

   

2. Se o painel de tarefas do suplemento ainda não estiver aberto no PowerPoint, selecione o botão Mostrar Painel de Tarefas na faixa de opções para abri-lo.

   

3. No painel de tarefas, escolha o botão Inserir Imagem para adicionar a foto do dia do Bing ao slide atual.

   

   Observação

   Se você receber um erro "Não foi possível encontrar o arquivo [...]\bin\roslyn\csc.exe", faça o seguinte:

   1. Abra o arquivo .\Web.config .
   2. Localize o <compiler> nó do .cs extensione remova o type atributo e seu valor.
   3. Salve o arquivo.

4. No Visual Studio, pare o suplemento pressionando Shift+F5 ou escolhendo o botão Parar . O PowerPoint fechará automaticamente quando o suplemento for interrompido.

   

Personalizar elementos da interface do usuário

Conclua as seguintes etapas para adicionar a marca que personaliza o painel de tarefas da interface do usuário.

1. No arquivo Home.html, substitua TODO2 pela marcação a seguir para adicionar uma seção de cabeçalho e um título ao painel de tarefas. Observação:

   • Os estilos que começam com ms- são definidos pelo Fabric Core em Suplementos do Office , uma estrutura de front-end JavaScript para construir experiências do usuário para o Office. O arquivo Home.html inclui uma referência à folha de estilo do Fabric Core.

   <div id="content-header">
       <div class="ms-Grid ms-bgColor-neutralPrimary">
           <div class="ms-Grid-row">
               <div class="padding ms-Grid-col ms-u-sm12 ms-u-md12 ms-u-lg12"> <div class="ms-font-xl ms-fontColor-white ms-fontWeight-semibold">My PowerPoint add-in</div></div>
           </div>
       </div>
   </div>
   

2. No arquivo Home.html, localize a div com class="footer" e exclua toda a div para remover a seção de rodapé do painel de tarefas.

Testar o suplemento

1. Usando o Visual Studio, teste o suplemento do PowerPoint pressionando F5 ou escolhendo o botão Iniciar para iniciar o PowerPoint com o botão do suplemento Mostrar Painel de Tarefas exibido na faixa de opções. O suplemento será hospedado localmente no IIS.

   

2. Se o painel de tarefas do suplemento ainda não estiver aberto no PowerPoint, selecione o botão Mostrar Painel de Tarefas na faixa de opções para abri-lo.

   

3. Observe que agora o painel de tarefas contém uma seção de cabeçalho e um título e não contém mais uma seção de rodapé.

   

4. No Visual Studio, pare o suplemento pressionando Shift+F5 ou escolhendo o botão Parar . O PowerPoint fechará automaticamente quando o suplemento for interrompido.

   

Inserir texto

Conclua as seguintes etapas para adicionar o código que insere texto no slide de título que contém as fotos do dia do Bing.

1. No arquivo Home.html, substitua TODO3 pela marcação a seguir. Essa marcação define o botão Inserir Texto que aparecerá no painel de tarefas do suplemento.

       <br /><br />
       <button class="Button Button--primary" id="insert-text">
           <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
           <span class="Button-label">Insert Text</span>
           <span class="Button-description">Inserts text into the slide.</span>
       </button>
   

2. No arquivo Home.js, substitua TODO4 pelo código a seguir para atribuir o manipulador de eventos ao botão Inserir Texto.

   $('#insert-text').on("click", insertText);
   

3. No arquivo Home.js, substitua TODO5 pelo código a seguir para definir a função insertText. Esta função insere texto no slide atual.

   function insertText() {
       Office.context.document.setSelectedDataAsync('Hello World!',
           function (asyncResult) {
               if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   

Testar o suplemento

1. Usando o Visual Studio, teste o suplemento pressionando F5 ou escolhendo o botão Iniciar para iniciar o PowerPoint com o botão do suplemento Mostrar Painel de Tarefas exibido na faixa de opções. O suplemento será hospedado localmente no IIS.

   

2. Se o painel de tarefas do suplemento ainda não estiver aberto no PowerPoint, selecione o botão Mostrar Painel de Tarefas na faixa de opções para abri-lo.

   

3. No painel de tarefas, escolha o botão Inserir Imagem para adicionar a foto do dia do Bing ao slide atual e escolher um design para o slide que contém uma caixa de texto como título.

   

4. Coloque o cursor na caixa de texto no slide de título e depois, no painel de tarefas, escolha o botão Inserir Texto para adicionar texto ao slide.

   

5. No Visual Studio, pare o suplemento pressionando Shift+F5 ou escolhendo o botão Parar . O PowerPoint fechará automaticamente quando o suplemento for interrompido.

   

Obter metadados do slide

Conclua as seguintes etapas para adicionar o código que recupera os metadados para o slide selecionado.

1. No arquivo Home.html, substitua TODO4 pela marcação a seguir. Essa marcação define o botão Obter metadados do slide que aparecerá no painel de tarefas do suplemento.

   <br /><br />
   <button class="Button Button--primary" id="get-slide-metadata">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Get Slide Metadata</span>
       <span class="Button-description">Gets metadata for the selected slides.</span>
   </button>
   

2. No arquivo Home.js, substitua TODO6 pelo código a seguir para atribuir o manipulador de eventos para o botão Obter Metadados do Slide.

   $('#get-slide-metadata').on("click", getSlideMetadata);
   

3. No arquivo Home.js, substitua TODO7 pelo código a seguir para definir a função getSlideMetadata. Esta função recupera metadados para os slides selecionados e os grava em uma janela de diálogo pop-up dentro do painel de tarefas do suplemento.

   function getSlideMetadata() {
       Office.context.document.getSelectedDataAsync(Office.CoercionType.SlideRange,
           function (asyncResult) {
               if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                   showNotification("Error", asyncResult.error.message);
               } else {
                   showNotification("Metadata for selected slides:", JSON.stringify(asyncResult.value), null, 2);
               }
           }
       );
   }
   

Testar o suplemento

1. Usando o Visual Studio, teste o suplemento pressionando F5 ou escolhendo o botão Iniciar para iniciar o PowerPoint com o botão do suplemento Mostrar Painel de Tarefas exibido na faixa de opções. O suplemento será hospedado localmente no IIS.

   

2. Se o painel de tarefas do suplemento ainda não estiver aberto no PowerPoint, selecione o botão Mostrar Painel de Tarefas na faixa de opções para abri-lo.

   

3. No painel de tarefas, escolha o botão Obter metadados do slide para obter os metadados do slide selecionado. Os metadados do slide serão gravados na janela pop-up da caixa de diálogo na parte inferior do painel de tarefas. Nesse caso, a matriz slides dos metadados JSON contém um objeto que especifica id, title e index do slide selecionado. Se vários slides tivessem sido selecionados na recuperação de metadados do slide, a matriz slides dos metadados JSON conteria um objeto para cada slide selecionado.

   

4. No Visual Studio, pare o suplemento pressionando Shift+F5 ou escolhendo o botão Parar . O PowerPoint fechará automaticamente quando o suplemento for interrompido.

   

Navegar entre slides

Conclua as seguintes etapas para adicionar o código que navega entre os slides de um documento.

1. No arquivo Home.html, substitua TODO5 pela marcação a seguir. Essa marcação define os quatro botões de navegação que aparecerão no painel de tarefas do suplemento.

   <br /><br />
   <button class="Button Button--primary" id="add-slides">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Add Slides</span>
       <span class="Button-description">Adds 2 slides.</span>
   </button>
   <br /><br />
   <button class="Button Button--primary" id="go-to-first-slide">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Go to First Slide</span>
       <span class="Button-description">Go to the first slide.</span>
   </button>
   <br /><br />
   <button class="Button Button--primary" id="go-to-next-slide">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Go to Next Slide</span>
       <span class="Button-description">Go to the next slide.</span>
   </button>
   <br /><br />
   <button class="Button Button--primary" id="go-to-previous-slide">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Go to Previous Slide</span>
       <span class="Button-description">Go to the previous slide.</span>
   </button>
   <br /><br />
   <button class="Button Button--primary" id="go-to-last-slide">
       <span class="Button-icon"><i class="ms-Icon ms-Icon--plus"></i></span>
       <span class="Button-label">Go to Last Slide</span>
       <span class="Button-description">Go to the last slide.</span>
   </button>
   

2. No arquivoHome.js , substitua TODO8 pelo código a seguir para atribuir os manipuladores de eventos para Adicionar Slides e quatro botões de navegação.

   $('#add-slides').on("click", addSlides);
   $('#go-to-first-slide').on("click", goToFirstSlide);
   $('#go-to-next-slide').on("click", goToNextSlide);
   $('#go-to-previous-slide').on("click", goToPreviousSlide);
   $('#go-to-last-slide').on("click", goToLastSlide);
   

3. No arquivoHome.js , substitua TODO9 pelo código a seguir para definir as addSlides funções de navegação e . Cada uma dessas funções usa o método goToByIdAsync para selecionar um slide com base em sua posição no documento (primeiro, último, anterior e próximo).

   async function addSlides() {
       await PowerPoint.run(async function (context) {
           context.presentation.slides.add();
           context.presentation.slides.add();
   
           await context.sync();
   
           showNotification("Success", "Slides added.");
           goToLastSlide();
       });
   }
   
   function goToFirstSlide() {
       Office.context.document.goToByIdAsync(Office.Index.First, Office.GoToType.Index,
           function (asyncResult) {
               if (asyncResult.status == "failed") {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   
   function goToLastSlide() {
       Office.context.document.goToByIdAsync(Office.Index.Last, Office.GoToType.Index,
           function (asyncResult) {
               if (asyncResult.status == "failed") {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   
   function goToPreviousSlide() {
       Office.context.document.goToByIdAsync(Office.Index.Previous, Office.GoToType.Index,
           function (asyncResult) {
               if (asyncResult.status == "failed") {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   
   function goToNextSlide() {
       Office.context.document.goToByIdAsync(Office.Index.Next, Office.GoToType.Index,
           function (asyncResult) {
               if (asyncResult.status == "failed") {
                   showNotification("Error", asyncResult.error.message);
               }
           });
   }
   

Testar o suplemento

1. Usando o Visual Studio, teste o suplemento pressionando F5 ou escolhendo o botão Iniciar para iniciar o PowerPoint com o botão do suplemento Mostrar Painel de Tarefas exibido na faixa de opções. O suplemento será hospedado localmente no IIS.

   

2. Se o painel de tarefas do suplemento ainda não estiver aberto no PowerPoint, selecione o botão Mostrar Painel de Tarefas na faixa de opções para abri-lo.

   

3. No painel de tarefas, escolha o botão Adicionar Slides . Dois novos slides são adicionados ao documento e o último slide do documento é selecionado e exibido.

   

4. No painel de tarefas, escolha o botão Ir para o primeiro Slide. O primeiro slide no documento é selecionado e exibido.

   

5. No painel de tarefas, escolha o botão Ir para o próximo Slide. O próximo slide no documento é selecionado e exibido.

   

6. No painel de tarefas, escolha o botão Ir Para o Slide Anterior. O slide anterior no documento é selecionado e exibido.

   

7. No painel de tarefas, escolha o botão Ir Para o Último Slide. O último slide no documento é selecionado e exibido.

   

8. No Visual Studio, pare o suplemento pressionando Shift+F5 ou escolhendo o botão Parar . O PowerPoint fechará automaticamente quando o suplemento for interrompido.

   

Exemplos de código

• Tutorial de suplemento do PowerPoint concluído: o resultado da conclusão deste tutorial.

Próximas etapas

Agora você tem um suplemento do PowerPoint funcional que insere imagens e texto, lê metadados de slides e navega em slides. Continue com estes artigos para aprofundar suas habilidades de desenvolvimento de suplementos do PowerPoint.

Confira também

• Visão geral da plataforma Suplementos do Office
• Desenvolver Suplementos do Office