Tempo de execução somente de JavaScript para funções personalizadas

  • Artigo

Funções personalizadas que não usam um runtime compartilhado usam um runtime somente JavaScript projetado para otimizar o desempenho dos cálculos.

Importante

Observe que as funções personalizadas do Excel estão disponíveis nas plataformas a seguir.

  • Office no Windows
    • Assinatura do Microsoft 365
    • varejo perpétuo Office 2016 e posterior
  • Office no Mac
  • Office na Web

No momento, não há suporte para funções personalizadas do Excel no seguinte:

  • Office no iPad
  • versões perpétuas licenciadas por volume do Office 2019 ou anteriores

Observação

Recomendamos usar funções personalizadas com um runtime compartilhado, a menos que você tenha um motivo específico para não usar um runtime compartilhado. Observe que o uso de um runtime compartilhado significa que seu suplemento usará o WebView2 (baseado em Chromium do Microsoft Edge) se as condições forem atendidas e, caso contrário, seu suplemento usará Trident (Internet Explorer 11), independentemente da versão do Windows ou do Microsoft 365. Para obter uma descrição das condições do WebView2, consulte Navegadores e controles de visão da Web usados pelos Suplementos do Office. Para obter mais informações sobre runtimes, consulte Runtimes em Suplementos do Office e Runtimes.

Esse runtime somente JavaScript fornece acesso a APIs no OfficeRuntime namespace que podem ser usadas por funções personalizadas e pelo painel de tarefas (que é executado em um runtime diferente) para armazenar dados.

Solicitar dados externos

É possível solicitar dados externos em uma função personalizada por meio de uma API, como a API Fetch, ou por meio de um objeto XmlHttpRequest (XHR), uma API Web padrão que envia solicitações HTTP para interagir com os servidores.

Lembre-se de que as funções personalizadas devem usar medidas de segurança adicionais ao fazer XmlHttpRequests, exigindo a Mesma Política de Origem e CORS simples.

Uma implementação cors simples não pode usar cookies e só dá suporte a métodos simples (GET, HEAD, POST). A CORS simples aceita cabeçalhos simples com nomes de campos Accept, Accept-Language, Content-Language. Você também pode usar um Content-Type cabeçalho no CORS simples, desde que o tipo de conteúdo seja application/x-www-form-urlencoded, text/plainou multipart/form-data.

Armazenar e acessar dados

Dentro de uma função personalizada que não usa um runtime compartilhado, você pode armazenar e acessar dados usando o objeto OfficeRuntime.storage . O Storage objeto é um sistema de armazenamento persistente, não criptografado e de valor-chave que fornece uma alternativa ao localStorage, que não pode ser usado por funções personalizadas que usam o runtime somente JavaScript. O Storage objeto oferece 10 MB de dados por domínio. Os domínios podem ser compartilhados por mais de um suplemento.

O Storage objeto é uma solução de armazenamento compartilhado, o que significa que várias partes de um suplemento são capazes de acessar os mesmos dados. Por exemplo, tokens para autenticação de usuário podem ser armazenados no Storage objeto porque podem ser acessados por uma função personalizada (usando o runtime somente JavaScript) e um painel de tarefas (usando um runtime de visão da Web completo). Da mesma forma, se dois suplementos compartilharem o mesmo domínio (por exemplo, www.contoso.com/addin1, , www.contoso.com/addin2), eles também poderão compartilhar informações para frente e para trás por meio do Storage objeto. Observe que os suplementos que têm subdomínios diferentes terão instâncias diferentes de Storage (por exemplo, subdomain.contoso.com/addin1, ). differentsubdomain.contoso.com/addin2

Como o Storage objeto pode ser um local compartilhado, é importante perceber que é possível substituir pares de valor de chave.

Os métodos a seguir estão disponíveis no Storage objeto.

  • getItem
  • getItems
  • setItem
  • setItems
  • removeItem
  • removeItems
  • getKeys

Observação

Não há nenhum método para limpar todas as informações (como clear). Em vez disso, use removeItems para remover várias entradas de uma só vez.

Exemplo do OfficeRuntime.storage

O exemplo de código a seguir chama o OfficeRuntime.storage.setItem método para definir uma chave e um valor em storage.

function StoreValue(key, value) {

  return OfficeRuntime.storage.setItem(key, value).then(function (result) {
      return "Success: Item with key '" + key + "' saved to storage.";
  }, function (error) {
      return "Error: Unable to save item with key '" + key + "' to storage. " + error;
  });
}

Próximas etapas

Saiba como depurar funções personalizadas.

Confira também