Criação de Add-ins Office

Este guia descreve os passos necessários para a criação de um add-in para o Excel, usando a Framework Angular (versão 5 à data da criação deste documento).

Apesar do resultado final ser um add-in para o Excel, os passos necessários para outros programas da suite Office são semelhantes.

Referências: - Build an Excel add-in using Angular - Sideload Office Add-ins for testing - Sideload an Office Add-in on Office Online

Pré-Requisitos

  • Node.JS (Versão 6.9.0 ou superior) - Servidor onde corre a aplicação Angular e que permite também gerir os packages desta.

Para verificar a versão na linha de comandos:

node -v
  • Angular CLI - Gerador de linha de comandos de código Angular.
npm install -g @angular/cli
  • Yeoman - Gerador de código que facilita o ínicio de novos projetos. Neste caso, apenas é necessário o gerador do Office.
npm install -g yo generator-office

Geração da Aplicação Angular

Este exemplo foi construído usando como base uma aplicação Angular. Mas é possível usar qualquer tipo de framework Javascript (React, jQuery, etc.) 1. Usar o Angular CLI para criar o esqueleto da aplicação. Na raiz da pasta onde queremos criar o código (e.g.: C:\PrjNET\OfficeAddIns), deve ser executado o seguinte comando na linha de comandos:

ng new budget-addin

Nota: À data da criação deste guia, existe um bug na versão do CLI atual, que obriga a uma pequena alteração. Para validar se é necessária a alteração, deve ser executado o comando para arrancar a aplicação.

npm start

Caso ocorra o erro:

Error: Cannot find module '@angular-devkit/core'

É necessário alterar o ficheiro package.json. Na linha onde diz "@angular/cli": "1.6.4", alterar para "@angular/cli": "^1.6.4", seguido do comando npm update.

Depois deve ser corrido o comando:

npm start

Este comando efetua a compilação da aplicação Angular e arranca um servidor nodejs. Acedendo a http://localhost:4200/ a aplicação Angular deve estar a funcionar.

// TODO: Inserir imagem da App.

Criação do ficheiro Manifest

O ficheiro Manifest, é o ficheiro de definições do Add-In. Este é o ficheiro que posteriormente será importado no Excel.

  1. Navegar para a pasta da aplicação Angular.
cd budget-addin
  1. Usar o gerador yeoman para gerar o Manifest.
yo office

Responder às perguntas colocadas pelo Yeoman da seguinte forma:

  • Would you like to create a new subfolder for your project?: 
N
  • What do you want to name your add-in?: 
Budget Add-in
  • Which Office client application would you like to support?: 
Excel
  • Would you like to create a new add-in?: 
No, I already have a web app and only need a manifest file for my add-in.
  • Would you like to open it now while we finish creating your project? (Y/n)
No
  • Overwrite package.json?
No
  1. Abrir o ficheiro manifest (este ficheiro deve estar na raiz da aplicação, com o nome budget-add-in-manifest.xml). Alterar todas as ocorrências de https://localhost:3000/ para http://localhost:4200/ (atenção ao protocolo, https -> http)

Adicionar suporte para os tipos TypeScript do Office.js

A instalação dos tipos do Office.js permitirá, não só, a compilação do código TypeScript da aplicação que utilize a biblioteca Office.js, assim como, o acesso ao IntelliSense da biblioteca no Visual Studio Code.

  1. Primeiro deve ser instalado o package com os tipos.
npm install --save @types/office-js
  1. Alterar o ficheiro src\tsconfig.app.json. Na linha onde tem "types": [], colocar:
"types": ["office-js"]

Alterar a aplicação Angular para executar como add-in.

Seguindo os passos deste guia até aqui, temos uma aplicação Angular funcional, mas que ainda não executa como Add-in no Excel. Para que isto seja possível é necessário fazer o seguinte:

  1. Abrir o ficheiro src/index.html, e adicionar a seguinte tag, imediatamente acima da tag </head>. Este é o ficheiro da biblioteca do office.js fornecido pela Microsoft. Nota: Depois desta referência estar no ficheiro, a aplicação deixa de funcionar como aplicação Angular stand-alone, passando apenas a funcionar no contexto do Office.
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
  1. Abrir o ficheiro src/main.ts e trocar o bootstrap da aplicação.
platformBrowserDynamic().bootstrapModule(AppModule)
  .catch(err => console.log(err));

para 

Office.initialize = () => {
    platformBrowserDynamic().bootstrapModule(AppModule)
        .catch(err => console.log(err));
};
  1. Editar o ficheiro src/polyfills.ts, adicionar a seguinte linha:
import 'core-js/client/shim';
  1. No mesmo ficheiro src/polyfills.ts descomentar as seguintes linhas:
import 'core-js/es6/symbol';
import 'core-js/es6/object';
import 'core-js/es6/function';
import 'core-js/es6/parse-int';
import 'core-js/es6/parse-float';
import 'core-js/es6/number';
import 'core-js/es6/math';
import 'core-js/es6/string';
import 'core-js/es6/date';
import 'core-js/es6/array';
import 'core-js/es6/regexp';
import 'core-js/es6/map';
import 'core-js/es6/weak-map';
import 'core-js/es6/set';

Executar o add-in no Office (Versão Desktop)

Para testar o add-in na máquina onde está a ser desenvolvido, é necessário criar uma pasta onde irão estar alojados os ficheiros Manifest dos add-ins desenvolvidos.

Partilhar uma pasta de rede

  1. Criar uma pasta na máquina, onde estará o ficheiro xml do Manifest. E.g.:
C:\OfficeAddins

  1. Esta pasta tem de ter um endereço de rede. Para isso, no menu de contexto da pasta (clique direito do rato), aceder às Propriedades

  2. No separador Partilha (Sharing), carregar em Partilhar... e adicionar o próprio utilizador da máquina em que está a ser desenvolvido o add-in. O nível de permissões deve ser de pelo menos leitura e escrita. Também podem ser adicionados outros utilizadores, caso seja necessário ser testado noutra máquina da rede.

  3. O ficheiro de Manifest criado nos passos anteriores, deve ser colocado nesta pasta.

Especificar a pasta partilhada como catálogo de add-ins

  1. Abrir o Excel, e no menu Ficheiro, aceder às Opções
  2. Escolher Trust Center, e depois Trust Center Settings
  3. Escolher Trusted Add-in Catalogs
  4. Na secção Trusted Catalogs Table, na caixa Catalog Url, introduzir o caminho de rede para a pasta partilhada. (e.g.) \\ANDRESILVA\OfficeAddins
  5. Seleccionar a opção Show in Menu

Executar o add-in

  1. No Excel, no separador Inserir, seleccionar Meus add-ins.
  2. Escolher Pasta partilhada.
  3. Nesta janela, devem aparecer os add-ins, cujos ficheiros manifest se encontram na pasta adicionada como catálogo. Caso não apareça o add-in criado, o mais provável é existir um erro no ficheiro de Manifest.
  4. Carregar em OK. Se o servidor node estiver a correr (como demonstrado anteriormente, através do comando, npm start) o Add-in deve abrir num painel lateral.