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. Estes projetos são baseados em Node.js. Quando quiser que o código do lado do servidor do suplemento esteja num . Linguagem baseada em NET (como C# ou VB.Net) ou pretende que o suplemento seja alojado no Internet Information Server (IIS), utilize o Visual Studio para criar o suplemento.

Observação

Os suplementos do Office também podem ser criados com o Toolkit de Agentes do Microsoft 365 ou o Kit de desenvolvimento de suplementos do Office.

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 de nível "Olá, Mundo" 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).

Dica

Se quiser desviar-se significativamente destas opções, como utilizar um executor de tarefas diferente ou um servidor diferente, recomendamos que, quando executar a ferramenta, escolha a opção Apenas manifesto.

Pré-requisitos

Observação

Se você não conhece o Node.js ou o npm, deve começar configurando seu ambiente de desenvolvimento.

• 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 Microsoft 365 E5 através do Programa para Programadores do Microsoft 365. Para obter detalhes, consulte 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 40 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 for fornecida uma lista, utilize as teclas de seta para cima e para baixo para selecionar 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
• Excel, PowerPoint e/ou Word Painel de Tarefas com manifesto unificado para o Microsoft 365 (pré-visualização)
• Projeto do Painel de Tarefas do Suplemento do Office com React framework
• 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 do Painel de Tarefas do Suplemento do Office que suporta o início de sessão único da Autenticação de Aplicações Aninhadas (pré-visualização)
• Projeto de Suplemento do Office que contém apenas o manifesto

Observação

• O projeto do Suplemento do Office que contém a opção apenas manifesto produz um projeto que contém um manifesto de suplemento básico e um estruturamento mínimo. Para obter mais informações sobre a opção, veja opção Apenas manifesto.
• A opção Excel, PowerPoint e/ou Word Painel de Tarefas com manifesto unificado para o Microsoft 365 (pré-visualização) cria um projeto para o Excel, PowerPoint, Word ou os três, que utiliza o manifesto unificado para o Microsoft 365. Para obter mais informações sobre a opção, consulte Word, PowerPoint ou Excel com a opção de manifesto unificado.

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.

Observação

Para obter informações sobre clientes e plataformas que suportam diretamente Suplementos do Office que utilizam o manifesto unificado do Microsoft 365, consulte Suplementos do Office com o manifesto de aplicação unificada do Microsoft 365.

Depois de responder a todas as perguntas, 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, veja Avisos e dependências no Node.js e npm world.

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.)

Dica

Se quiser criar o estruturamento de um projeto de Suplemento do Office, mas adiar a instalação das dependências, adicione a opção --skip-install ao yo office comando . O código a seguir é um exemplo.

yo office --skip-install

Quando estiver pronto para instalar as dependências, navegue para a pasta raiz do projeto numa linha de comandos e introduza npm install.

Aviso

Se escolher o projeto do Painel de Tarefas do Suplemento do Office que suporte o início de sessão único e o TypeScript e estiver a utilizar uma versão de Node.js superior a 18.16.0, um erro no Node.js poderá fazer com que o ficheiro <de projeto root>\src\middle-tier\ssoauth-helper.ts esteja danificado. Para o corrigir, copie o conteúdo do ficheiro do repositório , ssoauth-helper.ts, sobre o conteúdo do ficheiro no projeto gerado.

Opção Apenas manifesto

Esta opção cria apenas um manifesto para um suplemento. O projeto resultante não tem um suplemento Olá, Mundo, 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 de React, como o Vue.

Word, PowerPoint ou Excel com a opção de manifesto unificado

O manifesto unificado do Microsoft 365 está em pré-visualização para Suplementos excel, PowerPoint e Word. Não deve ser utilizada para suplementos de produção, mas pode selecionar esta opção no Yo Office para criar um suplemento para uma (ou as três) dessas aplicações do Office. Ser-lhe-á pedido para escolher qual a aplicação do Office. Também pode selecionar Tudo para criar um suplemento que seja instalável nas três aplicações do Office. O projeto criado utiliza TypeScript.

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 Pré-requisitos 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.