Criar um suplemento para o Office Tornou-se uma forma muito poderosa de estender as funcionalidades do Word, Excel, Outlook, PowerPoint e outros aplicativos. Microsoft 365 sem a necessidade de desenvolver suplementos tradicionais para desktop. Esses novos suplementos são baseados em tecnologias web padrão e na API JavaScript do Office, permitindo a criação de experiências modernas, seguras e fáceis de implementar em toda a organização.
Nas linhas seguintes, você encontrará um guia bastante completo sobre ferramentas de desenvolvimento, tipos de manifesto, APIs disponíveis e opções de implantaçãoIntegração com a documentação oficial da Microsoft. A ideia é que você possa partir do zero e criar um suplemento funcional, entendendo a função de cada componente e as decisões técnicas necessárias em cada etapa.
O que é um suplemento moderno do Office e como ele é estruturado?
Complementos do Modern Office Eles dependem da plataforma de suplementos do Office, comum ao Word, Excel, PowerPoint, OneNote, Outlook e Project, em computadores, na web e, em alguns casos, em dispositivos móveis. Todos compartilham a mesma arquitetura básica, composta por duas partes claramente distintas.
A primeira peça é a manifesto do complementoEste arquivo funciona como o "cartão de identidade" do suplemento. Ele declara os metadados (ID, nome, versão, idiomas), com quais aplicativos do Office ele pode ser usado, quais permissões ele precisa, quais comandos ele adiciona à faixa de opções, quais ícones ele usa, onde o aplicativo da Web está hospedado e em quais contextos ele deve ser ativado (por exemplo, no Outlook, somente para mensagens ou compromissos que atendam a determinadas regras).
A segunda peça é a aplicação web Esta aplicação fornece a interface do usuário e a lógica de negócios. Ela consiste em HTML, CSS e JavaScript (ou TypeScript) e é executada dentro de um contêiner HTML do Office (painel de tarefas, suplemento de conteúdo ou caixa de diálogo). A partir daí, utiliza a biblioteca office.js para ler e gravar no documento, chamar serviços externos, lidar com autenticação, exibir caixas de diálogo e executar quaisquer outras tarefas típicas de um aplicativo web moderno.
Ferramentas para criar suplementos do Office
Não existe uma única maneira de iniciar um projeto de suplemento. A Microsoft oferece diversas ferramentas oficiaisEssas ferramentas atendem a diferentes perfis de usuário: desde aqueles que preferem os modelos do Visual Studio até aqueles que trabalham diariamente com Node.js e Visual Studio Code. Existem também ferramentas de terceiros ou mais especializadas, como editores de interface de usuário para VBA.
Gerador Yeoman para suplementos do Office
O gerador Yeoman para Office provavelmente é A opção mais flexível para desenvolvedores web. Ele permite que você crie projetos baseados em Node.js que podem ser editados com Visual Studio Code ou sua editora preferida. O assistente o guiará por uma série de perguntas para escolher o tipo de suplemento (painel de tarefas, suplemento de conteúdo, funções personalizadas, Outlook etc.) e o aplicativo de destino.
Com este gerador você pode Criar projetos para Excel, OneNote, Outlook, PowerPoint, Project, Word e funções personalizadas do Excel. Além disso, permite escolher entre uma estrutura simples com HTML, CSS e JavaScript/TypeScript ou uma arquitetura baseada em React, também em JavaScript ou TypeScript, com toda a estrutura do projeto já preparada.
Projetos do Visual Studio para Office
Se você se mover com mais conforto em ambientes .NETO Visual Studio inclui modelos específicos para suplementos do Office. Esses modelos abrangem principalmente Excel, Outlook, Word e PowerPoint, criando uma solução completa que inclui o manifesto do suplemento, o aplicativo Web e, opcionalmente, projetos de back-end associados.
O projeto do Visual Studio Também é baseado em HTML, CSS e JavaScript, mas se integra ao ecossistema clássico da Microsoft.Depuração, publicação, empacotamento e outras funcionalidades integradas. É uma boa opção quando você já trabalha com soluções corporativas no Visual Studio e deseja manter tudo centralizado no mesmo IDE.
Kit de ferramentas para agentes do Microsoft 365 e kit de desenvolvimento de suplementos do Office
Kit de ferramentas de agentes do Microsoft 365 Ele foi projetado para ir além dos suplementos tradicionais e criar praticamente qualquer tipo de extensão para o ecossistema do Microsoft 365, combinando bots, extensões do Teams e suplementos. Com essa ferramenta, você pode gerar projetos de suplementos do Office que se integram a aplicativos mais amplos do Microsoft 365.
Kit de desenvolvimento de suplementos do Office É uma extensão do Visual Studio Code que simplifica muito o dia a dia. Dentro do VS Code, você pode criar novos projetos de complementos, carregar exemplos de código prontos para teste e gerenciar todo o ciclo de desenvolvimento sem sair do editor. A extensão foi projetada para funcionar tanto com manifestos unificados quanto com manifestos específicos para complementos.
O manifesto: a essência da configuração do complemento.
Cada suplemento do Office é descrito por um arquivo de manifesto Isso informa aos aplicativos como carregá-lo, quais opções de interface expor e quais permissões exigir. Existem dois modelos de manifesto principais, e a escolha entre eles determina como você pode integrar seu suplemento com outras extensões do Microsoft 365.
Tipos de manifesto: apenas suplemento e manifesto unificado
- Manifesto do único complemento. É o formato clássico para suplementos de produção do Office no Excel, OneNote, Outlook, PowerPoint, Project e Word. É escrito em XML e foca-se exclusivamente na descrição do suplemento, sem o misturar com outros tipos de aplicações.
- Manifesto Unificado para o Microsoft 365. A evolução do modelo de manifesto em formato JSON, historicamente usado em aplicativos do Teams. Esse formato permite que diferentes tipos de extensões do Microsoft 365 — suplementos do Office, extensões do Teams etc. — sejam agrupadas em um único aplicativo.
A lógica de configuração é semelhante em ambos os casos.Você define um identificador único (geralmente um GUID), a versão, o nome de exibição, a descrição, os idiomas suportados, os ícones, os tipos de permissão (por exemplo, leitura ou leitura/gravação de documentos) e a estrutura da interface (guias, grupos e botões da faixa de opções). Você também especifica a URL de inicialização do aplicativo Web e quaisquer configurações adicionais, como atalhos de teclado no Excel ou Word, regras de acionamento no Outlook ou as dimensões dos painéis e suplementos de conteúdo.
Elementos-chave declarados no manifesto
Adição metadados básicosO manifesto deve detalhar cuidadosamente como o suplemento se integra à experiência do Office. Isso inclui imagens de marca e ícones de comando da faixa de opções, que devem ser hospedados em um servidor que permita o armazenamento em cache (cabeçalhos HTTP com Cache-Control: no-cache ou similar para produção).
Outro aspecto crítico é a segurançaTodos os URLs que apontam para o aplicativo Web ou recursos do suplemento devem usar HTTPS. Embora alguns cenários de desenvolvimento permitam HTTP ou certificados autoassinados, se você quiser executar o suplemento no Office na Web ou publicá-lo no Microsoft Marketplace, o SSL é obrigatório para evitar avisos de conteúdo misto e garantir a proteção de dados em trânsito.
Se você planeja distribuir seu complemento pelo Microsoft Marketplace, o manifesto deve incluir: Além do GUID exclusivo, é necessário um URL de suporte técnico válido e acessível. A Microsoft aplica uma série de diretrizes de validação onde a consistência dos dados do manifesto, o comportamento do suplemento e a conformidade com os requisitos de segurança e experiência do usuário são analisados.
Domínios e origens permitidos para Office.js
O manifesto também controla Quais domínios podem ser navegados dentro do painel de plugins?No Office na Web e no novo Outlook para Windows, o painel de tarefas pode carregar praticamente qualquer URL. No entanto, em aplicativos de desktop, o comportamento é mais restritivo: se o suplemento tentar navegar para um domínio diferente do domínio da página inicial, a URL será aberta fora do aplicativo, em uma janela separada do navegador.
Para evitar esse salto externo na área de trabalhoVocê pode listar explicitamente cada domínio adicional que deseja que apareça na janela do suplemento no manifesto. Se o destino estiver listado, ele será aberto no painel tanto no Office para desktop quanto no Office na Web; caso contrário, no desktop, ele será aberto em um navegador externo.
Interagindo com documentos usando a API JavaScript do Office
O aplicativo web do suplemento se comunica com o documento do Office. (ou com a mensagem, no caso do Outlook) por meio da biblioteca da API JavaScript do Office, acessível através da CDN oficial da Microsoft em https://appsforoffice.microsoft.com/lib/1/hosted/office.jsBasta fazer referência a este script na seção <head> da página para poder usar os tipos e métodos disponíveis.
Após o carregamento da biblioteca, você terá acesso a dois modelos de API complementares:
- APIs específicas da aplicação.
- APIs comuns.
Cada modelo foi projetado para atender a diferentes cenários, embora possam ser combinados no mesmo acessório, dependendo das necessidades.
APIs específicas da aplicação
APIs específicas da aplicação fornecem objetos fortemente tipados Esses elementos representam entidades nativas do aplicativo específico do Office. Por exemplo, no Excel, você tem objetos para planilhas, intervalos, tabelas e gráficos, que permitem manipular dados de forma estruturada e eficiente.
Este modelo é baseado em operações em loteVocê encadeia ações dentro de um contexto e, quando estiver pronto, sincroniza as alterações com o Office. Essa forma de trabalho reduz o número de interações entre o suplemento e o aplicativo, melhorando significativamente o desempenho, principalmente no Office na Web.
APIs comuns para funcionalidades compartilhadas
APIs comuns Eles se concentram em funcionalidades transversais presentes em diversas aplicações.Elementos de interface, caixas de diálogo, configurações do cliente, etc. Este modelo usa callbacks em vez de promises e, por definição, cada chamada executa uma única operação no aplicativo.
Com APIs comuns você pode, por exemplo, Exibir uma caixa de diálogo pop-up, gerenciar a configuração de um suplemento em diferentes hosts ou acessar determinadas funcionalidades do Outlook, PowerPoint ou Project que ainda não são cobertas por APIs específicas do aplicativo, dependendo do caso de uso.
Conjuntos de requisitos e compatibilidade entre plataformas
A compatibilidade da API está organizada em conjuntos de requisitosEsses são membros de API específicos do grupo sob um nome de versão. Existem conjuntos de requisitos específicos do aplicativo, como ExcelApi 1.7e outras compartilhadas, como DialogApi 1.1, que funcionam onde a funcionalidade de caixa de diálogo é suportada.
O suplemento pode verificar em tempo de execução se o aplicativo do Office em que está sendo executado atende aos requisitos necessários. Isso permite personalizar a experiência ou desativar recursos avançados quando o host não atende aos requisitos mínimos, evitando erros inesperados.
Explore a API com o Script Lab
Script Lab é um complemento gratuito Ele funciona como um ambiente de testes para a API JavaScript do Office. É instalado a partir do Microsoft Marketplace e executado em aplicativos como o Excel ou o Word, permitindo que você escreva e execute trechos de código em tempo real no documento atual.
Dentro do Script Lab, você tem acesso a um Biblioteca de exemplos prontos para uso que demonstram várias funcionalidades da API.Você pode usar esses trechos como base para seu próprio código, modificá-los e ver instantaneamente o resultado no documento, o que acelera bastante a fase de prototipagem e teste de funcionalidades antes de incorporá-las ao seu plugin final.
Como expandir a interface do usuário do Office
Uma das grandes vantagens dos complementos é que eles permitem Integrar a funcionalidade diretamente na interface do Office.para que o usuário não tenha a sensação de estar "saindo" do aplicativo. Isso é conseguido combinando comandos de plugins e contêineres HTML, como painéis de tarefas, plugins de conteúdo e caixas de diálogo.
- Comandos de complemento São utilizados para adicionar guias personalizadas, novos grupos e botões ou menus adicionais à faixa de opções do Office.
- Contêineres HTML (Painéis de tarefas, suplementos de conteúdo e caixas de diálogo) atuam como uma superfície na qual a interface do próprio suplemento pode ser exibida.
Em um cenário típico, você pode ter um comando que adiciona um grupo com um botão "Analisar Dados" no Excel; ao pressioná-lo, um painel de tarefas é aberto à direita com seu aplicativo da web, que analisa o intervalo selecionado, chama um serviço de aprendizado de máquina e retorna os resultados destacando células ou criando gráficos usando a API específica do Excel.
Criar um suplemento para o painel de tarefas com o Yeoman (exemplo no Word)
Colocar todos esses conceitos em prática.É útil ver na prática como criar um suplemento para o painel de tarefas usando o gerador do Yeoman, tanto para Word quanto para Outlook. Embora os detalhes da interface mudem entre os aplicativos, a estrutura do projeto e o fluxo de trabalho são muito semelhantes.
Pré-requisitos do ambiente de desenvolvimento
Antes de gerar o projetoVocê precisa ter a versão LTS mais recente do Node.js instalada, que pode ser baixada do site oficial. Após a instalação, instale globalmente o Yeoman e o gerador do Office usando o comando. npm install -g yo generator-officePor fim, certifique-se de que o Office esteja vinculado a uma assinatura do Microsoft 365 que inclua o Office na Web, pois você testará o suplemento tanto no computador quanto no navegador.
Criando um suplemento do Word com um painel de tarefas
O primeiro passo é Decida o tipo de manifesto Você deve escolher qual usar dependendo se pretende combinar seu complemento com outras extensões em um único aplicativo ou não. Depois de tomar sua decisão, execute o comando. yo office no diretório de trabalho.
Durante o assistente interativoVocê pode, por exemplo, escolher um tipo de projeto, atribuir um nome como "Meu Suplemento do Office" e selecionar o Word como o aplicativo cliente de destino. Ao concluir, o gerador cria a pasta do projeto, instala as dependências do Node e prepara tudo para uso.
Dentro da solução você encontrará o arquivo de manifesto (manifest.json o manifest.xml) na raiz, que define a configuração do plugin; o arquivo ./src/taskpane/taskpane.html com a marcação do painel de tarefas; o CSS em ./src/taskpane/taskpane.csse o código que chama a API do Office em ./src/taskpane/taskpane.ts o .jsDependendo se você escolheu TypeScript ou JavaScript.
Para testar o suplemento no Word para desktop.Basta navegar até a pasta raiz do projeto (cd "My Office Add-in"e executar npm startEste comando inicia o servidor web local e abre o Word com o suplemento já carregado no modo de carregamento lateral. Se preferir experimentá-lo no Word na web, você pode usar um comando como este: npm run start -- web --document {url}, substituindo o URL pelo de um documento armazenado no OneDrive ou SharePoint.
Servidor de desenvolvimento e gerenciamento de dependências
Durante o desenvolvimento é comum que npm install Pode ocorrer uma falha durante a etapa automática executada pelo Yeoman, especialmente se houver conflitos com as versões das dependências. Nesses casos, basta acessar a pasta do projeto e executar o comando. npm install manualmente para resolvê-lo.
Se aparecerem avisos de dependência obsoletaVocê pode confiar na ferramenta. npm-check-updates, instalando-o com npm i -g npm-check-updates, executando ncu -u para atualizar intervalos de versões em package.json e concluindo o processo com um novo npm installMuitos desses avisos não são críticos, mas é uma boa prática revisá-los periodicamente para manter o projeto em bom funcionamento.
Para interromper o servidor de desenvolvimento e desinstale o plugin no modo de carregamento lateral, você poderá executar npm stop no diretório raiz. Se você já tiver carregado o suplemento manualmente (por exemplo, carregando o manifesto para o Office na Web), também precisará removê-lo manualmente da interface de administração correspondente.
Desde a estrutura básica de um suplemento e ferramentas de desenvolvimento (Yeoman, Visual Studio, Agents Toolkit, Script Lab) até o papel do manifesto, APIs JavaScript, controles de segurança e opções de implantação (local, Marketplace, implantação centralizada ou por meio de provedores como o Qlik), você tem um mapa bastante completo Para decidir que tipo de complemento você precisa, como criá-lo e como disponibilizá-lo aos seus usuários sem surpresas técnicas.