Configurar o seu Suplemento do Office para utilizar um runtime partilhado

Importante

O runtime partilhado só é suportado em algumas aplicações do Office. Para obter mais informações, confira Conjuntos de requisitos de tempo de execução compartilhados.

Pode configurar o seu Suplemento do Office para executar todo o respetivo código num único runtime partilhado. 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 <secção VersionOverrides> e adicione a secção Runtimes> seguinte<. 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 partilhado não será carregado se o resid utilizar valores diferentes no manifesto. Se alterar o valor para algo diferente de Taskpane.Url, certifique-se de que também altera o valor em todas as localizações apresentadas nos seguintes passos neste artigo.

   Além disso, a <secção Runtimes> tem de ser introduzida após o <elemento Anfitrião> pela ordem exata apresentada no XML seguinte.

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

5. Se tiver gerado um suplemento do Excel com funções personalizadas, localize o <elemento Página> . Em seguida, altere o local de origem de Functions.Page.Url para Taskpane.Url.

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

6. Localize a <etiqueta FunctionFile e altere> a resid de Commands.Url para Taskpane.Url. Tenha em atenção que, se não tiver comandos de ação, não terá uma <entrada FunctionFile> e poderá ignorar este passo.

   </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. Tem de modificá-lo para carregar apenas o runtime partilhado através do ficheiro 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 irá carregar o códigofunctions.js e commands.js para o runtime partilhado através das atualizações de webpack que acabou de efetuar.

Teste as alterações do Suplemento do Office

Pode confirmar que está a utilizar corretamente o runtime partilhado com as seguintes instruções.

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ó é suportada num runtime partilhado.

   /*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.

Quando estiver pronto para parar o servidor dev e desinstalar o suplemento, execute o seguinte comando.

npm stop

Duração do tempo de execução

Quando adiciona o <elemento Runtime> , também especifica uma duração 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 partilhado) e as condições para utilizar o WebView2 (microsoft Edge baseado em Chromium) forem cumpridas, utiliza esse controlo. Se as condições não forem cumpridas, utiliza o controlo de webview Trident (Internet Explorer 11), independentemente da versão do Windows ou do Microsoft 365. Para obter mais informações, veja Runtimes and Browsers and webview controls used by Office Add-ins (Runtimes e Browsers e controlos webview utilizados pelos Suplementos do Office).

Acerca do runtime partilhado

No Windows ou no Mac, o seu suplemento irá executar código para botões do friso, 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, pode configurar o seu Suplemento do Office para partilhar código no mesmo runtime (também conhecido como runtime partilhado). 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.

• Seu Suplemento do Office pode usar recursos de UI adicionais.
  • Ativar e Desativar Comandos de Suplemento
  • Execute o código em seu Suplemento do Office quando o documento for aberto
  • Mostre ou oculte o painel de tarefas de seu Suplemento do Office
• Os seguintes itens estão disponíveis somente para suplementos do Excel.
  • Adicionar atalhos de teclado personalizados aos seus Suplementos do Office
  • Criar separadores contextuais personalizados nos Suplementos do Office
  • As funções personalizadas terão suporte CORS completo.
  • Funções personalizadas podem chamar APIs Office.js para ler dados de documentos de planilhas.

Para o Office no Windows, o runtime partilhado utiliza o WebView2 (microsoft Edge baseado em Chromium) se as condições para utilizá-lo forem cumpridas conforme explicado em Browsers e controlos webview utilizados pelos Suplementos do Office. Caso contrário, utiliza 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 seguinte mostra como as funções personalizadas, a IU do friso e o código do painel de tarefas serão executados no mesmo runtime.

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

• Chamar APIs do Excel a partir de uma função personalizada
• Adicionar atalhos de teclado personalizados aos seus Suplementos do Office
• Criar separadores contextuais personalizados nos Suplementos do Office
• Ativar e Desativar Comandos de Suplemento
• Execute o código em seu Suplemento do Office quando o documento for aberto
• Mostre ou oculte o painel de tarefas de seu Suplemento do Office
• Tutorial: compartilhar dados e eventos entre as funções personalizadas do Excel e do painel de tarefas
• Runtimes nos Suplementos do Office