Usar IU fluente React em suplementos do Office

IU do Fluent O React é a estrutura oficial de front-end JavaScript de software livre projetada para criar experiências que se encaixam perfeitamente em uma ampla variedade de produtos da Microsoft, incluindo aplicativos do Microsoft 365. Ele fornece componentes robustos, atualizados e acessíveis baseados no React que são altamente personalizáveis usando o CSS-in-JS.

Este artigo descreve como criar um suplemento criado com o React e que usa componentes do Fluent UI React.

Criar um projeto de suplemento

Você usará o gerador Yeoman para Suplementos do Office para criar um projeto de suplemento que usa o React.

Instalar os pré-requisitos

• Node.js (a versão LTS ativa mais recente). Visite o site doNode.js para baixar e instalar a versão correta para o 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 tem o Office, você pode se qualificar para uma assinatura de desenvolvedor do Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365. Para obter detalhes, consulte as Perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou adquirir um plano do Microsoft 365.

Criar o projeto

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

yo office

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

• Escolha um tipo de projeto: Especifique Office Add-in Task Pane project using React framework.
• Escolha um tipo de script: Especifique ou TypeScriptJavaScript.
• Qual será o nome do suplemento? EspecifiqueMy Office Add-in.
• Você gostaria de proporcionar suporte para qual aplicativo cliente do Office? Especifique um dos hosts. (As capturas de tela neste artigo usam Word. Executar o projeto pela primeira vez é mais fácil se você selecionar Excel, PowerPoint, ou Word. Consulte Experimente.)

Apresentamos um exemplo a seguir.

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 explorar os componentes do seu projeto de suplemento, abra o projeto no editor de código e examine os arquivos a seguir. As extensões de nome de arquivo dependem do idioma escolhido. As extensões TypeScript estão entre parênteses. Quando estiver pronto para experimentar o suplemento, prossiga para a próxima seção.

• O arquivo ./manifest.xml ou ./manifest.json no diretório raiz do projeto define as configurações e os recursos do suplemento. Para saber mais sobre o arquivo manifest.xml , confira Suplementos do Office com o manifesto apenas do suplemento. Para saber mais sobre o arquivo manifest.json , confira Suplementos do Office com o manifesto de aplicativo unificado para Microsoft 365.

• O arquivo ./src/taskpane/taskpane.html contém a marcação HTML para o painel de tarefas e carrega a Biblioteca JavaScript do Office. Ele também testa se o controle webview dá suporte à interface do usuário fluente React v9 e exibe uma mensagem especial se não for o caso.

• O arquivo ./src/taskpane/index.jsx (tsx) é o componente raiz do React. Ele carrega o React e o Fluent UI React, garante que a biblioteca JavaScript do Office foi carregada e aplica o tema definido pelo Fluent.

• O arquivo ./src/taskpane/office-document.js (ts) 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.

• A pasta ./src/taskpane/components/ contém os arquivos *.jss (tsx) do componente do React que criam a interface do usuário.

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 usar HTTPS, não HTTP, mesmo durante o desenvolvimento. Se você for solicitado a instalar um certificado depois de executar um dos comandos a seguir, aceite a solicitação para instalar o certificado fornecido pelo gerador Yeoman. Você também pode executar o prompt de comando ou terminal como administrador para que as alterações sejam feitas.

   • Se esta é a primeira vez que você desenvolve um Suplemento do Office em seu computador, você pode ser solicitado na linha de comando a conceder ao Microsoft Edge WebView uma isenção de loopback ("Permitir loopback de localhost para o Microsoft Edge WebView?"). Quando solicitado, entre Y para permitir a isenção. Observe que você precisará de privilégios de administrador para permitir a isenção. Depois de permitido, você não deve ser solicitado a fornecer uma isenção ao fazer sideload de 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 do host local" ao carregar um suplemento do Office ou usar o Fiddler.

     

   • Quando você usa o gerador Yeoman pela primeira vez para desenvolver um suplemento do Office, seu navegador padrão abre uma janela onde você será solicitado a entrar em sua conta do Microsoft 365. Se uma janela de entrada não aparecer e você encontrar um erro de sideload ou tempo limite de login, 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 seu suplemento, execute o comando a seguir no diretório raiz do seu projeto. Isso inicia o servidor Web local e abre o aplicativo host do Office com o suplemento carregado.

     npm start
     

     Observação

     Se você estiver testando seu suplemento no Outlook, faça o sideload npm start do suplemento para a área de trabalho do Outlook e para os clientes Web. Para obter mais informações sobre como fazer sideload de suplementos no Outlook, consulte Fazer sideload de suplementos do Outlook para teste.

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

     Observação

     Se você estiver desenvolvendo em um Mac, coloque entre {url} aspas simples. Não faça isso 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 suplemento não fizer sideload no documento, faça o sideload manualmente seguindo as instruções em Fazer sideload manual de suplementos para o Office na Web.

   Observação

   Se esta for a primeira vez que você faz sideload de um suplemento do Office em seu computador (ou a primeira vez em mais de um mês), você será solicitado primeiro a excluir um certificado antigo e, em seguida, a instalar um novo. Concorde com os dois prompts.

3. Um prompt Parar ao Carregar do WebView é exibido. Selecione OK.

4. Se o painel de tarefas "Meu Suplemento do Office" ainda não estiver aberto, escolha a guia Página Inicial e, em seguida, escolha o botão Mostrar Painel de Tarefas na faixa de opções para abrir o painel de tarefas do suplemento.

   Observação

   Se você estiver testando seu suplemento no Outlook, crie uma nova mensagem. Em seguida, navegue até a guia Mensagem e escolha Mostrar Painel de Tarefas na faixa de opções para abrir o painel de tarefas do suplemento.

5. Insira texto na caixa de texto e selecione Inserir texto.

   

6. Quando você estiver pronto para interromper o servidor de desenvolvimento e desinstalar o suplemento, execute o comando a seguir.

   npm stop
   

Migrar para IU do Fluent React v9

Se você tiver um suplemento existente que implemente uma versão mais antiga do Fluent UI React, recomendamos migrar para o Fluent UI v9. Para obter orientação sobre o processo de migração, consulte Introdução à migração para a v9.

Solução de problemas

• Certifique-se de que seu ambiente esteja pronto para o desenvolvimento do Office seguindo as instruções em Configurar seu ambiente de desenvolvimento.

• A etapa automática npm install que o Yo Office executa pode falhar. Se você vir erros ao tentar executar npm start, navegue até a pasta do projeto recém-criada em um prompt de comando e execute npm installmanualmente . Para obter mais informações sobre o Yo Office, consulte Criar projetos de suplemento do Office usando o Gerador Yeoman.

• Você pode ver avisos gerados ao executar npm install o gerador Yeoman ou o projeto. Na maioria dos casos, você pode ignorar esses avisos com segurança. Às vezes, as dependências se tornam preteridas e suas substituições não têm suporte em outros pacotes dos quais o projeto depende. Se você quiser resolver esses avisos, use a npm-check-updates ferramenta.

  • No prompt de comando, enquanto estiver no diretório raiz do projeto, execute npm i -g npm-check-updates. Isso instala a ferramenta globalmente.
  • Execute ncu -u. Isso fornece um relatório de todos os pacotes e para quais versões eles serão atualizados.
  • Execute npm install para atualizar todos os pacotes.

  Para obter mais informações sobre avisos durante a execução npm install, consulte Avisos e dependências no mundo Node.js e npm.

• Se você não vir o botão do suplemento na faixa de opções (por exemplo, Mostrar Painel de Tarefas), selecione o botão Suplementos na guia da faixa de opções Página Inicial e escolha o suplemento de teste.

Confira também

• Padrões de design da experiência do usuário para suplementos do Office
• IU do Fluent React
• IU do Fluent Repositório GitHub