Visão geral do ambiente de execução V8

No Google Apps Script e no JavaScript, um ambiente de execução ou ambiente de execução contém o mecanismo JavaScript que analisa e executa o código do script. O ambiente de execução fornece regras sobre como a memória é acessada, como o programa pode interagir com o sistema operacional do computador e qual sintaxe de programa é legal. Cada navegador da Web tem um ambiente de execução para JavaScript.

Historicamente, o Apps Script era desenvolvido pelo interpretador JavaScript Rhino da Mozilla. Embora o Rhino tenha fornecido uma maneira conveniente para o Apps Script executar scripts de desenvolvedores, ele também vinculou o Apps Script a uma versão específica do JavaScript (ES5). Os desenvolvedores do Apps Script não podem usar sintaxe e recursos mais modernos do JavaScript em scripts que usam o ambiente de execução do Rhino.

Para resolver esse problema, o Apps Script agora é compatível com o V8 ambiente de execução que alimenta o Chrome e o Node.js. Migre os scripts atuais para o V8 para aproveitar a sintaxe e os recursos modernos do JavaScript.

Esta página descreve os novos recursos ativados pelo V8 e como ativar o V8 para uso nos scripts. A migração de scripts para o V8 descreve as etapas para migrar scripts atuais para usar o ambiente de execução do V8.

Recursos do ambiente de execução do V8

Os scripts que usam o ambiente de execução do V8 podem aproveitar os seguintes recursos:

Sintaxe moderna do ECMAScript

Use a sintaxe moderna do ECMAScript em scripts que são alimentados pelo ambiente de execução do V8. Essa sintaxe inclui let, const e muitos outros recursos populares.

Consulte exemplos de sintaxe do V8 para uma pequena lista de melhorias de sintaxe populares que podem ser feitas usando o ambiente de execução do V8.

O ambiente de execução do V8 do Apps Script tem algumas limitações e diferenças importantes em comparação com outros ambientes de execução comuns do JavaScript. Consulte as limitações do ambiente de execução do V8 do Apps Script para mais detalhes.

Detecção de função aprimorada

A detecção de função do Apps Script foi aprimorada para scripts que usam o V8. O novo ambiente de execução reconhece estes formatos de definição de função:

      function normalFunction() {}
      async function asyncFunction() {}
      function* generatorFunction() {}

      var varFunction = function() {}
      let letFunction = function() {}
      const constFunction = function() {}

      var namedVarFunction = function alternateNameVarFunction() {}
      let namedLetFunction = function alternateNameLetFunction() {}
      const namedConstFunction = function alternateNameConstFunction() {}

      var varAsyncFunction = async function() {}
      let letAsyncFunction = async function() {}
      const constAsyncFunction = async function() {}

      var namedVarAsyncFunction = async function alternateNameVarAsyncFunction() {}
      let namedLetAsyncFunction = async function alternateNameLetAsyncFunction() {}
      const namedConstAsyncFunction = async function alternateNameConstAsyncFunction() {}

      var varGeneratorFunction = function*() {}
      let letGeneratorFunction = function*() {}
      const constGeneratorFunction = function*() {}

      var namedVarGeneratorFunction = function* alternateNameVarGeneratorFunction() {}
      let namedLetGeneratorFunction = function* alternateNameLetGeneratorFunction() {}
      const namedConstGeneratorFunction = function* alternateNameConstGeneratorFunction() {}

      var varLambda = () => {}
      let letLambda = () => {}
      const constLambda = () => {}

      var varAsyncLambda = async () => {}
      let letAsyncLambda = async () => {}
      const constAsyncLambda = async () => {}

Chamar métodos de objeto de acionadores e callbacks

Scripts que usam o V8 podem chamar métodos de objeto e métodos estáticos de classe de lugares em que já era possível chamar métodos de biblioteca. Esses lugares incluem o seguinte:

O exemplo de V8 a seguir mostra o uso de métodos de objeto ao construir itens de menu no Planilhas Google:

function onOpen() {
  const ui = SpreadsheetApp.getUi(); // Or DocumentApp, SlidesApp, or FormApp.
  ui.createMenu('Custom Menu')
      .addItem('First item', 'menu.item1')
      .addSeparator()
      .addSubMenu(ui.createMenu('Sub-menu')
          .addItem('Second item', 'menu.item2'))
      .addToUi();
}

const menu = {
  item1: function() {
    SpreadsheetApp.getUi().alert('You clicked: First item');
  },
  item2: function() {
    SpreadsheetApp.getUi().alert('You clicked: Second item');
  }
}

Ver registros

O Apps Script oferece dois serviços de registro: o Logger serviço e a console classe. Ambos os serviços gravam registros no mesmo serviço do Stackdriver Logging.

Para mostrar os registros Logger e console, na parte de cima do editor de scripts, clique em Registro de execução.

Ver execuções

Para conferir o histórico de execução do script, abra o projeto do Apps Script e, à esquerda, clique em Execuções .

O painel Execuções não fornece registros com carimbo de data/hora das chamadas de serviço individuais do Apps Script. Use o console serviço para criar mensagens de registro adequadas. Todos os registros criados com console aparecem no painel Execuções.

Exemplos de sintaxe do V8

A seguir, apresentamos uma pequena lista de recursos sintáticos populares disponíveis para scripts que usam o ambiente de execução do V8.

let e const

As palavras-chave let e const permitem definir variáveis locais de escopo de bloco e constantes de escopo de bloco, respectivamente.

// V8 runtime
let s = "hello";
if (s === "hello") {
  s = "world";
  console.log(s);  // Prints "world"
}
console.log(s);  // Prints "hello"

const N = 100;
N = 5; // Results in TypeError

Funções de seta

As funções de seta oferecem uma maneira compacta de definir funções em expressões.

// Rhino runtime
function square(x) {
  return x * x;
}

console.log(square(5));  // Outputs 25
      
// V8 runtime
const square = x => x * x;
console.log(square(5));  // Outputs 25

// Outputs [1, 4, 9]
console.log([1, 2, 3].map(x => x * x));

Classes

As classes fornecem um meio de organizar conceitualmente o código com herança. As classes no V8 são principalmente açúcar sintático sobre a herança baseada em protótipos do JavaScript.

// V8 runtime
class Rectangle {
  constructor(width, height) { // class constructor
    this.width = width;
    this.height = height;
  }

  logToConsole() { // class method
    console.log(`Rectangle(width=${this.width}, height=${this.height})`);
  }
}

const r = new Rectangle(10, 20);
r.logToConsole();  // Outputs Rectangle(width=10, height=20)

Atribuições de desestruturação

As expressões de atribuição de desestruturação são uma maneira rápida de desempacotar valores de matrizes e objetos em variáveis distintas.

// Rhino runtime
var data = {a: 12, b: false, c: 'blue'};
var a = data.a;
var c = data.c;
console.log(a, c);  // Outputs 12 "blue"

var a = [1, 2, 3];
var x = a[0];
var y = a[1];
var z = a[2];
console.log(x, y, z);  // Outputs 1 2 3
      
// V8 runtime
const data = {a: 12, b: false, c: 'blue'};
const {a, c} = data;
console.log(a, c);  // Outputs 12 "blue"


const array = [1, 2, 3];
const [x, y, z] = array;
console.log(x, y, z);  // Outputs 1 2 3

Literais de modelo

Os literais de modelo são literais de string que permitem expressões incorporadas. Eles permitem evitar instruções de concatenação de string mais complexas.

// Rhino runtime
var name =
  'Hi ' + first + ' ' + last + '.';
var url =
  'http://localhost:3000/api/messages/'
  + id;
      
// V8 runtime
const name = `Hi ${first} ${last}.`;
const url =
  `http://localhost:3000/api/messages/${id}`;

Parâmetros padrão

Os parâmetros padrão permitem especificar valores padrão para parâmetros de função na declaração. Isso pode simplificar o código no corpo da função, pois remove a necessidade de atribuir explicitamente valores padrão a parâmetros ausentes.

// Rhino runtime
function hello(greeting, name) {
    greeting = greeting || "hello";
    name = name || "world";
    console.log(
        greeting + " " + name + "!");
}

hello();  // Outputs "hello world!"
      
// V8 runtime
const hello =
  function(greeting="hello", name="world") {
      console.log(
        greeting + " " + name + "!");
  }

hello();  // Outputs "hello world!"

Strings de várias linhas

Defina strings de várias linhas usando a mesma sintaxe dos literais de modelo. Assim como com literais de modelo, essa sintaxe permite evitar concatenações de string e simplificar as definições de string.

// Rhino runtime
var multiline = "This string is sort of\n"
+ "like a multi-line string,\n"
+ "but it's not really one.";
      
// V8 runtime
const multiline = `This on the other hand,
actually is a multi-line string,
thanks to JavaScript ES6`;

Limitações do ambiente de execução do V8

O ambiente de execução do V8 do Apps Script não é um ambiente padrão do Node.js ou do navegador. Isso pode levar a problemas de compatibilidade ao chamar bibliotecas de terceiros ou adaptar exemplos de código de outros ambientes JavaScript.

APIs indisponíveis

As seguintes APIs JavaScript padrão NÃO estão disponíveis no ambiente de execução do V8 do Apps Script:

  • Timers: setTimeout, setInterval, clearTimeout, clearInterval
  • Streams: ReadableStream, WritableStream, TextEncoder, TextDecoder
  • APIs da Web: fetch, FormData, File, Blob, URL, URLSearchParams, DOMException, atob, btoa
  • Crypto: crypto, SubtleCrypto
  • Objetos globais: window, navigator, performance, process (Node.js)

Use as seguintes APIs do Apps Script como alternativas:

Para APIs sem uma alternativa do Apps Script, como TextEncoder, às vezes é possível usar um polyfill. Um polyfill é uma biblioteca que replica a funcionalidade da API que não está disponível por padrão no ambiente de execução. Antes de usar um polyfill, confirme se ele é compatível com o ambiente de execução do V8 do Apps Script.

Limitações assíncronas

O ambiente de execução do V8 oferece suporte à sintaxe async e await e ao objeto Promise. No entanto, o ambiente de execução do Apps Script é fundamentalmente síncrono.

  • Microtarefas (com suporte): o ambiente de execução processa a fila de microtarefas (em que ocorrem Promise.then callbacks e await resoluções) depois que a pilha de chamadas atual é limpa.
  • Macrotarefas (sem suporte): o Apps Script não tem um loop de eventos padrão para macrotarefas. Funções como setTimeout e setInterval não estão disponíveis.
  • Exceção do WebAssembly: a API WebAssembly é o único recurso integrado que opera de maneira não bloqueadora no ambiente de execução, permitindo padrões de compilação assíncronos específicos (WebAssembly.instantiate).

Todas as operações de E/S, como UrlFetchApp.fetch, são bloqueadoras. Para fazer solicitações de rede paralelas, use UrlFetchApp.fetchAll.

Limitações de classe

O ambiente de execução do V8 tem limitações específicas em relação aos recursos de classe ES6+ modernos:

  • Campos particulares: os campos de classe particulares (por exemplo, #field) não são compatíveis e causam erros de análise. Considere usar fechamentos ou WeakMap para encapsulamento verdadeiro.
  • Campos estáticos: declarações de campo estático diretas no corpo da classe (por exemplo, static count = 0;) não são compatíveis. Atribua propriedades estáticas à classe após a definição dela (por exemplo, MyClass.count = 0;).

Limitações do módulo

  • Módulos ES6: o ambiente de execução do V8 não oferece suporte a módulos ES6 (import / export). Para usar bibliotecas, é necessário usar o mecanismo de biblioteca do Apps Script ou agrupar o código e as dependências em um único arquivo de script. (Issue Tracker)
  • Ordem de execução de arquivos: todos os arquivos de script no projeto são executados em um escopo global. É melhor evitar o código de nível superior com efeitos colaterais e garantir que as funções e classes sejam definidas antes de serem usadas em arquivos. Ordene explicitamente os arquivos no editor se houver dependências entre eles.

Ativar o ambiente de execução do V8

Se um script estiver usando o ambiente de execução do Rhino, mude para o V8 fazendo o seguinte:

  1. Abra o projeto do Apps Script.
  2. À esquerda, clique em Configurações do projeto .
  3. Marque a caixa de seleção Ativar o ambiente de execução do Chrome V8.

Como alternativa, especifique o ambiente de execução do script diretamente editando o arquivo de manifesto do script file:

  1. Abra o projeto do Apps Script.
  2. À esquerda, clique em Configurações do projeto .
  3. Marque a caixa de seleção Mostrar arquivo de manifesto "appsscript.json" no editor.
  4. À esquerda, clique em Editor > appsscript.json.
  5. No arquivo de manifesto appsscript.json, defina o runtimeVersion campo como o valor V8.
  6. Na parte de cima, clique em Salvar projeto .

A migração de scripts para o V8 explica outras etapas que você precisa seguir para garantir que o script funcione bem usando o V8.

Ativar o ambiente de execução do Rhino

Se o script estiver usando o V8 e você precisar mudar para usar o ambiente de execução original do Rhino, faça o seguinte:

  1. Abra o projeto do Apps Script.
  2. À esquerda, clique em Configurações do projeto .
  3. Desmarque a caixa de seleção Ativar o ambiente de execução do Chrome V8.

Como alternativa, edite o manifesto do script:

  1. Abra o projeto do Apps Script.
  2. À esquerda, clique em Configurações do projeto .
  3. Marque a caixa de seleção Mostrar arquivo de manifesto "appsscript.json" no editor.
  4. À esquerda, clique em Editor > appsscript.json.
  5. No arquivo de manifesto appsscript.json, defina o runtimeVersion campo como o valor DEPRECATED_ES5.
  6. Na parte de cima, clique em Salvar projeto .

Como migrar scripts atuais?

O guia Migrar scripts para o V8 descreve as etapas necessárias para migrar um script atual para usar o V8. Isso envolve ativar o ambiente de execução do V8 e verificar o script em busca de incompatibilidades conhecidas.

Migração automática de scripts para o V8

A partir de 18 de fevereiro de 2020, o Google migra gradualmente os scripts atuais que passam no nosso teste de compatibilidade automatizado para o V8. Os scripts afetados continuam funcionando normalmente após a migração.

Se você quiser desativar a migração automática de um script, defina o runtimeVersion campo no manifesto como DEPRECATED_ES5. Escolha migrar manualmente o script para o V8 a qualquer momento.

Como faço para informar bugs?

O guia de suporte explica como receber ajuda de programação no Stack Overflow, pesquisar relatórios de problemas atuais, registrar novos bugs e fazer novas solicitações de recursos.