Runtimes em suplementos do Office

  • Artigo

Os suplementos do Office são executados em runtimes inseridos no Office. Como um idioma interpretado, o JavaScript deve ser executado em um runtime javaScript. Node.js e navegadores modernos são exemplos desses runtimes.

Tipos de runtimes

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

Os detalhes sobre esses tipos são posteriores neste artigo no runtime somente JavaScript e no runtime do Navegador.

A tabela a seguir mostra quais recursos possíveis de um suplemento usam cada tipo de runtime.

Tipo de runtime Recurso de suplemento
Somente JavaScript Funções personalizadas
do Excel(exceto quando o runtime é compartilhado ou o suplemento está em execução em Office na Web)

Tarefa
baseada em eventos do Outlook(somente quando o suplemento está sendo executado no Outlook no Windows)

Recurso de relatório de spam integrado do Outlook (versão prévia)
(somente quando o suplemento está em execução no Outlook no Windows)
Navegador painel

de tarefasDiálogo

comando

functionFunções personalizadas
do Excel (quando o runtime é compartilhado ou o suplemento está em execução em Office na Web)

Tarefa
baseada em evento do Outlook(quando o suplemento está em execução no Outlook no Mac ou Outlook na Web)

Recurso de relatório de spam integrado do Outlook (versão prévia)
(somente quando o suplemento está sendo executado no Outlook no Mac ou na Web ou na Web ou na webnovo Outlook no Windows (versão prévia))

A tabela a seguir mostra as mesmas informações organizadas por qual tipo de runtime é usado para os vários recursos possíveis de um suplemento.

Recurso de suplemento Tipo de runtime no Windows Tipo de runtime no Mac Tipo de runtime na Web
Funções personalizadas do Excel Somente JavaScript
(mas navegador quando o runtime é compartilhado)		 Somente JavaScript
(mas navegador quando o runtime é compartilhado)		 Navegador
Tarefas baseadas em eventos do Outlook Navegador
JavaScript
(clássico do Outlook no Windows)

(novo Outlook no Windows (versão prévia))		 Navegador Navegador
Recurso de relatório de spam integrado do Outlook (versão prévia) Navegador
JavaScript
(clássico do Outlook no Windows)

(novo Outlook no Windows (versão prévia))		 Navegador Navegador
painel de tarefas Navegador Navegador Navegador
caixa de diálogo Navegador Navegador Navegador
comando function Navegador Navegador Navegador

Em Office na Web, tudo sempre é executado em um runtime de tipo de navegador. Com uma exceção, tudo em um suplemento na Web é executado no mesmo processo de navegador: o processo do navegador no qual o usuário abriu 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, 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á em execução em uma plataforma diferente da Web, os princípios a seguir se aplicam.

  • Uma caixa de diálogo é executada em seu próprio processo de runtime.

  • Um suplemento de relatório de spam ou baseado em eventos do Outlook é executado em seu próprio processo de runtime.

    Observação

    A ativação baseada em eventos e os recursos integrados de relatório de spam no Outlook devem usar o mesmo runtime. No momento, não há suporte para vários runtimes 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 runtime. No entanto, para alguns aplicativos host do Office, o manifesto de suplemento pode ser configurado para que qualquer dois ou todos os três possam ser executados no mesmo runtime. Consulte Runtime compartilhado.

Dependendo do aplicativo do Office host e dos recursos usados no suplemento, pode haver muitos runtimes 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 Word que não compartilha nenhum runtime e inclui os seguintes recursos, 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 no painel de tarefas ou no comando da função.)

      Observação

      Não é uma boa prática 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 do comando de função ao mesmo tempo, esse suplemento terá quatro runtimes. 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 em cima de seu antecessor com cada invocação, portanto, pode haver muitos runtimes. O restante dessa 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 seguintes recursos 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 no painel de tarefas, no comando da função ou em uma função personalizada.)

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

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

  • Um suplemento do Outlook que tem os seguintes recursos tem até quatro runtimes. Não há suporte para runtimes compartilhados no Outlook.

    • Um painel de tarefas
    • Um comando de função
    • Uma tarefa baseada em eventos ou um recurso de relatório de spam integrado
    • Uma caixa de diálogo (uma caixa de diálogo pode ser lançada do painel de tarefas ou do comando da função, mas não de uma tarefa baseada em eventos.)

Compartilhar dados em runtimes

Observação

  • Se você souber que seu suplemento só será usado em Office na Web e que ele não abrirá nenhuma caixa de diálogo com a opção displayInIFrame definida como true, então você poderá ignorar esta seção. Como tudo em seu suplemento é executado no mesmo processo de runtime, basta usar variáveis globais para compartilhar dados entre recursos.
  • Conforme observado acima em Tipos de runtimes, o tipo de runtime usado por um recurso varia parcialmente por plataforma. É uma boa prática evitar ter um código de suplemento que ramifica com base na plataforma, portanto, as diretrizes nesta seção recomendam técnicas que funcionarão entre plataformas. Há apenas um caso, observado abaixo, no qual o código de ramificação é necessário.

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ê precisa de métodos alternativos. As partes do suplemento que estão em processos de runtime separados não compartilham dados globais automaticamente e são tratadas pelo servidor de aplicativo Web do suplemento como sessões separadas, portanto , Window.sessionStorage não pode ser usado para compartilhar dados entre eles. As diretrizes a seguir pressupõem que você não está usando um runtime compartilhado.

  • Passe 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 runtime.

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

    Observação

    O LocalStorage não é acessível em um runtime somente JavaScript e, portanto, ele 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 runtime somente JavaScript em algumas plataformas).

    A partir da versão 115 de navegadores baseados em Chromium, como Chrome e Edge, a partição de armazenamento está sendo testada para impedir o rastreamento entre sites de canal lateral específico (consulte também políticas de navegador do Microsoft Edge). Isso significa que os dados armazenados por APIs de armazenamento, como o armazenamento local, só estão disponíveis para contextos com a mesma origem e o mesmo site de nível superior. Para contornar isso, no navegador, vá para chrome://flags ou edge://flags e defina o sinalizador Experimental de partição de armazenamento de terceiros (#third-armazenamento-particionamento) como Desabilitado.

    Dica

    Os dados em Window.localStorage persistem entre sessões do suplemento e são compartilhados por suplementos com a mesma origem. Essas duas características geralmente são indesejáveis para um suplemento.

    • Para garantir que cada sessão de um determinado suplemento inicie uma nova chamada, chame o método Window.localStorage.clear quando o suplemento for iniciado.
    • Para permitir que alguns valores armazenados persistam, mas reinitialize outros valores, use Window.localStorage.setItem quando o suplemento for iniciado para cada item que deve ser redefinido para um valor inicial.
    • Para excluir um item inteiramente, 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 runtimes.
  • Armazene dados compartilhados em um cookie para o domínio do suplemento para compartilhá-los entre runtimes do navegador. Runtimes somente JavaScript não dão suporte a cookies.

Para obter mais informações, consulte Persist add-in state and settings and Get and set add-in metadata for an Outlook add-in.

Runtime somente JavaScript

O runtime somente JavaScript usado em Suplementos do Office é uma modificação de um runtime código aberto criado originalmente para 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 runtime é usado em suplementos baseados em eventos e relatórios de spam no Outlook somente no Windows e em funções personalizadas do Excel , exceto quando as funções personalizadas estão compartilhando um runtime.

  • 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 de relatório de spam ou baseado em eventos do Outlook, o runtime é iniciado quando o evento ocorre. Ele termina quando o primeiro dos seguintes ocorre.

    • O manipulador de eventos chama o completed método de seu parâmetro de evento.
    • Cinco minutos se passaram desde o evento de gatilho.
    • O usuário altera o foco da janela em que o evento foi disparado, como uma janela de composição de mensagem (só se aplica a suplementos baseados em evento).

    Observação

    A ativação baseada em eventos e os recursos integrados de relatório de spam no Outlook devem usar o mesmo runtime. No momento, não há suporte para vários runtimes no Outlook.

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

Importante

O runtime somente JavaScript dá suporte diretamente ao padrão ECMAScript 2016 do JavaScript, mas você pode usar versões posteriores do JavaScript ou TypeScript. Para obter informações sobre como fazer isso, consulte Suporte para versões recentes do JavaScript.

Runtime do navegador

Os suplementos do Office usam um runtime de tipo de navegador diferente, dependendo da plataforma em que o Office está em execução (Web, Mac ou Windows) e na versão e compilação do Windows e do Office. Por exemplo, se o usuário estiver executando Office na Web em um navegador FireFox, o runtime 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 Explorer do Edge ou da Internet fornecerá o runtime, dependendo da versão do Windows e do Office. Os detalhes podem ser encontrados em navegadores e controles de visão da Web usados pelos Suplementos do Office.

Todos esses runtimes incluem um mecanismo de renderização HTML e fornecem suporte para WebSockets, CORS Completo (Compartilhamento de Recursos entre Origens)e armazenamento local e cookies.

Um tempo de vida de runtime do 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 runtime compartilhado, ele será desligado quando o documento é fechado. Se não for um runtime compartilhado, ele será desligado quando o painel de tarefas é fechado.

  • Quando uma caixa de diálogo é aberta, um runtime do 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á esteja em execução. Se for um runtime compartilhado, ele será desligado quando o documento é fechado. Se não for um runtime compartilhado, ele será desligado quando o primeiro dos seguintes ocorrer.

    • O comando de função chama o completed método de seu parâmetro de evento.
    • Cinco minutos se passaram desde o evento de gatilho. (Se uma caixa de diálogo foi aberta no comando da função e ela ainda estiver aberta quando o tempo de execução pai for encerrado, o runtime da caixa de diálogo permanecerá 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 começa 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.

Observação

Quando um runtime está sendo compartilhado, é possível que o código feche o painel de tarefas sem desligar o suplemento. Consulte Mostrar ou ocultar o painel de tarefas do suplemento do Office para obter mais informações.

Um runtime do navegador tem mais recursos do que um runtime somente JavaScript, mas começa mais lento e usa mais memória.

Tempo de execução compartilhado

Um "runtime compartilhado" não é um tipo de runtime. Ele se refere a um runtime do tipo navegador que está sendo compartilhado por recursos do suplemento que, caso contrário, cada um deles teria seu próprio runtime. Especificamente, você tem a opção de configurar o painel de tarefas e os comandos de função do suplemento para compartilhar um runtime. Em um suplemento do Excel, você também pode configurar funções personalizadas para compartilhar o runtime de um painel de tarefas ou comando de função ou ambos. Quando você faz isso, as funções personalizadas são executadas em um runtime do tipo navegador, em vez de um runtime 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 breve, o runtime somente JavaScript usa menos memória e inicia mais rapidamente, mas tem menos recursos.

Observação

  • Você só pode compartilhar runtimes no Excel, PowerPoint e Word.
  • Você não pode configurar uma caixa de diálogo para compartilhar um runtime. Cada caixa de diálogo sempre tem a sua própria, exceto quando a caixa de diálogo é lançada em Office na Web com a opção displayInIFrame definida como true.
  • Um runtime compartilhado nunca usa o runtime original do Microsoft Edge WebView (EdgeHTML). Se as condições para usar o Microsoft Edge com o WebView2 (baseado em Chromium) forem atendidas (conforme especificado em Navegadores e controles de webview usados pelos Suplementos do Office), esse runtime será usado. Caso contrário, o runtime da Internet Explorer 11 é usado.