Configurar seu Suplemento do Office para usar um runtime compartilhado

  • Artigo

Importante

O runtime compartilhado só tem suporte em alguns aplicativos do Office. Para obter mais informações, confira Conjuntos de requisitos de tempo de execução compartilhados.

Você pode configurar seu Suplemento do Office para executar todo o código em um único runtime compartilhado. Isso permite uma melhor coordenação em seu suplemento e acesso ao DOM e CORS de todas as partes de seu suplemento. Ele também ativa recursos adicionais, como a execução de código quando o documento é aberto ou a ativação ou desativação de botões da faixa de opções. Para configurar seu suplemento para usar um tempo de execução compartilhado, siga as instruções neste artigo.

Criar o projeto do suplemento

Se você estiver iniciando um novo projeto, use o Gerador Yeoman para Suplementos do Office para criar um projeto de suplemento do Excel, PowerPoint ou Word.

Execute o comando yo office --projectType taskpane --name "my office add in" --host <host> --js true, onde <host> é um dos seguintes valores.

  • excel
  • powerpoint
  • palavra

Importante

O --name de argumento deve estar entre aspas duplas, mesmo que não tenha espaços.

Você pode usar opções diferentes para as opções de linha de comando --projecttype, --name e --js. Para a lista completa de opções, veja Gerador Yeoman para Suplementos do Office.

O gerador criará o projeto e instalará os componentes do Node de suporte. Você também pode usar as etapas neste artigo para atualizar um projeto do Visual Studio para usar o tempo de execução compartilhado. No entanto, talvez seja necessário atualizar os esquemas XML para o manifesto. Para obter mais informações, confira Solucionar erros de desenvolvimento com Suplementos do Office.

Configurar o manifesto

Siga estas etapas para um projeto novo ou existente para configurá-lo para usar um tempo de execução compartilhado. Estas etapas pressupõem que você gerou seu projeto usando o Gerador Yeoman para Suplementos do Office .

  1. Inicie o Visual Studio Code e abra seu projeto de suplemento.

  2. Abra o arquivo manifest.xml.

  3. Para um suplemento do Excel ou PowerPoint, atualize a seção de requisitos para incluir o tempo de execução compartilhado. Certifique-se de remover o requisito CustomFunctionsRuntime se estiver presente. O XML deve aparecer da seguinte maneira.

    <Hosts>
  <Host Name="Workbook"/>
</Hosts>
<Requirements>
  <Sets DefaultMinVersion="1.1">
    <Set Name="SharedRuntime" MinVersion="1.1"/>
  </Sets>
</Requirements>
<DefaultSettings>

  4. Localize a <seção VersionOverrides> e adicione a seção Runtimes> a seguir<. A vida útil deve ser longa para que o código do suplemento possa ser executado mesmo quando o painel de tarefas está fechado. O residvalor é Taskpane.Url, que faz referência ao local do arquivo taskpane.html especificado na <bt:Urls>seção próxima à parte inferior do arquivo manifest.xml.

    Importante

    O runtime compartilhado não será carregado se o resid usar valores diferentes no manifesto. Se você alterar o valor para algo diferente de Taskpane.Url, também altere o valor em todos os locais mostrados nas etapas a seguir neste artigo.

    Além disso, a <seção Runtimes deve ser inserida> após o <elemento Host> na ordem exata mostrada no XML a seguir.

    <VersionOverrides ...>
  <Hosts>
    <Host ...>
      <Runtimes>
        <Runtime resid="Taskpane.Url" lifetime="long" />
      </Runtimes>
    ...
    </Host>

  5. Se você gerou um suplemento do Excel com funções personalizadas, localize o <elemento Page> . Em seguida, altere o local de origem de Functions.Page.Url para Taskpane.Url.

    <AllFormFactors>
...
<Page>
  <SourceLocation resid="Taskpane.Url"/>
</Page>
...

  6. Localize a <marca FunctionFile e altere> o resid de Commands.Url para Taskpane.Url. Observe que, se você não tiver comandos de ação, não terá uma <entrada do FunctionFile> e poderá ignorar essa etapa.

    </GetStarted>
...
<FunctionFile resid="Taskpane.Url"/>
...

  7. Salve o arquivo manifest.xml.

Configurar o arquivo webpack.config.js

O webpack.config.js construirá vários carregadores de tempo de execução. Você precisa modificá-lo para carregar apenas o runtime compartilhado por meio do arquivo taskpane.html .

  1. Inicie Visual Studio Code e abra o projeto de suplemento gerado.

  2. Abra o arquivo webpack.config.js.

  3. Se o arquivo webpack.config.js tiver o seguinte código de plug-in functions.html, remova-o.

    new HtmlWebpackPlugin({
    filename: "functions.html",
    template: "./src/functions/functions.html",
    chunks: ["polyfill", "functions"]
  })

  4. Se o seu arquivo webpack.config.js tiver o seguinte código de plug-in functions.html, remova-o.

    new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"]
  })

  5. Se o seu projeto usou as functions ou os blocos de commands, adicione-os à lista de blocos conforme mostrado a seguir (o código a seguir é para se o seu projeto usou os dois blocos).

      new HtmlWebpackPlugin({
    filename: "taskpane.html",
    template: "./src/taskpane/taskpane.html",
    chunks: ["polyfill", "taskpane", "commands", "functions"]
  })

  6. Salvar suas alterações e reconstrua o projeto.

    npm run build

Observação

Se o seu projeto tiver um arquivo functions.html ou um arquivo commands.html, eles podem ser removidos. O taskpane.html carregará o códigofunctions.js e commands.js no runtime compartilhado por meio das atualizações do webpack que você acabou de fazer.

Teste as alterações do Suplemento do Office

Você pode confirmar que está usando o runtime compartilhado corretamente usando as instruções a seguir.

  1. Abra o arquivo taskpane.js.

  2. Substitua todo o conteúdo do arquivo pelo código a seguir. Isso exibirá uma contagem de quantas vezes o painel de tarefas foi aberto. A adição do evento onVisibilityModeChanged só tem suporte em um runtime compartilhado.

    /*global document, Office*/

let _count = 0;

Office.onReady(() => {
  document.getElementById("sideload-msg").style.display = "none";
  document.getElementById("app-body").style.display = "flex";

  updateCount(); // Update count on first open.
  Office.addin.onVisibilityModeChanged(function (args) {
    if (args.visibilityMode === "Taskpane") {
      updateCount(); // Update count on subsequent opens.
    }
  });
});

function updateCount() {
  _count++;
  document.getElementById("run").textContent = "Task pane opened " + _count + " times.";
}

  3. Salve suas alterações e execute o projeto.

    npm start

Cada vez que você abre o painel de tarefas, a contagem de quantas vezes ele foi aberto será incrementada. O valor de _count não será perdido porque o tempo de execução compartilhado mantém seu código em execução mesmo quando o painel de tarefas é fechado.

Duração do tempo de execução

Ao adicionar o <elemento Runtime> , você também especifica um tempo de vida com um valor de long ou short. Defina esse valor como long para aproveitar os recursos, como iniciar o suplemento quando o documento for aberto, continuar executando o código após o fechamento do painel de tarefas ou usar o CORS e o DOM nas funções personalizadas.

Observação

O valor de vida útil padrão é short, mas recomendamos usar long em suplementos do Excel, PowerPoint e Word. Se você definir seu tempo de execução como short neste exemplo, seu suplemento será iniciado quando um dos botões da faixa de opções for pressionado, mas poderá ser encerrado após a execução do manipulador de faixa de opções. Da mesma forma, o suplemento será iniciado quando o painel de tarefas for aberto, mas pode ser encerrado quando o painel de tarefas for fechado.

<Runtimes>
  <Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>

Observação

Se o suplemento incluir o <elemento Runtimes> no manifesto (necessário para um runtime compartilhado) e as condições para usar o WebView2 (baseado em Chromium do Microsoft Edge) forem atendidas, ele usará esse controle. Se as condições não forem atendidas, ele usará o controle webview Trident (Internet Explorer 11), independentemente da versão do Windows ou do Microsoft 365. Para obter mais informações, consulte Runtimes e Browsers e controles webview usados pelos Suplementos do Office.

Sobre o runtime compartilhado

No Windows ou no Mac, o suplemento executará o código para botões de faixa de opções, funções personalizadas e o painel de tarefas em ambientes de runtime separados. Isso cria limitações, como não poder compartilhar facilmente dados globais e não poder acessar todas as funcionalidades do CORS a partir de uma função customizada.

No entanto, você pode configurar seu Suplemento do Office para compartilhar código no mesmo runtime (também chamado de runtime compartilhado). Isso permite uma melhor coordenação entre o suplemento e o acesso ao DOM e CORS do painel de tarefas de todas as partes do suplemento.

Configurar um tempo de execução compartilhado permite os seguintes cenários.

Para o Office no Windows, o runtime compartilhado usará o WebView2 (baseado em Chromium do Microsoft Edge) se as condições para usá-lo forem atendidas conforme explicado em Navegadores e controles webview usados pelos Suplementos do Office. Caso contrário, ele usa Trident (Internet Explorer 11). Além disso, todos os botões que seu suplemento exibir na faixa de opções serão executados no mesmo tempo de execução compartilhado. A imagem a seguir mostra como as funções personalizadas, a interface do usuário da faixa de opções e o código do painel de tarefas serão executadas no mesmo runtime.

Diagrama de uma função personalizada, painel de tarefas e botões da faixa de opções em execução em um tempo de execução de navegador compartilhado no Excel.

Depurar

Ao usar um tempo de execução compartilhado, não é possível usar o Código do Visual Studio para depurar funções personalizadas no Excel no Windows no momento. Em vez disso, você precisará usar as ferramentas de desenvolvedor. Para obter mais informações, consulte Depurar suplementos usando ferramentas de desenvolvedor para Internet Explorer ou Depurar suplementos usando ferramentas de desenvolvedor no Microsoft Edge (baseado em Chromium).

Vários painéis de tarefas

Não projete seu suplemento para usar vários painéis de tarefas se você planeja usar um tempo de execução compartilhado. Um tempo de execução compartilhado tem suporte para o uso de apenas um único painel de tarefas. Observe que qualquer painel de tarefas sem um <TaskpaneID> é considerado um painel de tarefas diferente.

Confira também