Compartilhar via

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

Implementar uma experiência de primeira execução ajuda a integrar utilizadores e realça o valor do suplemento. Este tutorial orienta-o ao longo da adição de uma experiência de primeira execução simples ao seu Suplemento do Office através do armazenamento local para controlar se o utilizador iniciou o suplemento anteriormente.

Observação

A experiência de primeira execução é um padrão recomendado para Suplementos do Office. Ajuda os utilizadores a compreender as funcionalidades do seu suplemento e aumenta o envolvimento.

O que irá aprender

  • Como adicionar uma IU de primeira execução ao seu suplemento.
  • Como utilizar o armazenamento local do browser para manter o estado do utilizador.
  • Como atualizar os ficheiros HTML, JavaScript e CSS do suplemento para suportar a experiência de primeira execução.

Visão Geral

Quando um utilizador abre o seu suplemento pela primeira vez, irá apresentar uma mensagem de boas-vindas e uma lista das principais funcionalidades. Nos lançamentos subsequentes, o suplemento irá ignorar as boas-vindas e mostrar a IU principal. Isto é conseguido ao verificar a existência de um sinalizador no armazenamento local e atualizar a IU em conformidade.

Este tutorial fornece instruções e capturas de ecrã para o Excel, mas pode utilizar um padrão semelhante para implementar uma experiência de primeira execução noutras aplicações do Office em que os Suplementos Web do Office são suportados.

Etapas

Siga estes passos para implementar a experiência de primeira execução:

  1. Atualize o HTML: adicione um contentor para a experiência de primeira execução.
  2. Atualize o JavaScript: verifique o armazenamento local e apresente a IU de primeira execução, se necessário.
  3. Atualizar o CSS: certifique-se de que a nova IU tem um estilo consistente.
  4. Testar o suplemento: verifique se a experiência de primeira execução funciona conforme esperado.

Vamos começar!

Dica

Se quiser uma versão completa deste tutorial, visite o repositório de exemplos de Suplementos do Office no GitHub.

Pré-requisitos

  1. Selecione o guia de introdução do Yo Office para a aplicação do Office que pretende utilizar.

  2. Siga as instruções no guia de introdução selecionado. Depois de concluir a secção "Experimentar", regresse aqui para continuar.

Implementar a experiência de primeira execução

Atualizar o ficheiro HTML

Seja claro sobre a área da IU que fará parte da experiência de primeira execução. Neste tutorial, irá criar um <div> elemento com o id nome "first-run-experience" que representa o que os utilizadores veem apenas na primeira vez que executarem o seu suplemento.

  1. Abra o taskpane.html. Substitua o <main> elemento pela seguinte marcação e, em seguida, guarde o ficheiro. Algumas notas sobre esta marcação:

    • A "experiência de primeira execução" <div> é inserida no <main> elemento . Rodeia a lista de funcionalidades de Suplementos do Office. Por predefinição, isto <div> não é apresentado.
    • O primeiro <p> elemento fornece ao utilizador instruções para utilizar 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 selecionou uma aplicação do Office para além do Excel, atualize o primeiro <p> elemento com instruções mais adequadas.

Atualizar o ficheiro JavaScript

Atualize o ficheiro JavaScript para apresentar a experiência de primeira execução se esta for a primeira vez que o utilizador está a executar o suplemento.

  1. Abra o arquivo taskpane.js. Substitua a Office.onReady instrução pelo seguinte código e, em seguida, guarde o ficheiro. Algumas notas sobre este código:

    • Verifica a existência de uma chave denominada "showedFRE" no armazenamento local. Se a chave não existir, mostre a experiência de primeira execução.
    • Adiciona uma nova função chamada showFirstRunExperience que apresenta a "primeira experiência de execução" <div> adicionada ao HTML. Esta 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;
  }
});

async function showFirstRunExperience() {
  document.getElementById("first-run-experience").style.display = "flex";
  localStorage.setItem("showedFRE", true);
}

  2. Se tiver selecionado uma aplicação do Office para além do Excel, atualize a condição da primeira if instrução para marcar para o Office.HostType escolhido.

Atualizar o ficheiro CSS

Atualize o ficheiro CSS para garantir que a IU do suplemento é modelada adequadamente dada a adição da "experiência de primeira execução" <div>.

  • Abra o ficheiro taskpane.css . Substitua a linha .ms-welcome__main { pelo seguinte código e, em seguida, guarde o ficheiro.

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

Experimente

  1. Certifique-se de que o servidor Web está em execução e que o suplemento foi sideloaded e, em seguida, abra o painel de tarefas. Para obter detalhes, veja as instruções no guia de introdução que utilizou.

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

    IU do painel de tarefas do suplemento na primeira execução.

  3. Feche o painel de tarefas e volte a abri-lo. Verifique se o painel de tarefas já não apresenta a lista de funcionalidades.

    IU do painel de tarefas do suplemento na segunda execução.

Próximas etapas

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

Preparar a produção

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

  • Atualize as funcionalidades listadas no placemat de valor para corresponder ao que o seu suplemento realmente faz.
  • Implemente um padrão diferente (por exemplo, placemat de vídeo ou carrossel) que melhor mostre os benefícios do seu suplemento.
  • Utilize uma opção mais segura e robusta para controlar o estado de primeira execução. Por exemplo, utilize a criação de partições de armazenamento, se disponível, ou implemente uma solução de autenticação de Início de Sessão Único (SSO).

Se estiver a planear disponibilizar o seu suplemento no Microsoft Marketplace, tem de ter uma experiência de primeira execução robusta e útil. Para obter mais informações, consulte Melhores práticas para desenvolver Suplementos do Office.

Exemplos de código

Confira também

  • Last updated on