Runtimes em Suplementos do Office

Os suplementos do Office são executados em runtimes inseridos no Office. Como uma linguagem interpretada, o JavaScript deve ser executado em um runtime JavaScript. NavegadoresNode.js e modernos são exemplos desses tempos de execução.

Tipos de runtimes

Há dois tipos de runtimes usados pelos Suplementos do Office:

• Runtime somente JavaScript: um mecanismo JavaScript complementado com suporte para WebSockets, CORS completo (compartilhamento de recursos entre origens) e armazenamento de dados do lado do cliente. Ele não dá suporte a armazenamento local ou cookies.
• Runtime do navegador: inclui todos os recursos de um runtime somente JavaScript e adiciona suporte para armazenamento local, um mecanismo de renderização que renderiza HTML e cookies.

Os detalhes sobre esses tipos são mais adiante neste artigo em Runtime somente JavaScript e Runtime do navegador.

A tabela a seguir mostra os possíveis recursos de um suplemento, de acordo com cada tipo de runtime.

A tabela a seguir mostra as mesmas informações organizadas pelo tipo de tempo de execução usado para os vários recursos possíveis de um suplemento.

No Office na Web, tudo sempre é executado em um tempo de execução do tipo navegador. Com uma exceção, tudo em um suplemento na Web é executado no mesmo processo do navegador: o processo do navegador no qual o usuário abriu o Office na Web. A exceção é quando uma caixa de diálogo é aberta com uma chamada de Office.ui.displayDialogAsync e a opção DialogOptions.displayInIFramenão é passada e definida como true. Quando a opção não é passada (portanto, ela tem o valor padrão false ), a caixa de diálogo é aberta em seu próprio processo. O mesmo princípio se aplica ao método OfficeRuntime.displayWebDialog e à opção OfficeRuntime.DisplayWebDialogOptions.displayInIFrame .

Quando um suplemento está sendo executado em uma plataforma diferente da Web, os seguintes princípios se aplicam.

• Uma caixa de diálogo é executada em seu próprio processo de tempo de execução.

• Um suplemento do Outlook baseado em eventos ou em relatórios de spam é executado em seu próprio processo de tempo de execução.

  Observação

  A ativação baseada em eventos e os recursos integrados de relatórios de spam no Outlook devem usar o mesmo tempo de execução. Atualmente, não há suporte para vários tempos de execução no Outlook.

• Por padrão, painéis de tarefas, comandos de função e funções personalizadas do Excel são executados em seu próprio processo de tempo de execução. No entanto, para alguns aplicativos host do Office, o manifesto do suplemento pode ser configurado para que quaisquer dois, ou todos os três, possam ser executados no mesmo tempo de execução. Consulte Tempo de execução compartilhado.

Dependendo do aplicativo host do Office e dos recursos usados no suplemento, pode haver muitos tempos de execução em um suplemento. Cada um geralmente será executado em seu próprio processo, mas não necessariamente simultaneamente. Eis alguns exemplos.

• Um suplemento do PowerPoint ou do Word que não compartilha runtimes e inclui os recursos a seguir tem até três runtimes.

  • Um painel de tarefas

  • Um comando de função

  • Uma caixa de diálogo (Uma caixa de diálogo pode ser iniciada a partir do painel de tarefas ou do comando de função.)

    Observação

    Não é recomendável ter várias caixas de diálogo abertas simultaneamente, mas se o suplemento permitir que o usuário abra uma no painel de tarefas e outra no comando da função ao mesmo tempo, esse suplemento terá quatro tempos de execução. Um painel de tarefas e uma determinada invocação de um comando de função podem ter apenas uma caixa de diálogo aberta por vez; Mas se o comando de função for invocado várias vezes, uma nova caixa de diálogo será aberta sobre seu antecessor a cada invocação, portanto, pode haver muitos tempos de execução. O restante desta lista ignora a possibilidade de várias caixas de diálogo abertas.

• Um suplemento do Excel que não compartilha nenhum runtime e inclui os recursos a seguir tem até quatro runtimes.

  • Um painel de tarefas
  • Um comando de função
  • Uma função personalizada
  • Uma caixa de diálogo (Uma caixa de diálogo pode ser iniciada a partir do painel de tarefas, do comando de função ou de uma função personalizada.)

• Um suplemento do Excel com os mesmos recursos e configurado para compartilhar o mesmo tempo de execução no painel de tarefas, comando de função e função personalizada, tem dois tempos de execução. Um runtime compartilhado pode abrir apenas uma caixa de diálogo por vez.

• Um suplemento do Excel com os mesmos recursos, exceto que não tem caixa de diálogo e está configurado para compartilhar o mesmo tempo de execução no painel de tarefas, comando de função e função personalizada, tem um tempo de execução.

• Um suplemento do Outlook com os recursos a seguir tem até quatro tempos de execução. Não há suporte para tempos de execução compartilhados no Outlook.

  • Um painel de tarefas
  • Um comando de função
  • Uma tarefa baseada em eventos ou um recurso integrado de denúncia de spam
  • Uma caixa de diálogo (Uma caixa de diálogo pode ser iniciada a partir do painel de tarefas ou do comando de função, mas não a partir de uma tarefa baseada em evento.)

Compartilhar dados entre runtimes

Para suplementos do Excel, PowerPoint e Word, use um runtime compartilhado quando dois ou mais recursos, exceto caixas de diálogo, precisarem compartilhar dados. No Outlook ou em cenários em que o compartilhamento de um runtime não é viável, você precisará de métodos alternativos. As partes do suplemento que estão em processos de tempo de execução separados não compartilham dados globais automaticamente e são tratadas pelo servidor de aplicativos Web do suplemento como sessões separadas, portanto, Window.sessionStorage não pode ser usado para compartilhar dados entre elas. As diretrizes a seguir pressupõem que você não esteja usando um runtime compartilhado.

• Transmita dados entre uma caixa de diálogo e seu painel de tarefas pai, comando de função ou função personalizada usando os métodos Office.ui.messageParent e Dialog.messageChild .

  Observação

  Os OfficeRuntime.storage métodos não podem ser chamados em uma caixa de diálogo, portanto, essa não é uma opção para compartilhar dados entre uma caixa de diálogo e outro tempo de execução.

• Para compartilhar dados entre um painel de tarefas e um comando de função, armazene dados em Window.localStorage, que é compartilhado em todos os runtimes que acessam a mesma origem específica.

  Observação

  LocalStorage não está acessível em um runtime somente JavaScript e, portanto, não está disponível em funções personalizadas do Excel. Ele também não pode ser usado para compartilhar dados com tarefas baseadas em eventos do Outlook (já que essas tarefas usam um tempo de execução somente JavaScript em algumas plataformas).

  A partir da versão 115 dos navegadores baseados no Chromium, como Chrome e Edge, o particionamento de armazenamento é habilitado para impedir o rastreamento específico entre sites de canal lateral (consulte também as políticas do navegador Microsoft Edge). Isso significa que os dados armazenados por APIs de armazenamento, como armazenamento local, estão disponíveis apenas em contextos com a mesma origem e o mesmo site de nível superior.

  Dica

  A entrada Window.localStorage de dados persiste entre as sessões do suplemento e é compartilhada por suplementos com a mesma origem. Ambas as características geralmente são indesejáveis para um suplemento.

  • Para garantir que cada sessão de um determinado suplemento comece do zero, chame o método Window.localStorage.clear quando o suplemento for iniciado.
  • Para permitir que alguns valores armazenados persistam, mas reinicializar outros valores, use Window.localStorage.setItem quando o suplemento for iniciado para cada item que deve ser redefinido para um valor inicial.
  • Para excluir totalmente um item, chame Window.localStorage.removeItem.

• Para compartilhar dados entre uma função personalizada do Excel e qualquer outro runtime, use OfficeRuntime.storage.

• Para compartilhar dados entre uma tarefa baseada em eventos do Outlook e um painel de tarefas ou comando de função, você deve ramificar seu código pelo valor da propriedade Office.context.platform .

  • Quando o valor for PC (Windows), armazene e recupere dados usando as APIs Office.sessionData .
  • Quando o valor for Mac, use Window.localStorage conforme descrito anteriormente nesta lista.

Outras maneiras de compartilhar dados incluem o seguinte:

• Armazene dados compartilhados em um banco de dados online acessível a todos os tempos de execução.
• Armazene dados compartilhados em um cookie para o domínio do suplemento para compartilhá-los entre os runtimes do navegador. Runtimes somente JavaScript não dão suporte a cookies.

Para obter mais informações, consulte Persistir estado e configurações do suplemento e Obter e definir metadados de suplemento para um suplemento do Outlook.

Runtime somente JavaScript

O runtime somente JavaScript usado nos Suplementos do Office é uma modificação de um runtime de código aberto originalmente criado para o React Native. Ele contém um mecanismo JavaScript complementado com suporte para WebSockets, CORS completo (compartilhamento de recursos entre origens) e OfficeRuntime.storage. Ele não tem um mecanismo de renderização e não dá suporte a cookies ou armazenamento local.

Esse tipo de tempo de execução é usado em suplementos baseados em eventos e de relatórios de spam no Outlook clássico somente no Windows e em funções personalizadas do Excel, exceto quando as funções personalizadas estão compartilhando um tempo de execução.

• Quando usado para uma função personalizada do Excel, o runtime é iniciado quando a planilha é recalculada ou a função personalizada calcula. Ele não é desligado até que a pasta de trabalho seja fechada.

• Quando usado em um suplemento do Outlook baseado em eventos ou de geração de relatórios de spam, o runtime é iniciado quando o evento ocorre. Ele termina quando ocorre o primeiro dos seguintes.

  • O manipulador de eventos chama o completed método de seu parâmetro event.
  • Cinco minutos se passaram desde o evento desencadeador.
  • O usuário muda o foco da janela em que o evento foi disparado, como uma janela de redação de mensagem (aplicável somente a suplementos baseados em evento).

  Observação

  A ativação baseada em eventos e os recursos integrados de relatórios de spam no Outlook devem usar o mesmo tempo de execução. Atualmente, não há suporte para vários tempos de execução no Outlook.

Um runtime somente JavaScript usa menos memória e inicia mais rapidamente do que um runtime de navegador, mas tem menos recursos.

Runtime do navegador

Os suplementos do Office usam um tipo de tempo de execução de navegador diferente dependendo da plataforma na qual o Office está sendo executado (Web, Mac ou Windows) e da versão e do build do Windows e do Office. Por exemplo, se o usuário estiver executando o Office na Web em um navegador FireFox, o tempo de execução do Firefox será usado. Se o usuário estiver executando o Office no Mac, o runtime do Safari será usado. Se o usuário estiver executando o Office no Windows, um Edge ou o Internet Explorer fornecerá o tempo de execução, dependendo da versão do Windows e do Office. Os detalhes podem ser encontrados nos navegadores e controles de modo de exibição da Web usados pelos Suplementos do Office.

Todos esses tempos de execução incluem um mecanismo de renderização HTML e fornecem suporte para WebSockets, CORS completo (compartilhamento de recursos entre origens),armazenamento local e cookies.

A vida útil do tempo de execução de um navegador varia dependendo do recurso que ele implementa e se ele está sendo compartilhado ou não.

• Quando um suplemento com um painel de tarefas é iniciado, um runtime do navegador é iniciado, a menos que seja um runtime compartilhado que já esteja em execução. Se for um tempo de execução compartilhado, ele será desligado quando o documento for fechado. Se não for um runtime compartilhado, ele será desligado quando o painel de tarefas for fechado.

• Quando uma caixa de diálogo é aberta, um runtime de navegador é iniciado. Ele é desligado quando a caixa de diálogo é fechada.

• Quando um comando de função é executado (o que acontece quando um usuário seleciona seu botão ou item de menu), um runtime do navegador é iniciado, a menos que seja um runtime compartilhado que já está em execução. Se for um tempo de execução compartilhado, ele será desligado quando o documento for fechado. Se não for um runtime compartilhado, ele será desligado quando ocorrer o primeiro dos seguintes.

  • O comando function chama o completed método de seu parâmetro event.
  • Cinco minutos se passaram desde o evento desencadeador. (Se uma caixa de diálogo foi aberta no comando de função e ela ainda está aberta quando o tempo de execução pai atinge o tempo limite, o tempo de execução da caixa de diálogo permanece em execução até que a caixa de diálogo seja fechada.)

• Quando uma função personalizada do Excel está usando um runtime compartilhado, um runtime do tipo navegador é iniciado quando a função personalizada calcula se o runtime compartilhado ainda não foi iniciado por algum outro motivo. Ele é desligado quando o documento é fechado.

Um tempo de execução do navegador tem mais recursos do que um tempo de execução somente JavaScript, mas inicia mais lentamente e usa mais memória.

Tempo de execução compartilhado

Um "tempo de execução compartilhado" não é um tipo de tempo de execução. Ele se refere a um tempo de execução do tipo navegador que está sendo compartilhado por recursos do suplemento que, caso contrário, cada um teria seu próprio tempo de execução. Especificamente, você tem a opção de configurar o painel de tarefas do suplemento e os comandos de função para compartilhar um tempo de execução. Em um suplemento do Excel, você também pode configurar funções personalizadas para compartilhar o tempo de execução de um painel de tarefas ou comando de função ou ambos. Quando você faz isso, as funções personalizadas estão sendo executadas em um tempo de execução do tipo navegador, em vez de um tempo de execução somente JavaScript , como faria de outra forma. Consulte Configurar seu suplemento para usar um runtime compartilhado para obter informações sobre os benefícios e limitações do compartilhamento de runtimes e instruções para configurar o suplemento para usar um runtime compartilhado. Em resumo, o tempo de execução somente JavaScript usa menos memória e inicia mais rapidamente, mas tem menos recursos.