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

Artigo
10/16/2024

Neste artigo, irá percorrer o processo de atualização de um suplemento do painel de tarefas para incluir uma experiência de primeira execução com o padrão placemat de valor. Quando o utilizador executa o suplemento, o suplemento determina se pretende ou não mostrar a experiência de primeira execução ao verificar se existe um sinalizador no armazenamento local .

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.

Dica

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

Pré-requisitos

Selecione o guia de introdução do Yo Office para a aplicação do Office que pretende utilizar.
- Excel
- OneNote
- Outlook
- PowerPoint
- Project
- Word
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.

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>

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.

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);
}

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

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.
Verifique se o painel de tarefas inclui a lista de funcionalidades.
Feche o painel de tarefas e volte a abri-lo. Verifique se o painel de tarefas já não apresenta a lista de funcionalidades.

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). Para obter mais informações sobre as opções de definições disponíveis, consulte Manter o estado e as definições do suplemento. Para obter mais informações sobre as opções de autenticação disponíveis, veja Descrição geral da autenticação e autorização.

Se estiver a planear disponibilizar o suplemento no marketplace do AppSource, terá 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

Tutorial completo da experiência de primeira execução: o resultado da conclusão deste tutorial com o Excel.

Compartilhar via