Visão geral dos suplementos do WordWord add-ins overview

Você deseja criar uma solução que estenda a funcionalidade do Word? Por exemplo, uma solução que envolva conjuntos de documentos automatizados? Ou uma solução que vincule essas associações aos dados e os acesse em um documento do Word a partir de outras fontes de dados? É possível usar a plataforma de suplementos do Office, que inclui a API JavaScript do Word e a API JavaScript para Office, para estender os clientes do Word que executam em uma área de trabalho do Windows, em um Mac ou na nuvem.Do you want to create a solution that extends the functionality of Word? For example, one that involves automated document assembly? Or a solution that binds to and accesses data in a Word document from other data sources? You can use the Office Add-ins platform, which includes the Word JavaScript API and the JavaScript API for Office, to extend Word clients running on a Windows desktop, on a Mac, or in the cloud.

Os suplementos do Word são uma das várias opções de desenvolvimento disponíveis na plataforma de suplementos do Office. Você pode usar comandos de suplemento para estender a interface do usuário do Word e iniciar os painéis de tarefas que executam JavaScript que interage com o conteúdo em um documento do Word. Qualquer código que você pode executar em um navegador, pode ser executado em um suplemento do Word. Suplementos que interagem com conteúdo em um documento do Word criam solicitações para agir em objetos do Word e sincronizar o estado do objeto.Word add-ins are one of the many development options that you have on the Office Add-ins platform. You can use add-in commands to extend the Word UI and launch task panes that run JavaScript that interacts with the content in a Word document. Any code that you can run in a browser can run in a Word add-in. Add-ins that interact with content in a Word document create requests to act on Word objects and synchronize object state.

Observação

Caso pretenda publicar o suplemento no AppSource depois de criá-lo, verifique se você está em conformidade com as Políticas de validação do AppSource. Por exemplo, para passar na validação, seu suplemento deve funcionar em todas as plataformas com suporte aos métodos que você definir (para mais informações, confira a seção 4.12 e a Página de hospedagem e disponibilidade do suplemento do Office).When you build your add-in, if you plan to publish your add-in to AppSource, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

A figura a seguir mostra um exemplo de um suplemento do Word que é executado em um painel de tarefas.The following figure shows an example of a Word add-in that runs in a task pane.

Figura 1. Suplemento em execução em um painel de tarefas no WordFigure 1. Add-in running in a task pane in Word

Suplemento em execução em um painel de tarefas no Word

O suplemento do Word (1) pode enviar solicitações para o documento do Word (2) e usar o JavaScript para acessar o objeto parágrafo e atualizar, excluir ou mover o parágrafo. Por exemplo, o código a seguir mostra como acrescentar uma nova sentença a esse parágrafo.The Word add-in (1) can send requests to the Word document (2) and can use JavaScript to access the paragraph object and update, delete, or move the paragraph. For example, the following code shows how to append a new sentence to that paragraph.

Word.run(function (context) {
    var paragraphs = context.document.getSelection().paragraphs;
    paragraphs.load();
    return context.sync().then(function () {
        paragraphs.items[0].insertText(' New sentence in the paragraph.',
                                       Word.InsertLocation.end);
    }).then(context.sync);
});

É possível usar qualquer tecnologia de servidor Web para hospedar o suplemento do Word, como ASP.NET, NodeJS ou Python. Use a estrutura de cliente de sua preferência (Ember, Backbone, Angular, React) ou use o VanillaJS para desenvolver a solução. É possível usar serviços como o Azure para autenticar e hospedar seu aplicativo.You can use any web server technology to host your Word add-in, such as ASP.NET, NodeJS, or Python. Use your favorite client-side framework -- Ember, Backbone, Angular, React -- or stick with VanillaJS to develop your solution, and you can use services like Azure to authenticate and host your application.

As APIs JavaScript do Word proporcionam ao seu aplicativo o acesso aos objetos e metadados encontrado em um documento do Word. Você pode usar essas APIs para criar suplementos que têm como objetivo:The Word JavaScript APIs give your application access to the objects and metadata found in a Word document. You can use these APIs to create add-ins that target:

  • Word 2013 ou posterior no WindowsWord 2013 or later on Windows
  • Word OnlineWord on the web
  • Word 2016 ou posterior no WindowsWord 2016 or later on Mac
  • Word no iPadWord on iPad

Redija seu suplemento uma vez e ele será executado em todas as versões do Word em várias plataformas. Para obter detalhes, consulte Disponibilidade de Suplementos do Office em hosts e plataformas.Write your add-in once, and it will run in all versions of Word across multiple platforms. For details, see Office Add-in host and platform availability.

APIs JavaScript para WordJavaScript APIs for Word

Você pode usar dois conjuntos de APIs JavaScript para interagir com metadados e objetos em um documento do Word.You can use two sets of JavaScript APIs to interact with the objects and metadata in a Word document. O primeiro é a API comuns, que foi introduzido no Office 2013.The first is the Common API, which was introduced in Office 2013. Muitos dos objetos na API comuns podem ser usados em suplementos hospedados por dois ou mais clientes do Office. Many of the objects in the Common API can be used in add-ins hosted by two or more Office clients. Essa API usa retornos de chamadas de maneira ampla.This API uses callbacks extensively.

O segundo é a API JavaScript do Word. Este é um modelo de objeto fortemente tipado que você pode usar para criar suplementos do Word que se destinam ao Word 2016 para Mac e Windows. Este modelo de objeto usa promessas e fornece acesso a objetos específicos do Word como corpo, controles de conteúdo, imagens embutidas e parágrafos. A API JavaScript do Word inclui definições do TypeScript e arquivos vsdoc para que você possa obter dicas de código em seu IDE.The second is the Word JavaScript API. This is a strongly-typed object model that you can use to create Word add-ins that target Word 2016 on Mac and Windows. This object model uses promises, and provides access to Word-specific objects like body, content controls, inline pictures, and paragraphs. The Word JavaScript API includes TypeScript definitions and vsdoc files so that you can get code hints in your IDE.

Atualmente, todos os clientes do Word são compatíveis com a API do JavaScript para Office compartilhada, e a maioria dos clientes é compatível com a API do JavaScript do Word. Para obter detalhes sobre clientes compatíveis, consulte a visão geral da API do JavaScript do Office.Currently, all Word clients support the shared JavaScript API for Office, and most clients support the Word JavaScript API. For details about supported clients, see the JavaScript API for Office overview.

Recomendamos que você comece com a API JavaScript do Word porque o modelo de objeto é mais fácil de usar. Use a API JavaScript do Word se precisar:We recommend that you start with the Word JavaScript API because the object model is easier to use. Use the Word JavaScript API if you need to:

  • Acessar os objetos em um documento do Word.Access the objects in a Word document.

Use a API JavaScript para Office compartilhada quando precisar:Use the shared JavaScript API for Office when you need to:

  • Direcionar o Word 2013.Target Word 2013.
  • Executar ações iniciais do aplicativo.Perform initial actions for the application.
  • Verificar o conjunto requisitos com suporte.Check the supported requirement set.
  • Acessar metadados, configurações e informações do ambiente para o documento.Access metadata, settings, and environmental information for the document.
  • Vincular a seções em um documento e capturar eventos.Bind to sections in a document and capture events.
  • Usar partes XML personalizadas.Use custom XML parts.
  • Abrir uma caixa de diálogo.Open a dialog box.

Próximas etapasNext steps

Pronto para criar seu primeiro suplemento do Word? Confira Criar seu primeiro suplemento do Word. Use o manifesto de suplemento para descrever onde seu suplemento está hospedado e como ele é exibido, bem como para definir permissões e outras informações.Ready to create your first Word add-in? See Build your first Word add-in. Use the add-in manifest to describe where your add-in is hosted, how it is displayed, and define permissions and other information.

Para saber mais sobre como projetar um suplemento do Word de classe internacional que cria uma ótima experiência para seus usuários, consulte Diretrizes de design e Práticas recomendadas.To learn more about how to design a world class Word add-in that creates a compelling experience for your users, see Design guidelines and Best practices.

Depois de desenvolver seu suplemento, é possível publicá-lo em um compartilhamento de rede, um catálogo de aplicativos ou no AppSource.After you develop your add-in, you can publish it to a network share, an app catalog, or AppSource.

Confira tambémSee also