Criar um suplemento do painel de tarefas do Excel usando o React

Artigo
08/13/2024

Neste artigo, você passará pelo processo de criar um suplemento do painel de tarefas do Excel usando o React e a API JavaScript do Excel.

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

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 using React framework
Escolha um tipo de script:TypeScript
Qual é o nome do seu suplemento?My Office Add-in
Que aplicação cliente do Office pretende suportar?Excel

A interface de linha de comandos do Gerador de Suplementos do Office Yeoman, com o tipo de projeto definido para a arquitetura react.

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

Observação

Se estiver a utilizar Node.js versão 20.0.0 ou posterior, poderá ver um aviso quando o gerador executar a instalação de que tem um motor não suportado. Estamos a trabalhar numa correção para isto. Entretanto, o aviso não afeta o gerador ou o projeto que gera, pelo que pode ser ignorado.

Dica

Você pode ignorar as orientações da próximas etapas fornecidas pelo gerador Yeoman após a criação do projeto de suplemento. As instruções passo a passo deste artigo fornecem todas as orientações necessárias para concluir este tutorial.

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 principais 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 arquivo manifest.xml no diretório raiz do projeto define as configurações e os recursos do suplemento. Para saber mais sobre o ficheiro manifest.xml , consulte Suplementos do Office com o manifesto apenas de suplemento.
O arquivo ./src/taskpane/taskpane.html define a estrutura HTML do painel de tarefas e os arquivos na pasta ./src/taskpane/components definem as diversas partes da interface do usuário 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/components/App.tsx contém o código da API JavaScript do Office que facilita a interação entre o painel de tarefas e o Excel.

Experimente

Navegue até a pasta raiz do projeto.
```
cd "My Office Add-in"
```
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.
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 o Office na Web.
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.
Selecione um intervalo de células na planilha.
Na parte inferior do painel de tarefas, escolha o link Executar para definir a cor do intervalo selecionado como amarelo.
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.

Próximas etapas

Parabéns, você criou com êxito um suplemento do painel de tarefas do Excel usando o React! 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.

Tutorial de suplemento do Excel

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.
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.
Se o suplemento mostrar um erro (por exemplo, "Não foi possível iniciar este suplemento. Feche esta caixa de diálogo para ignorar o problema ou clique em "Reiniciar" para tentar novamente.") quando prime F5 ou seleciona Depurar>Iniciar Depuração no Visual Studio, consulte Depurar Suplementos do Office no Visual Studio para obter outras opções de depuração.
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 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.

Partilhar via