Runtimes nos Suplementos do Office

Os Suplementos do Office são executados em runtimes incorporados no Office. Como linguagem interpretada, o JavaScript tem de ser executado num runtime javaScript. Node.js e browsers modernos são exemplos desses runtimes.

Tipos de runtimes

Existem dois tipos de runtimes utilizados pelos Suplementos do Office:

• Runtime apenas javaScript: um motor JavaScript complementado com suporte para WebSockets, CORS Completo (Partilha de Recursos Transversais à Origem) e armazenamento de dados do lado do cliente. Não suporta armazenamento local nem cookies.
• Runtime do browser: inclui todas as funcionalidades de um runtime apenas javaScript e adiciona suporte para armazenamento local, um motor de composição que compõe HTML e cookies.

Os detalhes sobre estes tipos encontram-se mais adiante neste artigo em Runtime apenas em JavaScript e Runtime do browser.

A tabela seguinte mostra as funcionalidades possíveis de um suplemento, de acordo com cada tipo de runtime.

Tipo de runtime	Funcionalidade de suplemento
Apenas JavaScript	Funções personalizadas do Excel(exceto quando o runtime é partilhado ou o suplemento está em execução no Office na Web) Tarefa baseada em eventos do Outlook (apenas quando o suplemento está em execução no Outlook clássico no Windows) Funcionalidade de relatórios de spam integrados do Outlook (apenas quando o suplemento está em execução no Outlook clássico no Windows)
Navegador	painel de tarefas caixa de diálogo comando functionFunções personalizadas do Excel (quando o runtime é partilhado ou o suplemento está em execução no Office na Web) Tarefa baseada em eventos do Outlook (quando o suplemento está a ser executado no Outlook no Mac ou no Outlook na Web ou no novo Outlook no Windows) Funcionalidade de relatórios de spam integrados do Outlook (apenas quando o suplemento está em execução no Outlook no Mac ou na Web ou no novo Outlook no Windows)

A tabela seguinte mostra as mesmas informações organizadas pelo tipo de runtime utilizado para as várias funcionalidades possíveis de um suplemento.

Funcionalidade de suplemento	Tipo de runtime no Windows	Tipo de runtime no Mac	Tipo de runtime na Web
Funções personalizadas do Excel	Apenas JavaScript(mas browser quando o runtime é partilhado)	Navegador	Navegador
Tarefas baseadas em eventos do Outlook	JavaScript-only (Outlook clássico no Windows) browser (novo Outlook no Windows)	Navegador	Navegador
Funcionalidade de relatórios de spam integrados do Outlook (pré-visualização)	JavaScript-only (Outlook clássico no Windows) browser (novo Outlook no Windows)	Navegador	Navegador
painel de tarefas	Navegador	Navegador	Navegador
caixa de diálogo	Navegador	Navegador	Navegador
comando function	Navegador	Navegador	Navegador

No Office na Web, tudo é sempre executado num runtime de tipo de browser. Com uma exceção, tudo num suplemento na Web é executado no mesmo processo do browser: o processo do browser no qual o utilizador abriu o Office na Web. A exceção ocorre quando uma caixa de diálogo é aberta com uma chamada de Office.ui.displayDialogAsync e a opção DialogOptions.displayInIFramenão é transmitida e definida como true. Quando a opção não é transmitida (por isso tem o valor predefinido false ), a caixa de diálogo é aberta no seu próprio processo. O mesmo princípio aplica-se ao método OfficeRuntime.displayWebDialog e à opção OfficeRuntime.DisplayWebDialogOptions.displayInIFrame .

Quando um suplemento está em execução numa plataforma diferente da Web, aplicam-se os seguintes princípios.

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

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

  Observação

  As funcionalidades de ativação baseada em eventos e relatórios de spam integrados no Outlook têm de utilizar o mesmo runtime. Atualmente, não são suportados vários runtimes no Outlook.

• Por predefinição, os painéis de tarefas, os comandos de função e as funções personalizadas do Excel são executados no seu próprio processo de runtime. No entanto, para algumas aplicações anfitriãs do Office, o manifesto do suplemento pode ser configurado para que qualquer duas ou três aplicações possam ser executadas no mesmo runtime. Veja Runtime partilhado.

Dependendo da aplicação anfitriã do Office e das funcionalidades utilizadas no suplemento, podem existir muitos runtimes num suplemento. Normalmente, cada um deles será executado no seu próprio processo, mas não necessariamente em simultâneo. Eis alguns exemplos.

• Um suplemento do PowerPoint ou word que não partilhe runtimes e que inclua as seguintes funcionalidades 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 é uma boa prática ter várias caixas de diálogo abertas em simultâneo, mas se o suplemento permitir que o utilizador abra uma a partir do painel de tarefas e outra a partir do comando de função ao mesmo tempo, este suplemento terá quatro runtimes. Um painel de tarefas e uma determinada invocação de um comando de função só podem ter uma caixa de diálogo aberta de cada vez; no entanto, se o comando da função for invocado várias vezes, é aberta uma nova caixa de diálogo sobre o antecessor com cada invocação, pelo que poderá haver muitos runtimes. O resto desta lista ignora a possibilidade de várias caixas de diálogo abertas.

• Um suplemento do Excel que não partilha runtimes e inclui as seguintes funcionalidades 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 da função ou de uma função personalizada.)

• Um suplemento do Excel com as mesmas funcionalidades e configurado para partilhar o mesmo runtime no painel de tarefas, no comando de função e na função personalizada, tem dois runtimes. Um runtime partilhado só pode abrir uma caixa de diálogo de cada vez.

• Um suplemento do Excel com as mesmas funcionalidades, exceto que não tem caixa de diálogo, e está configurado para partilhar o mesmo runtime no painel de tarefas, no comando de função e na função personalizada, tem um runtime.

• Um suplemento do Outlook com as seguintes funcionalidades tem até quatro runtimes. Os runtimes partilhados não são suportados no Outlook.

  • Um painel de tarefas
  • Um comando de função
  • Uma tarefa baseada em eventos ou uma funcionalidade de relatório de spam integrada
  • 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 eventos.)

Partilhar dados entre runtimes

Observação

• Se souber que o seu suplemento só será utilizado no Office na Web e que não irá abrir caixas de diálogo com a opção displayInIFrame definida como true, pode ignorar esta secção. Uma vez que tudo no seu suplemento é executado no mesmo processo de runtime, só pode utilizar variáveis globais para partilhar dados entre funcionalidades.
• Conforme indicado acima em Tipos de runtimes, o tipo de runtime utilizado por uma funcionalidade varia em parte por plataforma. É uma boa prática evitar ter código de suplemento que ramifica com base na plataforma, pelo que a documentação de orientação nesta secção recomenda técnicas que irão funcionar em várias plataformas. Existe apenas um caso, indicado abaixo, no qual o código de ramificação é necessário.

Para suplementos do Excel, PowerPoint e Word, utilize um runtime Partilhado quando duas ou mais funcionalidades, exceto caixas de diálogo, precisarem de partilhar dados. No Outlook, ou em cenários em que a partilha de um runtime não é viável, precisa de métodos alternativos. As partes do suplemento que estão em processos de runtime separados não partilham dados globais automaticamente e são tratadas pelo servidor de aplicações Web do suplemento como sessões separadas, pelo que Windows.sessionStorage não pode ser utilizado para partilhar dados entre eles. A seguinte documentação de orientação pressupõe que não está a utilizar um runtime partilhado.

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

  Observação

  Os OfficeRuntime.storage métodos não podem ser chamados numa caixa de diálogo, pelo que esta não é uma opção para partilhar dados entre uma caixa de diálogo e outro runtime.

• Para partilhar dados entre um painel de tarefas e um comando de função, armazene dados em Window.localStorage, que é partilhado em todos os runtimes que acedem à mesma origem específica.

  Observação

  LocalStorage não está acessível num runtime apenas javaScript e, portanto, não está disponível em funções personalizadas do Excel. Também não pode ser utilizado para partilhar dados com tarefas baseadas em eventos do Outlook (uma vez que essas tarefas utilizam um runtime apenas javaScript em algumas plataformas).

  A partir da Versão 115 dos browsers baseados no Chromium, como o Chrome e o Edge, a criação de partições de armazenamento está ativada para impedir o controlo de canais laterais específicos entre sites (consulte também políticas do browser Microsoft Edge). Isto 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.

  Dica

  Os dados em Window.localStorage persistem entre sessões do suplemento e são partilhados por suplementos com a mesma origem. Ambas as características são muitas vezes indesejáveis para um suplemento.

  • Para garantir que cada sessão de um determinado suplemento inicia uma nova chamada, chame o método Window.localStorage.clear quando o suplemento é iniciado.
  • Para permitir que alguns valores armazenados persistam, mas reinicialize outros valores, utilize Window.localStorage.setItem quando o suplemento for iniciado para cada item que deve ser reposto para um valor inicial.
  • Para eliminar completamente um item, chame Window.localStorage.removeItem.

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

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

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

Outras formas de partilhar dados incluem o seguinte:

• Armazene dados partilhados numa base de dados online que esteja acessível a todos os runtimes.
• Armazene dados partilhados num cookie do domínio do suplemento para partilhá-los entre runtimes do browser. Os runtimes apenas javaScript não suportam cookies.

Para obter mais informações, veja Manter o estado e as definições do suplemento e Obter e definir metadados de suplementos para um suplemento do Outlook.

Runtime apenas javaScript

O runtime apenas javaScript utilizado nos Suplementos do Office é uma modificação de um runtime open source criado originalmente para o React Native. Contém um motor JavaScript complementado com suporte para WebSockets, CORS Completo (Partilha de Recursos De Várias Origens) e OfficeRuntime.storage. Não tem um motor de composição e não suporta cookies nem armazenamento local.

Este tipo de runtime é utilizado em suplementos baseados em eventos e relatórios de spam no Outlook clássico apenas no Windows e em funções personalizadas do Excel, exceto quando as funções personalizadas estão a partilhar um runtime.

• Quando utilizado para uma função personalizada do Excel, o runtime é iniciado quando a folha de cálculo é recalculada ou a função personalizada calcula. Não é encerrado até que o livro seja fechado.

• Quando utilizado num suplemento baseado em eventos ou relatórios de spam do Outlook, o runtime é iniciado quando o evento ocorre. Termina quando ocorre o primeiro dos seguintes procedimentos.

  • O processador de eventos chama o completed método do respetivo parâmetro de evento.
  • Decorreram cinco minutos desde o evento de acionamento.
  • O utilizador altera o foco da janela onde o evento foi acionado, como uma janela de composição de mensagens (aplica-se apenas a suplementos baseados em eventos).

  Observação

  As funcionalidades de ativação baseada em eventos e relatórios de spam integrados no Outlook têm de utilizar o mesmo runtime. Atualmente, não são suportados vários runtimes no Outlook.

Um runtime apenas javaScript utiliza menos memória e inicia-se mais rapidamente do que um runtime do browser, mas tem menos funcionalidades.

Importante

Nas versões do Office para Windows anteriores à versão 2403 (Compilação 16.0.17425.20000) e licença perpétua do Office até ao Office 2021, o runtime apenas javaScript suporta diretamente o padrão ECMAScript 2016 do JavaScript. No entanto, pode utilizar versões posteriores de JavaScript ou TypeScript. Para obter informações sobre como fazê-lo, consulte Suporte para versões recentes do JavaScript.

Runtime do browser

Os Suplementos do Office utilizam um runtime de tipo de browser diferente consoante a plataforma na qual o Office está a executar (Web, Mac ou Windows) e na versão e compilação do Windows e do Office. Por exemplo, se o utilizador estiver a executar o Office na Web num browser FireFox, será utilizado o runtime do Firefox. Se o utilizador estiver a executar o Office no Mac, será utilizado o runtime do Safari. Se o utilizador estiver a executar o Office no Windows, o Edge ou o Internet Explorer fornece o runtime, consoante a versão do Windows e do Office. Pode encontrar detalhes em Browsers e controlos webview utilizados pelos Suplementos do Office.

Todos estes runtimes incluem um motor de composição HTML e fornecem suporte para WebSockets, CORS Completo (Partilha de Recursos De Várias Origens) e armazenamento local e cookies.

O tempo de vida do runtime do browser varia consoante a funcionalidade que implementa e se está a ser partilhado ou não.

• Quando é iniciado um suplemento com um painel de tarefas, é iniciado um runtime do browser, a menos que seja um runtime partilhado que já esteja em execução. Se for um runtime partilhado, será encerrado quando o documento for fechado. Se não for um runtime partilhado, será encerrado quando o painel de tarefas estiver fechado.

• Quando uma caixa de diálogo é aberta, é iniciado um runtime do browser. É encerrada quando a caixa de diálogo é fechada.

• Quando um comando de função é executado (o que acontece quando um utilizador seleciona o botão ou item de menu), é iniciado um runtime do browser, a menos que seja um runtime partilhado que já esteja em execução. Se for um runtime partilhado, será encerrado quando o documento for fechado. Se não for um runtime partilhado, será encerrado quando ocorrer o primeiro dos seguintes procedimentos.

  • O comando de função chama o completed método do respetivo parâmetro de evento.
  • Decorreram cinco minutos desde o evento de acionamento. (Se uma caixa de diálogo tiver sido aberta no comando de função e ainda estiver aberta quando o tempo de execução principal exceder o limite de tempo, o runtime da caixa de diálogo permanecerá em execução até a caixa de diálogo ser fechada.)

• Quando uma função personalizada do Excel está a utilizar um runtime partilhado, um runtime do tipo browser é iniciado quando a função personalizada calcula se o runtime partilhado ainda não foi iniciado por outro motivo. É encerrado quando o documento é fechado.

Observação

Quando um runtime está a ser partilhado, é possível que o seu código feche o painel de tarefas sem encerrar o suplemento. Consulte Mostrar ou ocultar o painel de tarefas do seu Suplemento do Office para obter mais informações.

Um runtime do browser tem mais funcionalidades do que um runtime apenas em JavaScript, mas inicia mais lentamente e utiliza mais memória.

Tempo de execução compartilhado

Um "runtime partilhado" não é um tipo de runtime. Refere-se a um runtime do tipo browser que está a ser partilhado por funcionalidades do suplemento que, caso contrário, cada um teria o seu próprio runtime. Especificamente, tem a opção de configurar o painel de tarefas e os comandos de função do suplemento para partilhar um runtime. Num suplemento do Excel, também pode configurar funções personalizadas para partilhar o runtime de um painel de tarefas ou comando de função ou ambos. Ao fazê-lo, as funções personalizadas são executadas num runtime do tipo browser, em vez de um runtime apenas javaScript como faria de outra forma. Veja Configurar o suplemento para utilizar um runtime partilhado para obter informações sobre as vantagens e limitações dos runtimes de partilha e instruções para configurar o suplemento para utilizar um runtime partilhado. Resumindo, o runtime apenas javaScript utiliza menos memória e inicia-se mais rapidamente, mas tem menos funcionalidades.

Observação

• Só pode partilhar runtimes no Excel, PowerPoint e Word.
• Não pode configurar uma caixa de diálogo para partilhar um runtime. Cada caixa de diálogo tem sempre a sua própria, exceto quando a caixa de diálogo é iniciada no Office na Web com a opção displayInIFrame definida como true.
• Um runtime partilhado nunca utiliza o runtime original do Microsoft Edge WebView (EdgeHTML). Se as condições para utilizar o Microsoft Edge com o WebView2 (baseado em Chromium) forem cumpridas (conforme especificado em Browsers e controlos webview utilizados pelos Suplementos do Office), esse runtime é utilizado. Caso contrário, é utilizado o runtime do Internet Explorer 11.