Criar projetos de suplemento do Office usando o Gerador yeoman

O Gerador yeoman para suplementos do Office (também chamado de "Yo Office") é uma ferramenta interativa de linha de comando baseada em Node.js que cria projetos de desenvolvimento de suplementos do Office. Recomendamos que você use essa ferramenta para criar projetos de suplemento, exceto quando quiser que o código do lado do servidor do suplemento esteja em um . Linguagem baseada em NET (como C# ou VB.Net) ou deseja que o suplemento seja hospedado no IIS (Servidor de Informações da Internet). Em uma das duas últimas situações, use o Visual Studio para criar o suplemento.

Observação

Os suplementos do Office também podem ser criados com o Kit de Ferramentas do Teams (versão pré-lançamento). Para obter mais informações sobre como fazer isso e as limitações, confira Criar projetos de suplemento do Office usando o Kit de Ferramentas do Teams (versão prévia).

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

• Eles têm uma configuração npm padrão que inclui um arquivo package.json .
• Eles incluem vários scripts úteis para criar o projeto, iniciar o servidor, carregar o suplemento no Office e outras tarefas.
• Eles usam o webpack como um empacotador e um gerenciador de tarefas básico.
• No modo de desenvolvimento, eles são hospedados no localhost pelo webpack-dev-server baseado em Node.js webpack, uma versão orientada para desenvolvimento do servidor expresso que dá suporte a hot-reloading e recompile-on-change.
• Por padrão, todas as dependências são instaladas pela ferramenta, mas você pode adiar a instalação com um argumento de linha de comando.
• Eles incluem um manifesto de suplemento completo.
• Eles têm um suplemento no nível de "Olá, Mundo" que está pronto para execução assim que a ferramenta for concluída.
• Eles incluem um polyfill e um transpiler configurado para transpilar TypeScript e versões recentes do JavaScript para JavaScript ES5. Esses recursos garantem que o suplemento tenha suporte em todos os runtimes de webview em que os Suplementos do Office podem ser executados, incluindo Trident (Internet Explorer).

Dica

Se você quiser desviar-se significativamente dessas opções, como usar um gerenciador de tarefas diferente ou um servidor diferente, recomendamos que, ao executar a ferramenta, escolha a opção Somente 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 baixar e instalar a versão certa para seu sistema operacional.

• 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 você ainda não tiver o Office, poderá se qualificar para uma assinatura de desenvolvedor Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar um plano do Microsoft 365.

Usar a ferramenta

Inicie a ferramenta com o comando a seguir em um prompt do sistema (não uma janela bash). Isso criará um novo projeto em uma nova pasta no diretório atual.

yo office 

Muita coisa precisa ser carregada, portanto, pode levar 20 segundos até que a ferramenta comece. A ferramenta faz uma série de perguntas. Para alguns, basta digitar uma resposta para o prompt. Para outras pessoas, você recebe uma lista de possíveis respostas. Se receber uma lista, selecione uma e selecione Inserir.

A primeira pergunta pede que você escolha entre vários tipos de projetos. As opções são:

• Projeto do Painel de Tarefas de Suplemento do Office
• Projeto do Painel de Tarefas de Suplemento do Office usando React estrutura
• Funções Personalizadas do Excel usando um Runtime Compartilhado
• Funções Personalizadas do Excel usando um Runtime somente JavaScript
• Projeto do Painel de Tarefas de Suplemento do Office que dá suporte ao logon único
• Suplemento do Outlook com o manifesto unificado do Microsoft 365 (versão prévia)
• Projeto de suplemento do Office que contém apenas o manifesto

Observação

• O manifesto unificado está em versão prévia e tem suporte apenas no Outlook no Windows. Ainda não há suporte para um suplemento de produção.
• O projeto de suplemento do Office que contém a opção somente manifesto produz um projeto que contém um manifesto de suplemento básico e um scaffolding mínimo. Para obter mais informações sobre a opção, consulte opção Somente manifesto.

A próxima pergunta pede que você escolha entre TypeScript e JavaScript. (Essa pergunta será ignorada se você escolher a opção somente manifesto na pergunta anterior.)

Em seguida, você será solicitado a dar um nome ao suplemento. O nome especificado será usado no manifesto do suplemento, mas você pode alterá-lo posteriormente. Esse também é o nome da pasta para o projeto.

Em seguida, você será solicitado a escolher em qual aplicativo do Office o suplemento deve ser executado. Há seis aplicativos possíveis para escolher: Excel, OneNote, Outlook, PowerPoint, Project e Word. Você deve escolher apenas um, mas pode alterar o manifesto posteriormente para dar suporte aos aplicativos adicionais do Office. A exceção é o Outlook. Um manifesto que dá suporte ao Outlook não pode dar suporte a nenhum outro aplicativo do Office.

Depois de responder a essa pergunta, o gerador cria o projeto e instala as dependências. Você pode ver mensagens WARN na saída npm na tela. Você pode ignorá-los. Você também pode ver mensagens de que vulnerabilidades foram encontradas. Você pode ignorá-los por enquanto, mas eventualmente precisará corrigi-los antes que seu suplemento seja liberado para produção. Para obter mais informações sobre como corrigir vulnerabilidades, abra seu navegador e pesquise por "vulnerabilidade npm".

Se a criação for bem-sucedida, você verá uma mensagem Parabéns! na janela de comando, seguida por algumas próximas etapas sugeridas. (Se você estiver usando o gerador como parte de um início rápido ou tutorial, ignore as próximas etapas na janela de comando e continue com as instruções no artigo.)

Dica

Se você quiser criar o scaffolding 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 até a pasta raiz do projeto em um prompt de comando e insira npm install.

Aviso

Se você escolher o projeto do Painel de Tarefas de Suplemento do Office com suporte a logon único e TypeScript e estiver usando uma versão Node.js maior que 18.16.0, um bug no Node.js fará com que a raiz> do arquivo< de projeto\src\middle-tier\ssoauth-helper.ts seja corrompida. Para corrigi-lo, copie o conteúdo do arquivo do repositório, ssoauth-helper.ts, sobre o conteúdo do arquivo no projeto gerado.

Opção somente manifesto

Essa 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. Use essa opção nos cenários a seguir.

• Você deseja usar ferramentas diferentes das que um projeto gerador yeoman instala e configura por padrão. Por exemplo, você deseja usar um empacotador, um transpilador, um gerenciador de tarefas ou um servidor de desenvolvimento diferente.
• Você deseja usar uma estrutura de desenvolvimento de aplicativos Web, diferente de React, como o Vue.

Para obter um exemplo de como usar o gerador com a opção somente manifesto, consulte Usar o Vue para criar um suplemento de painel de tarefas do Excel.

Usar parâmetros de linha de comando

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

• yo office --details: isso gerará uma breve ajuda sobre todos os outros parâmetros de linha de comando.
• yo office --skip-install: isso impedirá que o gerador instale as dependências.

Para obter referência detalhada sobre os parâmetros de linha de comando, consulte o readme do gerador no gerador Yeoman para Suplementos do Office.

Solução de problemas

Se você encontrar problemas usando a ferramenta, sua primeira etapa deve ser reinstalá-la para ter certeza de que você tem a versão mais recente. (Consulte Instalar o gerador para obter detalhes.) Se isso não resolver o problema, pesquise os problemas do repositório GitHub para ver se outra pessoa encontrou o mesmo problema e encontrou uma solução. Se ninguém tiver, crie um novo problema.