Desenvolver Suplementos do Office
Dica
Análise a Visão geral da plataforma de Suplementos do Office antes de ler este artigo.
Todos os Suplementos do Office são criados com base na plataforma de Suplementos do Office. Para qualquer suplemento que você criar, você precisará entender conceitos importantes como disponibilidade de aplicativo e plataforma, padrões de programação da API do Office JavaScript, como especificar as configurações e recursos de um suplemento no arquivo de manifesto, como projetar a Interface do Usuário, experiência e muito mais. Conceitos básicos de desenvolvimento como esses são abordados aqui na seção Ciclo de vida de desenvolvimento>Desenvolver da documentação. Análise as informações contidas aqui antes de explorar a documentação específica do aplicativo que corresponde ao suplemento que você está criando (por exemplo, Excel).
Criar um Suplemento do Office
Pode criar um Suplemento do Office com o gerador Yeoman para Suplementos do Office, Visual Studio, Teams Toolkit ou o Development Kit de Suplementos do Office (pré-visualização).
Gerador do Yeoman
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. O gerador pode criar suplementos do Office para qualquer um dos seguintes aplicativos:
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
- Funções personalizadas do Excel
Crie o seu projeto com HTML, CSS e JavaScript (ou TypeScript) ou com React. Se escolher React, também pode escolher entre JavaScript e Typescript. Para saber mais sobre como criar suplementos com o gerador, confira Gerador do Yeoman para Suplementos do Office.
Visual Studio
O Visual Studio pode ser usado para criar suplementos do Office para o Excel, Outlook, Word e PowerPoint. Um projeto do suplemento do Office é criado como parte de uma solução do Visual Studio e usa HTML, CSS e JavaScript. Para saber mais sobre como criar suplementos usando o Visual Studio, confira Desenvolver suplementos do Office com o Visual Studio.
Kit de ferramentas do Teams
O Toolkit do Teams pode ser utilizado para criar praticamente qualquer tipo de Aplicação do Teams, um termo que inclui todas as extensões do Microsoft 365, incluindo as que não expandem a aplicação Teams. Para obter detalhes sobre como criar um suplemento, consulte Criar projetos de Suplementos do Office com o Teams Toolkit.
Development Kit de Suplementos do Office (pré-visualização)
O Development Kit de Suplementos do Office é uma extensão para Visual Studio Code. Permite-lhe criar novos projetos de suplementos e carregar exemplos diretamente a partir do IDE. Transfira a extensão a partir do Visual Studio Marketplace ou saiba mais no artigo Criar projetos de Suplementos do Office com o Development Kit de Suplementos do Office para Visual Studio Code.
Entender as duas partes de um Suplemento do Office
Um suplemento do Office consiste em duas partes.
O manifesto do suplemento que define as definições e capacidades do suplemento.
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.
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. 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.
Definir as configurações e os recursos do suplemento
O manifesto de um Suplemento do Office define as definições e capacidades do suplemento. Você vai configurar o manifesto para especificar itens como:
- Metadados que descrevem o suplemento (por exemplo, ID, versão, descrição, nome de exibição, local padrão).
- Aplicativos do Office onde o suplemento será executado.
- Permissões necessárias para o suplemento.
- Como o suplemento se integra ao Office, incluindo qualquer interface do usuário personalizada que o suplemento cria (por exemplo, uma guia personalizada ou botões de faixa de opções personalizados).
- Localização de imagens que o suplemento usa para identidade visual e iconografia de comando.
- Dimensões do suplemento (por exemplo, dimensões para suplementos de conteúdo, altura solicitada para suplementos do Outlook).
- As regras que especificam quando o suplemento é ativado no contexto de uma mensagem ou de um compromisso (somente para suplementos do Outlook).
- Atalhos de teclado (apenas para Excel).
Para obter informações detalhadas sobre o manifesto, consulte o manifesto de Suplementos do Office.
Interagir com o conteúdo em um documento do Office
Um suplemento do Office pode usar as APIs JavaScript para Office para interagir com o conteúdo no documento do Office no qual o suplemento está sendo executado.
Acessar a biblioteca de API JavaScript do Office
A biblioteca da API JavaScript do Office pode ser acessada por meio da CDN (rede de entrega de conteúdo) do Office JS em: https://appsforoffice.microsoft.com/lib/1.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.
<head>
...
<script src="https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js" type="text/javascript"></script>
</head>
Observação
Para usar APIs de visualização, faça referência à versão de visualização da biblioteca da API JavaScript do Office na CDN: https://appsforoffice.microsoft.com/lib/beta/hosted/office.js.
Para obter mais informações sobre como acessar a biblioteca da API JavaScript do Office, incluindo como obter o IntelliSense, consulte Fazendo referência à biblioteca da API JavaScript do Office a partir de sua CDN (rede de distribuição de conteúdo).
Modelos de API
A API JavaScript do Office inclui dois modelos diferentes:
As APIs específicas do aplicativo fornecem objetos fortemente tipados que podem ser usados para interagir com objetos que são nativos de um aplicativo específico do Office. Por exemplo, você pode usar as APIs JavaScript do Excel para acessar planilhas, intervalos, tabelas, gráficos e mais. As APIs específicas da aplicação estão atualmente disponíveis para as seguintes aplicações do Office.
Esse modelo de API usa promessas e permite que você especifique várias operações em cada solicitação enviada ao aplicativo do Office. Dessa maneira, operações de envio em lote podem melhorar significativamente o desempenho do suplemento em aplicativos do Office na Web. As APIs específicas da aplicação foram introduzidas com o Office 2016.
Observação
Também existe uma API específica da aplicação para o Visio, mas só pode utilizá-la em páginas do SharePoint Online para interagir com diagramas do Visio incorporados na página. Os Suplementos Web do Office não são suportados no Visio.
Confira Usando o modelo de API específico do aplicativo para saber mais sobre esse modelo de API.
As APIs Comuns pode ser usada para acessar recursos como interface de usuário, caixas de diálogo e configurações de cliente, que são comuns entre vários tipos de aplicativos do Office. Esse modelo de API usa retornos de chamada, que permitem especificar apenas uma operação em cada solicitação enviada ao aplicativo do Office. As APIs comuns foram introduzidas com o Office 2013 e podem ser utilizadas para interagir com quaisquer aplicações do Office suportadas. Para saber mais sobre o modelo de objeto da API Comum, que inclui APIs para interagir com o Outlook, o PowerPoint e o Project, confira Modelo de objeto da API JavaScript comum.
Observação
Funções personalizadas sem uma execução de runtime partilhado num runtime apenas javaScript que prioriza a execução de cálculos. Essas funções usam um modelo de programação ligeiramente diferente.
Conjuntos de requisitos da API
Os conjuntos de requisitos são grupos nomeados de membros da API. Os conjuntos de requisitos podem ser específicos para os aplicativos 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 aplicativos, 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).
Seu suplemento pode usar conjuntos de requisitos para determinar se o aplicativo do Office oferece suporte aos membros da API necessários. Para saber mais sobre isso, confira Especificar requisitos de API e aplicativos do Office.
O suporte a um conjunto de requisitos varia de acordo com o aplicativo do Office, a versão e a plataforma. 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 aplicativo e plataforma do cliente Office para Suplementos do Office.
Explorar as APIs com o 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. 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. 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.
O vídeo de um minuto a seguir mostra o Script Lab em ação.
Para saber mais sobre o Script Lab, confira Explorar as APIs JavaScript para Office usando o Script Lab.
Estender a interface do usuário do Office
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.
Os comandos de suplemento podem ser utilizados para adicionar um separador personalizado, botões e menus personalizados ao friso predefinido no Office ou para expandir o menu de contexto predefinido que é apresentado quando os utilizadores clicam com o botão direito do rato (ou selecionam sem soltar) texto num documento do Office ou num objeto no 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.
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. 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. 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.
A imagem seguinte mostra um comando de suplemento no friso, um painel de tarefas à direita do documento e uma caixa de diálogo ou suplemento de conteúdo sobre o documento.
Para obter mais informações sobre como estender a Interface de Usuário do Office e projetar a Experiência de Usuário do suplemento, confira Elementos da Interface do Usuário do Office para Suplementos do Office.
Próximos passos
Este artigo descreveu as diferentes maneiras de criar suplementos do Office, apresentou as maneiras como um suplemento pode estender a Interface do Usuário do Office, descreveu os conjuntos de API e apresentou o Script Lab como uma ferramenta valiosa para explorar as APIs de JavaScript do Office e os suplementos de prototipagem em funcionalidade. Agora que você explorou essas informações introdutórias, considere continuar sua jornada de Suplementos do Office pelos seguintes caminhos.
Criar um Suplemento do Office
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. Se você já concluiu um início rápido e deseja criar um suplemento um pouco mais complexo, experiente o tutorial.
Saiba mais
Saiba mais sobre o desenvolvimento, testes e publicação de suplementos do Office explorando essa documentação.
Dica
Para qualquer suplemento que você construir, você usará informações na seção Ciclo de vida de desenvolvimentodesta documentação, junto com informações na seção específica do aplicativo que corresponde ao tipo de suplemento que você está construindo (por exemplo, Excel).