Criando Suplementos do OfficeBuilding Office Add-ins

Dica

Examine a Visão geral da plataforma de Suplementos do Office antes de ler este artigo.Please review Office Add-ins platform overview before reading this article.

Os suplementos do Office estendem a interface do usuário a e funcionalidade de aplicativos do Office e interagem com o conteúdo nos documentos do Office.Office Add-ins extend the UI and functionality of Office applications and interact with content in Office documents. Você usará tecnologias da Web conhecidas para criar suplementos do Office que estendem e interagem com o Word, Excel, PowerPoint, OneNote, Project ou Outlook.You'll use familiar web technologies to create Office Add-ins that extend and interact with Word, Excel, PowerPoint, OneNote, Project, or Outlook. Os suplementos que você criou podem ser executados no Office em várias plataformas, incluindo Windows, Mac, iPad e em um navegador.The add-ins you build can run in Office across multiple platforms, including Windows, Mac, iPad, and in a browser. Este artigo fornece uma introdução ao desenvolvimento de Suplementos do Office.This article provides an introduction to developing Office Add-ins.

Criar um Suplemento do OfficeCreating an Office Add-in

Você pode criar um suplemento do Office usando o Gerador Yeoman para suplementos do Office ou Visual Studio.You can create an Office Add-in by using the Yeoman generator for Office Add-ins or Visual Studio.

Gerador Yeoman para suplementos do OfficeYeoman generator for Office Add-ins

O Gerador Yeoman para suplementos do Office pode ser usado para criar um projeto de suplemento do Office Node.js que pode ser gerenciado com o Visual Studio Code ou qualquer outro editor.The Yeoman generator for Office Add-ins can be used to create a Node.js Office Add-in project that can be managed with Visual Studio Code or any other editor. O gerador pode criar suplementos do Office para qualquer um dos seguintes aplicativos:The generator can create Office Add-ins for any of the following:

  • ExcelExcel
  • OneNoteOneNote
  • OutlookOutlook
  • PowerPointPowerPoint
  • ProjectProject
  • WordWord
  • Funções personalizadas do ExcelExcel custom functions

Você pode optar por criar o projeto usando HTML, CSS e JavaScript ou usando o Angular ou React.You can choose to create the project using HTML, CSS and JavaScript, or using Angular or React. Para qualquer estrutura escolhida, você pode escolher entre o JavaScript e o Typescript também.For whichever framework you choose, you can choose between JavaScript and Typescript as well. Para saber mais sobre como criar suplementos com o gerador Yeoman, confira Desenvolver Suplementos do Office com o Código do Visual Studio.For more information about creating add-ins with the Yeoman generator, see Develop Office Add-ins with Visual Studio Code.

Visual StudioVisual Studio

O Visual Studio pode ser usado para criar suplementos do Office para o Excel, Outlook, Word e PowerPoint.Visual Studio can be used to create Office Add-ins for Excel, Word, PowerPoint, or Outlook. Um projeto do suplemento do Office é criado como parte de uma solução do Visual Studio e usa HTML, CSS e JavaScript.An Office Add-in project gets created as part of a Visual Studio solution and uses HTML, CSS, and JavaScript. Para saber mais sobre como criar suplementos usando o Visual Studio, confira Desenvolver suplementos do Office com o Visual Studio.For more information about creating add-ins with Visual Studio, see Develop Office Add-ins with Visual Studio.

Observação

Embora seja possível criar Suplementos do Office usando o Visual Studio, usar o gerador Yeoman oferece, em alguns casos de forma memorável, uma experiência melhor para o desenvolvedor.Although it's possible to create Office Add-ins using Visual Studio, using the Yeoman generator provides a better developer experience in some notable ways.

  • O gerador Yeoman fornece uma maior variedade de opções para tipos de projetos, estruturas e idiomas se comparado com o que o Visual Studio oferece para projetos de Suplemento do Office.The Yeoman generator provides a wider range of options for project types, frameworks, and languages than Visual Studio does for Office Add-in projects.

  • Os modelos de projeto no gerador Yeoman são atualizados com mais frequência do que os modelos de projeto no Visual Studio.Project templates in the Yeoman generator are updated more frequently than project templates in Visual Studio.

Explorar APIs com o Script LabExploring APIs with Script Lab

O Script Lab é um suplemento que permite explorar a API JavaScript para Office e executar trechos de código enquanto você trabalha em um programa do Office, como o Excel ou o Word.Script Lab is an add-in that enables you to explore the Office JavaScript API and run code snippets while you're working in an Office program such as Excel or Word. Ele está disponível gratuitamente através do AppSource e é uma ferramenta útil para incluir no seu kit de ferramentas de desenvolvimento ao prototipar e verificar a funcionalidade desejada no suplemento.It's available for free via AppSource and is a useful tool to include in your development toolkit as you prototype and verify the functionality you want in your add-in. No Script Lab, você pode acessar uma biblioteca de exemplos internos para experimentar APIs rapidamente ou até mesmo usar uma amostra como o ponto de partida para o seu próprio código.In Script Lab, you can access a library of built-in samples to quickly try out APIs or even use a sample as the starting point for your own code.

O vídeo de um minuto a seguir mostra o Script Lab em ação.The following one-minute video shows Script Lab in action.

Visualização de vídeo mostrando o Script Lab em execução no Excel, Word e PowerPoint.Preview video showing Script Lab running in Excel, Word, and PowerPoint.

Para saber mais sobre o Script Lab, confira Explorar as APIs JavaScript para Office usando o Script Lab.For more information about Script Lab, see Explore Office JavaScript APIs using Script Lab.

Estendendo a interface do usuário do OfficeExtending the Office UI

Um suplemento do Office pode estender a interface do usuário do Office usando comandos de suplementos e contêineres HTML como painéis de tarefas, suplementos de conteúdo ou caixas de diálogo.An Office Add-in can extend the Office UI by using add-in commands and HTML containers such as task panes, content add-ins, or dialog boxes.

  • Os comandos de suplemento podem ser usados para adicionar guias, botões e menus personalizados à faixa de opções padrão no office ou para estender o menu de contexto padrão que aparece quando os usuários clicam com o botão direito do mouse em um texto em um documento do Office ou em um objeto no Excel.Add-in commands can be used to add custom tabs, buttons, and menus to the default ribbon in Office, or to extend the default context menu that appears when users right-click text in an Office document or an object in Excel. Quando os usuários selecionam um comando de suplemento, eles iniciam a tarefa que o comando de suplemento especifica, como a execução de código JavaScript, a abertura de um painel de tarefas ou a inicialização de uma caixa de diálogo.When users select an add-in command, they initiate the task that the add-in command specifies, such as running JavaScript code, opening a task pane, or launching a dialog box.

  • Os contêineres HTML como painéis de tarefas, suplementos de conteúdo e caixas de diálogo podem ser usadas para exibir a interface do usuário personalizada e expor uma funcionalidade adicional em um aplicativo do Office.HTML containers like task panes, content add-ins, and dialog boxes can be used to display custom UI and expose additional functionality within an Office application. O conteúdo e a funcionalidade de cada painel de tarefas, suplemento de conteúdo ou caixa de diálogo são derivados de uma página da Web que você especifica.The content and functionality of each task pane, content add-in, or dialog box derives from a web page that you specify. Essas páginas da Web podem usar a API JavaScript para Office para interagir com o conteúdo do documento do Office no qual o suplemento está sendo executado, além disso, também pode fazer outras coisas que as páginas da Web geralmente fazem, como chamar serviços Web externos, facilitar a autenticação do usuário e mais.Those web pages can use the Office JavaScript API to interact with content in the Office document where the add-in is running, and can also do other things that web pages typically do, like call external web services, facilitate user authentication, and more.

A imagem a seguir mostra um comando de suplemento na faixa de opções, um painel de tarefas à direita do documento e uma caixa de diálogo ou suplemento de conteúdo sobre o documento.The following image shows an add-in command in the ribbon, a task pane to the right of the document, and a dialog box or content add-in over the document.

Uma imagem que mostra comandos de suplemento na faixa de opções, um painel de tarefas e uma caixa de diálogo em um documento do Office

Para saber mais sobre como estender a interface do usuário do Office, confira Elementos da interface do usuário do Office para suplementos do Office.For more information about extending the Office UI, see Office UI elements for Office Add-ins.

Principais conceitos de desenvolvimentoCore development concepts

Um suplemento do Office consiste em duas partes:An Office Add-in consists of two parts:

  • O manifesto do suplemento (um arquivo XML) que defina as configurações e recursos do suplemento.The add-in manifest (an XML file) that defines the settings and capabilities of the add-in.

  • O aplicativo Web que defina a interface do usuário e a funcionalidade de componentes do suplemento, como painéis de tarefas, suplementos de conteúdo e caixas de diálogo.The web application that defines the UI and functionality of add-in components such as task panes, content add-ins, and dialog boxes.

O aplicativo Web usa a API JavaScript para Office para interagir com o conteúdo do documento do Office no qual o suplemento está sendo executado.The web application uses the Office JavaScript API to interact with content in the Office document where the add-in is running. Seu suplemento também pode fazer outras coisas que os aplicativos Web normalmente fazem, como chamar serviços Web externos, facilitar a autenticação do usuário e mais.Your add-in can also do other things that web applications typically do, like call external web services, facilitate user authentication, and more.

Definir as configurações e os recursos do suplementoDefining an add-in's settings and capabilities

Um manifesto do suplemento do Office (um arquivo XML) define as configurações e os recursos do suplemento.An Office Add-in's manifest (an XML file) defines the settings and capabilities of the add-in. Você vai configurar o manifesto para especificar itens como:You'll configure the manifest to specify things such as:

  • Metadados que descrevem o suplemento (por exemplo, ID, versão, descrição, nome de exibição, local padrão).Metadata that describes the add-in (for example, ID, version, description, display name, default locale).
  • Aplicativos do Office onde o suplemento será executado.Office applications where the add-in will run.
  • Permissões necessárias para o suplemento.Permissions that the add-in requires.
  • Como o suplemento se integra ao Office, incluindo qualquer interface do usuário personalizada que o suplemento cria (por exemplo, guias personalizadas, botões da faixa de opções).How the add-in integrates with Office, including any custom UI that the add-in creates (for example, custom tabs, ribbon buttons).
  • Localização de imagens que o suplemento usa para identidade visual e iconografia de comando.Location of images that the add-in uses for branding and command iconography.
  • Dimensões do suplemento (por exemplo, dimensões para suplementos de conteúdo, altura solicitada para suplementos do Outlook).Dimensions of the add-in (for example, dimensions for content add-ins, requested height for Outlook add-ins).
  • As regras que especificam quando o suplemento é ativado no contexto de uma mensagem ou de um compromisso (somente para suplementos do Outlook).Rules that specify when the add-in activates in the context of a message or appointment (for Outlook add-ins only).

Para saber mais sobre o manifesto, confira Manifesto XML de suplementos do Office.For detailed information about the manifest, see Office Add-ins XML manifest.

Interagir com o conteúdo em um documento do OfficeInteracting with content in an Office document

Um suplemento do Office pode usar as APIs JavaScript para Office para interagir com o conteúdo no documento do Office no qual o documento está sendo executado.An Office Add-in can use the Office JavaScript APIs to interact with content in the Office document where the add-in is running.

Acessar a biblioteca JavaScript do OfficeAccessing the Office JavaScript library

A biblioteca JavaScript do Office pode ser acessada pela CDN (rede de distribuição de conteúdo do Office JS) em: https://appsforoffice.microsoft.com/lib/1/hosted/Office.js.The Office JavaScript library can be accessed via the Office JS content delivery network (CDN) at: https://appsforoffice.microsoft.com/lib/1/hosted/Office.js. Para usar as APIs JavaScript para Office em qualquer uma das páginas da Web do seu suplemento, você deve fazer referência à CDN em uma tag <script> na tag <head> da página.To use Office JavaScript APIs within any of your add-in's web pages, you must reference the CDN in a <script> tag in the <head> tag of the page.

<head>
    ...
    <script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>
</head>

Observação

Para usar as APIs de visualização, referencie a versão de visualização da biblioteca JavaScript para Office na CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js.To use preview APIs, reference the preview version of the Office JavaScript library on the CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js.

Para saber mais sobre como acessar a biblioteca JavaScript para Office, incluindo como obter o IntelliSense, confira Fazer referência à biblioteca da API JavaScript para Office de sua CDN (rede de distribuição de conteúdo).For more information about accessing the Office JavaScript library, including how to get IntelliSense, see Referencing the JavaScript API for Office library from its content delivery network (CDN).

Modelos de APIAPI models

As API do JavaScript para Office incluem dois modelos diferentes:The Office JavaScript APIs include two distinct models:

  • As APIs Específicas do host fornecem objetos fortemente tipados que podem ser usados para interagir com objetos que são nativos de um aplicativos do Office específico.Host-specific APIs provide strongly-typed objects that can be used to interact with objects that are native to a specific Office application. Por exemplo, você pode usar as APIs JavaScript do Excel para acessar planilhas, intervalos, tabelas, gráficos e mais.For example, you can use the Excel JavaScript APIs to access worksheets, ranges, tables, charts, and more. As APIs específicas do host estão disponíveis atualmente para o Excel, Word e OneNote.Host-specific APIs are currently available for Excel, Word, and OneNote. Esse modelo de API usa promessas e permite que você especifique várias operações em cada solicitação enviada ao host do Office.This API model uses promises and allows you to specify multiple operations in each request you send to the Office host. Operações de envio em lote dessa maneira podem melhorar significativamente o desempenho do suplemento no Office nos aplicativos Web.Batching operations in this manner can significantly improve add-in performance in Office on the web applications. As APIs específicas do host foram introduzidas com o Office 2016 e não pode ser usadas para interagir com o Office 2013.Host-specific APIs were introduced with Office 2016 and cannot be used to interact with Office 2013.

  • As APIs Comuns podem ser usadas para acessar recursos como interface do usuário, caixas de diálogo e configurações de cliente, que são comuns entre vários tipos de aplicativos do Office.Common APIs can be used to access features such as UI, dialogs, and client settings that are common across multiple types of Office applications. Esse modelo de API usa retornos de chamada, em que você pode especificar apenas uma operação em cada solicitação enviada ao host do Office.This API model uses callbacks, where you can only specify one operation in each request you send to the Office host. As APIs comuns foram introduzidas com o Office 2013 e podem ser usadas para interagir com o Office 2013 ou posterior.Common APIs were introduced with Office 2013 and can be used to interact with Office 2013 or later. Para saber mais sobre o modelo de objeto da API comum, que inclui APIs para interagir com o Outlook e o PowerPoint, confira Modelo de objeto de API JavaScript para Office.For details about the Common API object model, which includes APIs for interacting with Outlook and PowerPoint, see Office JavaScript API object model.

Observação

As funções personalizadas do Excel são executadas dentro de um tempo de execução único que prioriza a execução de cálculos e, portanto, usa um modelo de programação ligeiramente diferente.Excel Custom functions run within a unique runtime that prioritizes execution of calculations, and therefore uses a slightly different programming model. Para saber mais, confira Arquitetura de funções personalizadas.For details, see Custom functions architecture.

Para obter mais informações sobre as APIs JavaScript para Office, confira Noções básicas da API JavaScript para Office.For additional information about the Office JavaScript APIs, see Understanding the JavaScript API for Office.

Conjuntos de requisitos da APIAPI requirement sets

Os conjuntos de requisitos são grupos nomeados de membros da API.Requirement sets are named groups of API members. Os conjuntos de requisitos podem ser específicos para os hosts do Office, como o conjunto de requisitos ExcelApi 1.7 (um conjunto de APIs que só podem ser usadas no Excel) ou comuns a vários hosts, como o conjunto de requisitos DialogApi 1.1 (um conjunto de APIs que podem ser usadas em qualquer aplicativo do Office que forneça suporte à API de Caixa de Diálogo).Requirement sets can be specific to Office hosts, such as the ExcelApi 1.7 requirement set (a set of APIs that can only be used in Excel), or common to multiple hosts, such as the DialogApi 1.1 requirement set (a set of APIs that can be used in any Office application that supports the Dialog API).

Seu suplemento pode usar conjuntos de requisitos para determinar se o host do Office oferece suporte aos membros da API necessários.Your add-in can use requirement sets to determine whether the Office host supports the API members that it needs to use. Para saber mais sobre isso, confira Especificar requisitos de API e host do Office.For more information about this, see Specify Office hosts and API requirements.

O suporte a um conjunto de requisitos varia de acordo com o host do Office, a versão e a plataforma.Requirement set support varies by Office host, version, and platform. Para obter informações detalhadas sobre as plataformas, os conjuntos de requisitos e as APIs comuns compatíveis com cada aplicativo do Office, confira Disponibilidade de host e plataforma para suplementos do Office.For detailed information about the platforms, requirement sets, and Common APIs that each Office application supports, see Office Add-in host and platform availability.

Teste e depuração de um suplemento do OfficeTesting and debugging an Office Add-in

Ao desenvolver seu suplemento, você pode testá-lo localmente usando uma técnica conhecida como sideload.As you develop your add-in, you can test it locally by using a technique known as sideloading. O procedimento para realizar o sideload de um suplemento varia de acordo com a plataforma e, em alguns casos, também com o produto.The procedure for sideloading an add-in varies by platform, and in some cases, by product as well. Da mesma forma, o procedimento de depuração de um suplemento também pode variar de acordo com a plataforma e o produto.Likewise, the procedure for debugging an add-in can also vary by platform and product. Para saber mais sobre teste e depuração, confira Testar e depurar suplementos do Office.For more information about testing and debugging, see Test and debug Office Add-ins.

Publicar um suplemento do OfficePublishing an Office Add-in

Quando estiver pronto para compartilhar seu suplemento com outras pessoas, você poderá fazer isso usando o método de implantação mais adequado aos seus objetivos.When you're ready to share your add-in with others, you'll do so by using the deployment method that best meets your objectives. Por exemplo, para implantar um suplemento para os usuários dentro da organização, você pode usar a implantação centralizada ou publicar o suplemento em um catálogo de aplicativos do SharePoint.For example, to deploy an add-in to users within your organization, you might use centralized deployment or publish the add-in to a SharePoint app catalog. Se você quiser compartilhar seu suplemento publicamente para que qualquer pessoa possa acessá-lo, publique-o no AppSource.If you want to share your add-in publicly for anyone to obtain, you can publish the add-in to AppSource. Para saber mais sobre publicação, confira Implantar e publicar suplementos do Office.For more information about publishing, see Deploy and publish Office Add-ins.

Próximas etapasNext steps

Este artigo descreveu as diferentes maneiras de criar suplementos do Office, apresentou o Script Lab como uma ferramenta valiosa para explorar as APIs JavaScript para Office e a criação de protótipo de funcionalidade de suplemento e descreveu o desenvolvimento, teste e conceitos de publicação importantes dos suplementos do Office.This article has outlined the different ways to create Office Add-ins, introduced Script Lab as a valuable tool for exploring Office JavaScript APIs and prototyping add-in functionality, and described important Office Add-ins development, testing, and publishing concepts. Agora que você já explorou estas informações introdutórias, considere continuar sua jornada de suplementos do Office ao longo dos caminhos a seguir.Now that you've explored this introductory information, consider continuing your Office Add-ins journey along the following paths.

Criar um suplemento do OfficeCreate an Office add-in

Você pode criar rapidamente um suplemento básico para o Excel, o OneNote, o Outlook, o PowerPoint, o Project ou o Word realizando um início rápido de 5 minutos.You can quickly create a basic add-in for Excel, OneNote, Outlook, PowerPoint, Project, or Word by completing a 5-minute quick start. Se você já concluiu um início rápido e deseja criar um suplemento um pouco mais complexo, experiente o tutorial.If you've previously completed a quick start and want to create a slightly more complex add-in, you should try the tutorial.

Explorar as APIs com o Script LabExplore the APIs with Script Lab

Explore a biblioteca de amostras internas no Script Lab para ter uma ideia dos recursos das APIs JavaScript para Office.Explore the library of built-in samples in Script Lab to get a sense for the capabilities of the Office JavaScript APIs.

Saiba maisLearn more

Saiba mais sobre o desenvolvimento, testes e publicação de suplementos do Office explorando essa documentação.Learn more about developing, testing, and publishing Office Add-ins by exploring this documentation.

Dica

Para qualquer suplemento que você criar, use as informações na seção Principais conceitos desta documentação, juntamente com as informações na seção específica do host que correspondem ao tipo de suplemento que você está criando (por exemplo, Excel).For any add-in that you build, you'll use information in the Core concepts section of this documentation, along with information in the host-specific section that corresponds to the type of add-in you're building (for example, Excel).

Uma imagem que mostra o sumário

Confira tambémSee also