Usar React de interface do usuário fluente em suplementos do Office
A interface do usuário fluente React é a estrutura de front-end do JavaScript de código aberto oficial projetada para criar experiências que se encaixam perfeitamente em uma ampla gama de produtos da Microsoft, incluindo aplicativos Microsoft 365. Ele fornece componentes robustos, atualizados e acessíveis baseados no React que são altamente personalizáveis usando o CSS-in-JS.
Observação
Este artigo descreve o uso de React de interface do usuário fluente no contexto de suplementos do Office. No entanto, ele também é usado em uma ampla gama de aplicativos e extensões do Microsoft 365. Para obter mais informações, confira React de interface do usuário fluente e o repositório código aberto web da interface do usuário fluente.
Este artigo descreve como criar um suplemento criado com React e que usa componentes da interface do usuário fluente React.
Criar um projeto de suplemento
Você usará o gerador Yeoman para suplementos do Office para criar um projeto de suplemento que usa React.
Observação
Os suplementos baseados em React criados com o gerador usam a interface do usuário fluente React V9. Essa versão não dá suporte à visão web do Trident (IE). Se os usuários do suplemento tiverem versões do Office que exigem Trident, use um dos exemplos no Office-Add-ins-Fluent-React-version-8 em vez deste artigo. Para obter informações sobre quais versões do Office usam o Trident, consulte Navegadores e controles de visão da Web usados pelos Suplementos do Office.
Instalar os pré-requisitos
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.
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
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: Especifique
Office Add-in Task Pane project using React framework
. - Escolha um tipo de script: Especifique ou
TypeScript
JavaScript
. - Qual será o nome do suplemento? Especifique
My 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ê selecionarExcel
,PowerPoint
ouWord
. Confira Experimentar.)
Apresentamos um exemplo a seguir.
Depois que você concluir o assistente, o gerador criará o projeto e instalará os componentes Node de suporte.
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.
Observação
A interface do usuário fluente React v9 ou posterior não tem suporte com os controles de visão web do Trident (IE) ou edgeHTML (Edge Legacy). Se sua versão do Office estiver usando um deles, o painel de tarefas do suplemento gerado pelo Yo Office simplesmente contém uma mensagem para atualizar sua versão do Office. Para obter mais informações, consulte Navegadores e controles de visão da Web usados pelos Suplementos do Office.
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 do arquivo dependem de qual idioma você escolher. As extensões TypeScript estão em parênteses. 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 arquivo manifest.xml arquivo, consulte manifesto XML de suplementos do Office.
- 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 o fizer.
- O arquivo ./src/taskpane/index.jsx (tsx) é o componente raiz React. Ele carrega React e React de interface do usuário fluente, garante que a biblioteca JavaScript do Office tenha sido carregada e aplique o tema definido por Fluente.
- 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 do componente React *.jss (tsx) que criam a interface do usuário.
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 usar HTTPS, não HTTP, mesmo enquanto você estiver desenvolvendo. Se você for solicitado a instalar um certificado depois de executar um dos comandos a seguir, aceite o prompt 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 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 seu suplemento carregado.
npm start
Observação
Se você estiver testando seu suplemento no Outlook,
npm start
carregará o suplemento para os clientes da área de trabalho e da Web do Outlook. Para obter mais informações sobre como carregar suplementos de sideload no Outlook, confira Suplementos do Sideload outlook para teste.Para testar seu suplemento no Excel, Word ou PowerPoint na Web, execute o seguinte comando 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, inclua as
{url}
aspas em um único. 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 carregar de lado no documento, o carregará manualmente seguindo as instruções em suplementos de sideload manualmente para Office na Web.
Observação
Se essa for a primeira vez que você carrega um suplemento do Office em seu computador (ou pela primeira vez em mais de um mês), você será solicitado primeiro a excluir um certificado antigo e, em seguida, instalar um novo. Concorde com ambos os prompts.
Um prompt de interrupção de carregamento do WebView é exibido. Selecione OK.
Se o painel de tarefas "Meu Suplemento do Office" ainda não estiver aberto, escolha a guia Página Inicial e escolha o botão Mostrar Painel de Tarefas na faixa de opções para abrir o painel de tarefas de 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 Taskpane na faixa de opções para abrir o painel de tarefas de suplemento.
Insira texto na caixa de texto e selecione Inserir texto.
Migrar para a interface do usuário fluente React v9
Se você tiver um suplemento existente que implemente uma versão mais antiga da interface do usuário fluente React, recomendamos migrar para a interface do usuário fluente v9. Para obter diretrizes sobre o processo de migração, consulte Introdução à migração para v9.
Solução de problemas
Verifique se o ambiente está 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 executarnpm start
, navegue até a pasta de projeto recém-criada em um prompt de comando e executenpm install
manualmente . Para obter mais informações sobre o Yo Office, consulte Criar projetos de suplemento do Office usando o Gerador yeoman.Se o suplemento mostrar um erro (por exemplo, "Esse suplemento não pôde ser iniciado. Feche essa caixa de diálogo para ignorar o problema ou clique em "Reiniciar" para tentar novamente.") ao pressionar F5 ou escolher Depurar>Iniciar Depuração no Visual Studio, consulte Depurar suplementos do Office no Visual Studio para outras opções de depuração.
Alguns dos códigos de exemplo usam JavaScript ES6. Isso não é compatível com versões mais antigas do Office que usam o mecanismo do navegador Trident (Internet Explorer 11). Para obter informações sobre como dar suporte a essas plataformas em seu suplemento, consulte Suporte a versões mais antigas da Microsoft webviews e office. Se você ainda não tiver uma assinatura do Microsoft 365 a ser usada para desenvolvimento, 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.
Confira também
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de