Criar projetos de Suplementos do Office com o Yeoman Generator

O Yeoman Generator para Suplementos do Office (também denominado "Yo Office") é uma ferramenta de linha de comandos interativa baseada em Node.js que cria projetos de desenvolvimento de Suplementos do Office. Recomendamos que utilize esta ferramenta para criar projetos de suplementos, exceto quando quiser que o código do lado do servidor do suplemento esteja num . Linguagem baseada em NET (como C# ou VB.Net) ou quer o suplemento alojado no Internet Information Server (IIS). Em qualquer uma das duas últimas situações, utilize o Visual Studio para criar o suplemento.

Os projetos que a ferramenta cria têm as seguintes características.

• Têm uma configuração npm padrão que inclui um ficheiro package.json .
• Incluem vários scripts úteis para criar o projeto, iniciar o servidor, fazer sideload do suplemento no Office e outras tarefas.
• Utilizam o webpack como um bundler e um executor de tarefas básico.
• No modo de desenvolvimento, são alojados no localhost pelo webpack webpack baseado em Node.js-dev-server, uma versão orientada para o desenvolvimento do servidor express que suporta o recarregamento frequente e a recompilação em mudança.
• Por predefinição, todas as dependências são instaladas pela ferramenta, mas pode adiar a instalação com um argumento de linha de comandos.
• Incluem um manifesto de suplemento completo.
• Têm um suplemento ao nível "Hello World" que está pronto para ser executado assim que a ferramenta terminar.
• Incluem um polifill e um transpiler que está configurado para transpíle TypeScript e versões recentes do JavaScript para ES5 JavaScript. Estas funcionalidades garantem que o suplemento é suportado em todos os runtimes do Webview nos quais os Suplementos do Office podem ser executados, incluindo o Trident (Internet Explorer).

Instalar o gerador

• Node.js (a versão mais recente de LTS). Visite o siteNode.js para transferir e instalar a versão certa para o seu sistema operativo.

• A versão mais recente do Yeoman e do Yeoman gerador de Suplementos do Office. Para instalar essas ferramentas globalmente, execute o seguinte comando por meio do prompt de comando.

  npm install -g yo generator-office
  

  Observação

  Mesmo se você já instalou o gerador Yeoman, recomendamos atualizar seu pacote para a versão mais recente do npm.

• Office conectado a uma assinatura Microsoft 365 (incluindo o Office na web).

  Observação

  Se ainda não tiver o Office, poderá qualificar-se para uma subscrição de programador do Microsoft 365 E5 através do Programa para Programadores do Microsoft 365; para obter detalhes, veja as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.

Utilizar a ferramenta

Inicie a ferramenta com o seguinte comando numa linha de comandos do sistema (não numa janela bash). Esta ação irá criar um novo projeto numa nova pasta no diretório atual.

yo office 

É necessário carregar muita coisa, pelo que pode demorar 20 segundos até a ferramenta ser iniciada. A ferramenta faz-lhe uma série de perguntas. Para alguns, basta escrever uma resposta para o pedido. Para outras pessoas, é-lhe dada uma lista de respostas possíveis. Se lhe for dada uma lista, selecione uma e, em seguida, selecione Enter.

A primeira pergunta pede-lhe para escolher entre vários tipos de projetos. As opções são:

• Projeto do Painel de Tarefas do Suplemento do Office
• Projeto do Painel de Tarefas do Suplemento do Office com a estrutura do React
• Funções Personalizadas do Excel com um Runtime Partilhado
• Funções Personalizadas do Excel com um Runtime apenas em JavaScript
• Projeto do Painel de Tarefas do Suplemento do Office que suporta o início de sessão único
• Projeto de Suplemento do Office que contém apenas o manifesto

A pergunta seguinte pede-lhe para escolher entre TypeScript e JavaScript. (Esta pergunta é ignorada se tiver escolhido a opção apenas de manifesto na pergunta anterior.)

Em seguida, ser-lhe-á pedido para dar um nome ao suplemento. O nome que especificar será utilizado no manifesto do suplemento, mas pode alterá-lo mais tarde. Este é também o nome da pasta do projeto.

Em seguida, ser-lhe-á pedido para escolher em que aplicação do Office o suplemento deve ser executado. Existem seis aplicações possíveis à escolha: Excel, OneNote, Outlook, PowerPoint, Project e Word. Tem de escolher apenas uma, mas pode alterar o manifesto mais tarde para suportar as aplicações adicionais do Office. A exceção é o Outlook. Um manifesto que suporte o Outlook não pode suportar qualquer outra aplicação do Office.

Se escolher o Outlook como a aplicação do Office, receberá uma pergunta adicional a perguntar-lhe que tipo de manifesto pretende utilizar. Recomendamos que escolha o manifesto unificado para o Microsoft 365 , a menos que o seu suplemento inclua uma funcionalidade de extensibilidade que ainda não é suportada pelo manifesto unificado.

Depois de responder a esta pergunta, o gerador cria o projeto e instala as dependências. Poderá ver mensagens AVISO na saída npm no ecrã. Pode ignorá-los. Também poderá ver mensagens a indicar que foram encontradas vulnerabilidades. Pode ignorá-los por agora, mas terá eventualmente de corrigi-los antes de o seu suplemento ser lançado para produção. Para obter mais informações sobre como corrigir vulnerabilidades, abra o browser e procure "vulnerabilidade npm".

Se a criação for bem-sucedida, verá uma mensagem Parabéns! na janela de comando, seguida de alguns passos seguintes sugeridos. (Se estiver a utilizar o gerador como parte de um início rápido ou tutorial, ignore os passos seguintes na janela de comandos e continue com as instruções no artigo.)

yo office --skip-install

Opção Apenas manifesto

Esta opção cria apenas um manifesto para um suplemento. O projeto resultante não tem um suplemento Hello World, nenhum dos scripts ou qualquer uma das dependências. Utilize esta opção nos seguintes cenários.

• Quer utilizar ferramentas diferentes das que um projeto gerador Yeoman instala e configura por predefinição. Por exemplo, quer utilizar um bundler, transpiler, execução de tarefas ou servidor de desenvolvimento diferente.
• Quer utilizar uma arquitetura de desenvolvimento de aplicações Web, para além do React, como o Vue.

Para obter um exemplo de utilização do gerador com a opção apenas de manifesto, veja Utilizar o Vue para criar um suplemento do painel de tarefas do Excel.

Utilizar parâmetros da linha de comandos

Também pode adicionar parâmetros ao yo office comando . As duas opções mais comuns são:

• yo office --details: será apresentada uma breve ajuda sobre todos os outros parâmetros da linha de comandos.
• yo office --skip-install: isto impedirá que o gerador instale as dependências.

Para obter referência detalhada sobre os parâmetros da linha de comandos, consulte o readme do gerador em Yeoman generator for Office Add-ins (Gerador Yeoman para Suplementos do Office).

Solução de problemas

Se tiver problemas ao utilizar a ferramenta, o primeiro passo deverá ser reinstalá-la para se certificar de que tem a versão mais recente. (Consulte Instalar o gerador para obter detalhes.) Se tal não resolver o problema, pesquise os problemas do repositório do GitHub da ferramenta para ver se mais alguém encontrou o mesmo problema e encontrou uma solução. Se ninguém tiver, crie um novo problema.