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.

Observação

Os suplementos do Office também podem ser criados com o Teams Toolkit (versão de pré-lançamento). Para obter mais informações sobre como fazê-lo e as limitações, consulte Criar projetos de Suplementos do Office com o Toolkit do Teams (pré-visualização).

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.

Instalar o gerador

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

Os Suplementos do Office que utilizam o manifesto unificado do Microsoft 365 são diretamente suportados no Office na Web, no novo Outlook no Windows e no Office no Windows ligado a uma subscrição do Microsoft 365, Versão 2304 (Compilação 16320.00000) ou posterior.

Quando o pacote de aplicação que contém o manifesto unificado é implementado no AppSource ou no Administração Microsoft 365 Center, se o manifesto tiver uma propriedade "alternateIcons" válida, é gerado um manifesto apenas de suplemento a partir do manifesto unificado e armazenado. Este manifesto apenas de suplemento permite que o suplemento seja instalado em plataformas que não suportam diretamente o manifesto unificado, incluindo o Office no Mac, o Office em dispositivos móveis, versões de subscrição do Office no Windows anteriores à 2304 (Compilação 16320.00000) e versões perpétuas do Office no Windows.

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

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

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.