Crie um suplemento do Office com uma experiência básica de primeira execução

Implementar uma experiência de primeira execução ajuda os usuários integrados e destaca o valor do seu suplemento. Este tutorial ajuda você a adicionar uma experiência simples de primeira execução ao seu Suplemento do Office usando o armazenamento local para acompanhar se o usuário iniciou o suplemento anteriormente.

O que você aprenderá

• Como adicionar uma interface do usuário de primeira execução ao seu suplemento.
• Como usar o armazenamento local do navegador para manter o estado do usuário.
• Como atualizar os arquivos HTML, TypeScript ou JavaScript e CSS do seu suplemento para dar suporte à experiência de primeira execução.

Visão Geral

Quando um usuário abrir seu suplemento pela primeira vez, você exibirá uma mensagem de boas-vindas e uma lista dos principais recursos. Nas próximas inicializações, o suplemento ignorará as boas-vindas e mostrará a interface do usuário principal. Isso é feito verificando se há um sinalizador no armazenamento local e atualizando a interface do usuário adequadamente.

Este tutorial fornece instruções e capturas de tela para o Excel, mas você pode usar um padrão semelhante para implementar uma experiência de primeira execução em outros aplicativos do Office em que há suporte para os Suplementos da Web do Office.

Etapas

Siga estas etapas para implementar a experiência de primeira execução:

1. Atualize o HTML: adicione um contêiner para a experiência de primeira execução.
2. Atualize o TypeScript ou JavaScript: verifique o armazenamento local e exiba a interface do usuário de primeira execução, se necessário.
3. Atualize o CSS: verifique se a nova interface do usuário tem um estilo consistente.
4. Teste seu suplemento: verifique se a experiência de primeira execução funciona conforme o esperado.

Vamos começar!

Pré-requisitos

1. Selecione o Início rápido do Yo Office para o aplicativo do Office que você deseja usar.

   • Excel
   • OneNote
   • Outlook
   • PowerPoint
   • Project
   • Word

2. Siga as instruções no início rápido selecionado. Depois de concluir a seção "Experimente", volte aqui para continuar.

Implementar a experiência de primeira execução

Atualizar o arquivo HTML

Seja claro sobre a área da interface do usuário que fará parte da experiência de primeira execução. Neste tutorial, você criará um <div> elemento com o id nome "experiência de primeira execução" que representa o que os usuários veem apenas na primeira vez que executam o suplemento.

1. Abra a taskpane.html. Substitua o <main> elemento pela seguinte marcação e salve o arquivo. Algumas observações sobre essa marcação:

   • A "experiência de primeira execução" <div> é inserida no <main> elemento. Ele envolve a lista de recursos de Suplementos do Office. Por padrão, isso <div> não é exibido.
   • O primeiro <p> elemento fornece ao usuário instruções para usar o suplemento.

   <main id="app-body" class="ms-welcome__main" style="display: none;">
       <div id="first-run-experience" style="display: none;">
           <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
           <ul class="ms-List ms-welcome__features">
               <li class="ms-ListItem">
                   <i class="ms-Icon ms-Icon--Ribbon ms-font-xl"></i>
                   <span class="ms-font-m">Achieve more with Office integration</span>
               </li>
               <li class="ms-ListItem">
                   <i class="ms-Icon ms-Icon--Unlock ms-font-xl"></i>
                   <span class="ms-font-m">Unlock features and functionality</span>
               </li>
               <li class="ms-ListItem">
                   <i class="ms-Icon ms-Icon--Design ms-font-xl"></i>
                   <span class="ms-font-m">Create and visualize like a pro</span>
               </li>
           </ul>
       </div>
       <p class="ms-font-l">Select any range of cells in the worksheet, then click <b>Run</b>.</p>
       <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
           <span class="ms-Button-label">Run</span>
       </div>
       <p><label id="item-subject"></label></p>    
   </main>
   

2. Se você selecionou um aplicativo do Office além do Excel, atualize o primeiro <p> elemento com instruções mais apropriadas.

Atualize o arquivo TypeScript ou JavaScript

Atualize o arquivo TypeScript ou JavaScript para exibir a experiência de primeira execução se esta for a primeira vez que o usuário está executando o suplemento.

1. Se você escolheu Excel, PowerPoint ou Word com o manifesto unificado para o Microsoft 365, faça o seguinte antes de continuar. Caso o contrário, prossiga para a próxima etapa.

   1. Abra o respectivo arquivo application-name.ts na pasta ./src/taskpane. Por exemplo, se você usou o Excel, isso é ./src/taskpane/excel.ts.
   2. Renomeie a função específica do aplicativo (por exemplo, runExcel, , ou runWord) para runrunPowerPoint.
   3. Copie todo o conteúdo desse arquivo e substitua todo o conteúdo do taskpane.ts.
   4. Exclua o arquivo application-name.ts (por exemplo, excel.ts).

2. Abra o arquivo taskpane.ts ou taskpane.js . Substitua a Office.onReady instrução pelo código a seguir. Algumas observações sobre este código:

   • Ele verifica o armazenamento local em busca de uma chave chamada "showedFRE". Se a chave não existir, mostre a experiência de primeira execução.
   • Ele adiciona uma nova função chamada showFirstRunExperience que exibe a "experiência de primeira execução" <div> adicionada ao HTML. Essa função também adiciona o item "showedFRE" ao armazenamento local.

   Office.onReady((info) => {
     if (info.host === Office.HostType.Excel) {
       document.getElementById("sideload-msg").style.display = "none";
       document.getElementById("app-body").style.display = "flex";
   
       // showedFRE is created and set to "true" when you call showFirstRunExperience().
       if (!localStorage.getItem("showedFRE")) {
         showFirstRunExperience();
       }
   
       document.getElementById("run").onclick = run;
     }
   });
   
   function showFirstRunExperience() {
     document.getElementById("first-run-experience").style.display = "flex";
     localStorage.setItem("showedFRE", "true");
   }  
   

3. Se você selecionou um aplicativo do Office além do Excel, atualize a condição da primeira if instrução para marcar o Office.HostType escolhido.

4. Salve suas alterações.

Atualize o arquivo CSS

Atualize o arquivo CSS para garantir que a interface do usuário do suplemento seja estilizada adequadamente, dada a adição da "experiência de primeira execução". <div>

• Abra o arquivo taskpane.css . Substitua a linha .ms-welcome__main { pelo código a seguir e salve o arquivo.

  .ms-welcome__main, .ms-welcome__main > div {
  

Experimente

1. Verifique se o servidor Web está em execução e se o suplemento foi carregado e se abriu o painel de tarefas. Para obter detalhes, consulte as instruções no início rápido que você usou.

2. Verifique se o painel de tarefas inclui a lista de recursos.

   

3. Feche o painel de tarefas e abra-o novamente. Verifique se o painel de tarefas não exibe mais a lista de recursos.

   

Próximas etapas

Parabéns, você criou com êxito um suplemento do painel de tarefas do Office com uma experiência de primeira execução!

Prepare-o para a produção

Usando este tutorial, você implementou uma experiência básica de primeira execução. Para que a experiência de primeira execução esteja pronta para os usuários, você deve considerar o seguinte:

• Atualize os recursos listados no placemat de valor para corresponder ao que seu suplemento realmente faz.
• Implemente um padrão diferente (por exemplo, jogo americano de vídeo ou carrossel) que mostre melhor os benefícios do suplemento.
• Use uma opção mais segura e robusta para acompanhar o estado da primeira execução. Por exemplo, use o particionamento de armazenamento, se disponível, ou implemente uma solução de autenticação de logon único (SSO).
  • Para obter mais informações sobre as opções de configurações disponíveis, consulte Manter estado e configurações do suplemento.
  • Para obter mais informações sobre as opções de autenticação disponíveis, consulte Visão geral de autenticação e autorização.

Se você planeja disponibilizar seu suplemento no Microsoft Marketplace, deve ter uma experiência de primeira execução robusta e útil. Para obter mais informações, consulte Práticas recomendadas para o desenvolvimento de suplementos do Office.

Exemplos de código

• Tutorial de experiência de primeira execução concluído: o resultado da conclusão deste tutorial com o Excel.

Confira também

• Visão geral da plataforma Suplementos do Office
• Práticas recomendadas para o desenvolvimento de Suplementos do Office
• Desenvolver Suplementos do Office
• Amostras de código de suplemento do Office
• Usando o Visual Studio Code para publicar