Criar um suplemento do painel de tarefas do Excel

Neste artigo, você passará pelo processo de criação de um suplemento do painel de tarefas do Excel. Irá utilizar o Development Kit de Suplementos do Office ou o gerador Yeoman para criar o seu Suplemento do Office. Selecione a guia do que você deseja usar e, em seguida, siga as instruções para criar o suplemento e testá-lo localmente. Se quiser criar o projeto de suplemento no Visual Studio Code, recomendamos o Development Kit de Suplementos do Office.

Kit de Desenvolvimento de Suplementos do Office

Pré-requisitos

• Transfira e instale Visual Studio Code.
• 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. Para verificar se já instalou estas ferramentas, execute os comandos node -v e npm -v no terminal.
• Office ligado a uma subscrição do Microsoft 365. Pode qualificar-se para uma subscrição de programador Microsoft 365 E5 através do Programa para Programadores do Microsoft 365. Consulte FAQ para obter detalhes. Em alternativa, pode inscrever-se numa avaliação gratuita de um mês ou comprar um plano do Microsoft 365.

Criar o projeto do suplemento

Clique no botão seguinte para criar um projeto de suplemento com o Development Kit de Suplementos do Office para Visual Studio Code. Ser-lhe-á pedido que instale a extensão se ainda não a tiver. Será aberta uma página que contém a descrição do projeto no Visual Studio Code.

Criar um suplemento no Visual Studio Code

Na página pedida, selecione Criar para criar o projeto de suplemento. Na caixa de diálogo da pasta Área de Trabalho que é aberta, selecione a pasta onde pretende criar o projeto.

O Development Kit de Suplementos do Office irá criar o projeto. Em seguida, abrirá o projeto numa segunda janela Visual Studio Code. Feche a janela de Visual Studio Code original.

Observação

Se utilizar o VSCode Insiders ou tiver problemas ao abrir a página do projeto no VSCode, instale a extensão manualmente ao seguir estes passos e localize o exemplo na galeria de exemplo.

Explore o projeto

O projeto de suplemento que criou com o Development Kit de Suplementos do Office contém código de exemplo para um suplemento do painel de tarefas básico. Se você quiser examinar os componentes do seu projeto de suplemento, abra o projeto no seu editor de código e revise os arquivos listados abaixo. Quando estiver pronto para experimentar o suplemento, prossiga para a próxima seção.

1. O ficheiro ./manifest.xml ou ./manifest.json no diretório de raiz do projeto define as definições e capacidades do suplemento.
2. O arquivo ./src/taskpane/taskpane.html contém a marcação HTML do painel de tarefas.
3. O arquivo ./src/taskpane/taskpane.css contém o CSS que é aplicado ao conteúdo no painel de tarefas.
4. O arquivo ./src/taskpane/taskpane.js contém o código da API JavaScript do Office que facilita a interação entre o painel de tarefas e o aplicativo cliente do Office.

Experimente

1. Abra a extensão ao selecionar o ícone do Development Kit de Suplementos do Office na Barra de Atividade.
2. Selecione Pré-visualizar o Seu Suplemento do Office (F5)
3. No menu Escolha Rápida, selecione a opção {Office Application} Desktop (Edge Chromium), em que "{Office Application}" é a aplicação adequada, como "Excel" ou "Word". Esta ação irá iniciar o suplemento e depurar o código.

O kit de desenvolvimento verifica se os pré-requisitos são cumpridos antes do início da depuração. Verifique o terminal para obter informações detalhadas se existirem problemas com o seu ambiente. Após este processo, a aplicação de ambiente de trabalho do Office é iniciada e efetua sideloads do suplemento. Tenha em atenção que, quando executar um projeto pela primeira vez, poderá demorar alguns minutos a instalar as dependências. Terá de instalar o certificado quando lhe for pedido.

Parar de testar o seu Suplemento do Office

Quando terminar de testar e depurar o suplemento, feche sempre o suplemento ao seguir estes passos. (Fechar a aplicação do Office ou a janela do servidor Web não regista de forma fiável o suplemento.)

1. Abra a extensão ao selecionar o ícone do Development Kit de Suplementos do Office na Barra de Atividade.
2. Selecione Parar a Pré-visualização do Seu Suplemento do Office. Esta ação fecha o servidor Web e remove o suplemento do registo e da cache.
3. Feche a janela da aplicação do Office.

Solução de problemas

Se tiver problemas ao executar o suplemento, siga estes passos.

• Feche todas as instâncias abertas do Office.
• Feche o servidor Web anterior iniciado para o suplemento com a opção Parar de Pré-visualizar a extensão do Development Kit de Suplementos do Office.

O artigo Resolver erros de desenvolvimento com Suplementos do Office contém soluções para problemas comuns. Se os problemas persistirem, crie um problema do GitHub e iremos ajudá-lo.

Para obter informações sobre como executar o suplemento no Office na Web, consulte Sideload Office Add-ins to Office na Web (Sideload Office Add-ins to Office na Web( Transferir Suplementos do Office para Office na Web).

Para obter informações sobre a depuração em versões mais antigas do Office, consulte Depurar suplementos com ferramentas de programador no Versão Prévia do Microsoft Edge.

Gerador do Yeoman

Pré-requisitos

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

Criar o projeto do suplemento

Execute o comando a seguir para criar um projeto de suplemento usando o gerador Yeoman. Será adicionada uma pasta que contém o projeto ao diretório atual.

yo office

Observação

Ao executar o comando yo office, você receberá informações sobre as políticas de coleta de dados de Yeoman e as ferramentas da CLI do suplemento do Office. Use as informações fornecidas para responder às solicitações como achar melhor.

Quando solicitado, forneça as informações a seguir para criar seu projeto de suplemento.

• Escolha um tipo de projeto:Office Add-in Task Pane project
• Escolha um tipo de script:Javascript
• Qual é o nome do seu suplemento?My Office Add-in
• Que aplicação cliente do Office pretende suportar?Excel

Depois que você concluir o assistente, o gerador criará o projeto e instalará os componentes Node de suporte.

Explore o projeto

O projeto de suplemento que você criou com o gerador Yeoman contém um código de exemplo para um suplemento básico do painel de tarefas. Se você quiser examinar os componentes do seu projeto de suplemento, abra o projeto no seu editor de código e revise os arquivos listados abaixo. Quando estiver pronto para experimentar o suplemento, prossiga para a próxima seção.

• O ficheiro ./manifest.xml ou manifest.json no diretório de raiz do projeto define as definições e capacidades do suplemento.
• O arquivo ./src/taskpane/taskpane.html contém a marcação HTML do painel de tarefas.
• O arquivo ./src/taskpane/taskpane.css contém o CSS que é aplicado ao conteúdo no painel de tarefas.
• O arquivo ./src/taskpane/taskpane.js contém o código da API JavaScript do Office que facilita a interação entre o painel de tarefas e o aplicativo cliente do Office.

Experimente

1. Navegue até a pasta raiz do projeto.

   cd "My Office Add-in"
   

2. Conclua as etapas a seguir para iniciar o servidor Web local e fazer o sideload do seu suplemento.

   Observação

   • Os Suplementos do Office devem utilizar HTTPS e não HTTP, mesmo quando estiver a desenvolver. Se lhe for pedido para instalar um certificado depois de executar um dos seguintes comandos, aceite o pedido para instalar o certificado que o gerador Yeoman fornece. Você também pode executar o prompt de comando ou terminal como administrador para que as alterações sejam feitas.

   • Se esta for a primeira vez que desenvolve um Suplemento do Office no seu computador, poderá ser-lhe pedido na linha de comandos para conceder ao Microsoft Edge WebView uma isenção de loopback ("Permitir loopback localhost para o Microsoft Edge WebView?"). Quando lhe for pedido, introduza Y para permitir a isenção. Tenha em atenção que precisará de privilégios de administrador para permitir a isenção. Uma vez permitido, não lhe deverá ser pedida uma isenção quando carregar os Suplementos do Office no futuro (a menos que remova a isenção do seu computador). Para saber mais, consulte "Não é possível abrir este suplemento a partir do localhost" ao carregar um Suplemento do Office ou ao utilizar o Fiddler.

     

   • Quando utiliza o gerador Yeoman pela primeira vez para desenvolver um Suplemento do Office, o seu browser predefinido abre uma janela onde lhe será pedido para iniciar sessão na sua conta do Microsoft 365. Se não for apresentada uma janela de início de sessão e encontrar um erro de tempo limite de sideload ou início de sessão, execute atk auth login m365.

   Dica

   Se você estiver testando o seu suplemento no Mac, execute o seguinte comando antes de continuar. O servidor Web local é iniciado quando este comando é executado.

   npm run dev-server
   

   • Para testar o seu suplemento no Excel, execute o seguinte comando no diretório raiz do projeto. Isso inicia o servidor Web local e abre o Excel com seu suplemento carregado.

     npm start
     

   • Para testar o seu suplemento no Excel em um navegador, execute o seguinte comando no diretório raiz do projeto. O servidor Web local é iniciado quando este comando é executado. Substitua “{url}” pelo URL de um documento do Excel no seu OneDrive ou uma biblioteca do SharePoint para a qual você tenha permissões.

     Observação

     Se estiver a desenvolver num Mac, coloque as {url} aspas simples. Não o faça no Windows.

     npm run start -- web --document {url}
     

     Eis alguns exemplos.

     • npm run start -- web --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
     • npm run start -- web --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
     • npm run start -- web --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

     Se o seu suplemento não carregar em sideload no documento, carregue-o manualmente ao seguir as instruções em Suplementos de sideload manualmente para Office na Web.

3. No Excel, selecione o separador Base e, em seguida, selecione o botão Mostrar Painel de Tarefas no friso para abrir o painel de tarefas do suplemento.

   

4. Selecione um intervalo de células na planilha.

5. Na parte inferior do painel de tarefas, escolha o link Executar para definir a cor do intervalo selecionado como amarelo.

   

6. Quando quiser parar o servidor Web local e desinstalar o suplemento, siga as instruções aplicáveis:

   • Para parar o servidor, execute o seguinte comando. Se tiver utilizado npm start, o seguinte comando também desinstala o suplemento.

     npm stop
     

   • Se tiver carregado manualmente o suplemento em sideload, consulte Remover um suplemento sideloaded.

Solução de problemas

• Certifique-se de que o seu ambiente está pronto para o desenvolvimento do Office ao seguir as instruções em Configurar o seu ambiente de desenvolvimento.

• Alguns dos códigos de exemplo utilizam JavaScript ES6. Isto não é compatível com versões mais antigas do Office que utilizam o motor de browser Trident (Internet Explorer 11). Para obter informações sobre como suportar essas plataformas no seu suplemento, consulte Suportar webviews mais antigos da Microsoft e versões do Office. Se ainda não tiver uma subscrição do Microsoft 365 para utilizar para desenvolvimento, 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.

• O passo automático npm install que o Yo Office executa pode falhar. Se vir erros ao tentar executar npm start, navegue para a pasta do projeto recentemente criada numa linha de comandos e execute npm installmanualmente . Para obter mais informações sobre o Yo Office, consulte Criar projetos de Suplementos do Office com o Yeoman Generator.
• Poderá ver avisos gerados ao executar npm install para o gerador Yeoman ou para o projeto. Na maioria dos casos, pode ignorar estes avisos com segurança. Por vezes, as dependências são preteridas e as respetivas substituições não são suportadas por outros pacotes dos quais o projeto depende. Se quiser resolve estes avisos, utilize a npm-check-updates ferramenta .
  • Na linha de comandos no diretório do projeto de raiz, execute npm i -g npm-check-updates. Esta ação instala a ferramenta globalmente.
  • Execute ncu -u. Isto fornece um relatório de todos os pacotes e de que versões serão atualizados.
  • Execute npm install para atualizar todos os pacotes.

Próximas etapas

Parabéns, você criou com êxito um suplemento do painel de tarefas do Excel! Em seguida, saiba mais sobre os recursos de um suplemento do Excel e crie um suplemento mais complexo seguindo as etapas deste tutorial de suplemento do Excel.

Exemplos de código

• Suplemento "Hello world" do Excel: saiba como criar um suplemento do Office simples com apenas um manifesto, uma página Web HTML e um logótipo.

Confira também

• Visão geral da plataforma Suplementos do Office
• Desenvolver Suplementos do Office
• Modelo de objeto JavaScript do Excel em Suplementos do Office
• Exemplos de código do suplemento do Excel
• Referência da API JavaScript do Excel
• Usando o Visual Studio Code para publicar