Se você tiver um script que usa o ambiente de execução do Rhino e quiser usar a sintaxe e os recursos do V8, migre o script para o V8.
A maioria dos scripts criados com o ambiente de execução do Rhino funciona com o ambiente de execução do V8 sem ajustes. Muitas vezes, o único pré-requisito para adicionar a sintaxe e os recursos do V8 a um script é ativar o ambiente de execução do V8.
No entanto, há um pequeno conjunto de incompatibilidades e outras diferenças que podem resultar em um script falhando ou se comportando de forma inesperada após ativar o ambiente de execução do V8. Ao migrar um script para usar o V8, é preciso pesquisar esses problemas no projeto de script e corrigir os encontrados.
Procedimento de migração do V8
Para migrar um script para o V8, siga este procedimento:
- Ative o tempo de execução do V8 para o script.
- Analise com atenção as incompatibilidades listadas abaixo. Examine seu script para determinar se há incompatibilidades. Se uma ou mais incompatibilidades estiverem presentes, ajuste o código do script para remover ou evitar o problema.
- Analise com atenção as outras diferenças listadas abaixo. Examine seu script para determinar se alguma das diferenças listadas afeta o comportamento do código. Ajuste o script para corrigir o comportamento.
- Depois de corrigir as incompatibilidades descobertas ou outras diferenças, você pode começar a atualizar seu código para usar a sintaxe V8 e outros recursos conforme quiser.
- Depois de concluir os ajustes do código, teste o script minuciosamente para garantir que ele se comporte conforme o esperado.
- Se o script for um app da Web ou um complemento publicado, será necessário criar uma nova versão do script com os ajustes da V8. Para disponibilizar a versão V8 para os usuários, republique o script com essa versão.
Incompatibilidades
Infelizmente, o ambiente de execução original do Apps Script baseado no Rhino permitiu vários comportamentos do ECMAScript não padrão. Como o V8 está em conformidade com os padrões, esses comportamentos não serão aceitos após a migração. A não correção desses problemas resulta em erros ou comportamento corrompido do script quando o ambiente de execução do V8 é ativado.
As seções a seguir descrevem cada um desses comportamentos e etapas para corrigir o código do script durante a migração para o V8.
Evite for each(variable in object)
A instrução for each (variable in object)
foi adicionada ao JavaScript 1.6 e removida em favor de for...of
.
Ao migrar seu script para o V8, evite usar instruções for each (variable in object)
.
Em vez disso, use for (variable in object)
:
// Rhino runtime var obj = {a: 1, b: 2, c: 3}; // Don't use 'for each' in V8 for each (var value in obj) { Logger.log("value = %s", value); } |
// V8 runtime var obj = {a: 1, b: 2, c: 3}; for (var key in obj) { // OK in V8 var value = obj[key]; Logger.log("value = %s", value); } |
Evite Date.prototype.getYear()
No ambiente de execução original do Rhino, Date.prototype.getYear()
retorna anos com dois dígitos para os anos de 1900 a 1999, mas anos com quatro dígitos para outras datas, que era o comportamento no JavaScript 1.2 e anteriores.
No ambiente de execução do V8, Date.prototype.getYear()
retorna o ano menos 1900, conforme exigido pelos padrões ECMAScript.
Ao migrar seu script para o V8, sempre use
Date.prototype.getFullYear()
,
que retorna um ano de quatro dígitos, independentemente da data.
Evite usar palavras-chave reservadas como nomes
A ECMAScript proíbe o uso de determinadas palavras-chave reservadas em nomes de funções e variáveis. O ambiente de execução do Rhino permitia muitas dessas palavras. Portanto, se elas forem usadas no código, será necessário renomear as funções ou variáveis.
Ao migrar seu script para o V8, evite nomear variáveis ou funções usando uma das palavras-chave reservadas.
Renomeie qualquer variável ou função para evitar o uso do nome da palavra-chave. Os usos comuns de palavras-chave como nomes são class
, import
e export
.
Evite reatribuir variáveis const
.
No ambiente de execução original do Rhino, você pode declarar uma variável usando const
, o que
significa que o valor do símbolo nunca muda e as atribuições futuras ao
símbolo são ignoradas.
No novo ambiente de execução do V8, a palavra-chave const
está em conformidade com o padrão, e a atribuição
a uma variável declarada como const
resulta em um
erro de tempo de execução TypeError: Assignment to constant variable
.
Ao migrar seu script para o V8, não tente reatribuir o valor de uma variável const
:
// Rhino runtime const x = 1; x = 2; // No error console.log(x); // Outputs 1 |
// V8 runtime const x = 1; x = 2; // Throws TypeError console.log(x); // Never executed |
Evitar literais XML e o objeto XML
Essa extensão não padrão do ECMAScript permite que projetos do Apps Script usem a sintaxe XML diretamente.
Ao migrar seu script para o V8, evite usar literais XML diretos ou o objeto XML.
Em vez disso, use o XmlService para analisar o XML:
// V8 runtime var incompatibleXml1 = <container><item/></container>; // Don't use var incompatibleXml2 = new XML('<container><item/></container>'); // Don't use var xml3 = XmlService.parse('<container><item/></container>'); // OK |
Não crie funções de iterador personalizadas usando __iterator__
O JavaScript 1.7 adicionou um recurso para permitir a adição de um iterador personalizado a qualquer classe
declarando uma função __iterator__
no protótipo dessa classe. Isso também
foi adicionado ao ambiente de execução do Rhino do Apps Script para conveniência do desenvolvedor. No entanto, esse recurso nunca fazia parte do padrão ECMA-262 e foi removido dos mecanismos JavaScript em conformidade com o ECMAScript. Scripts que usam V8 não podem usar essa construção de iterador.
Ao migrar seu script para o V8, evite a função __iterator__
para criar
iteradores personalizados. Em vez disso, use os iteradores do ECMAScript 6.
Considere a seguinte construção de matriz:
// Create a sample array var myArray = ['a', 'b', 'c']; // Add a property to the array myArray.foo = 'bar'; // The default behavior for an array is to return keys of all properties, // including 'foo'. Logger.log("Normal for...in loop:"); for (var item in myArray) { Logger.log(item); // Logs 0, 1, 2, foo } // To only log the array values with `for..in`, a custom iterator can be used. |
Os exemplos de código a seguir mostram como um iterador pode ser construído no tempo de execução do Rhino e como criar um iterador substituto no ambiente de execução do V8:
// Rhino runtime custom iterator function ArrayIterator(array) { this.array = array; this.currentIndex = 0; } ArrayIterator.prototype.next = function() { if (this.currentIndex >= this.array.length) { throw StopIteration; } return "[" + this.currentIndex + "]=" + this.array[this.currentIndex++]; }; // Direct myArray to use the custom iterator myArray.__iterator__ = function() { return new ArrayIterator(this); } Logger.log("With custom Rhino iterator:"); for (var item in myArray) { // Logs [0]=a, [1]=b, [2]=c Logger.log(item); } |
// V8 runtime (ECMAScript 6) custom iterator myArray[Symbol.iterator] = function() { var currentIndex = 0; var array = this; return { next: function() { if (currentIndex < array.length) { return { value: "[${currentIndex}]=" + array[currentIndex++], done: false}; } else { return {done: true}; } } }; } Logger.log("With V8 custom iterator:"); // Must use for...of since // for...in doesn't expect an iterable. for (var item of myArray) { // Logs [0]=a, [1]=b, [2]=c Logger.log(item); } |
Evitar cláusulas de captura condicional
O ambiente de execução do V8 não oferece suporte a cláusulas de captura condicional catch..if
, já que não estão em conformidade com o padrão.
Ao migrar seu script para o V8, mova todas as condicionais de captura para dentro do corpo da captura:
// Rhino runtime try { doSomething(); } catch (e if e instanceof TypeError) { // Don't use // Handle exception } |
// V8 runtime try { doSomething(); } catch (e) { if (e instanceof TypeError) { // Handle exception } } |
Evitar usar Object.prototype.toSource()
O JavaScript 1.3 continha um método Object.prototype.toSource() que nunca fazia parte de nenhum padrão ECMAScript. Ela não é compatível com o tempo de execução do V8.
Ao migrar seu script para o V8, remova qualquer uso de Object.prototype.toSource() do código.
Outras diferenças
Além das incompatibilidades acima que podem causar falhas de script, há algumas outras diferenças que, se não forem corrigidas, podem resultar em um comportamento inesperado do script de execução do V8.
As seções a seguir explicam como atualizar o código do script para evitar essas surpresas inesperadas.
Ajustar a formatação de data e hora específica do local
Os métodos Date
toLocaleString()
,
toLocaleDateString()
e toLocaleTimeString()
se comportam
de maneira diferente no ambiente de execução do V8 em comparação com o Rhino.
No Rhino, o formato padrão é o formato longo, e todos os parâmetros transmitidos são ignorados.
No ambiente de execução do V8, o formato padrão é o formato curto, e os parâmetros
transmitidos são processados de acordo com o padrão ECMA. Consulte a
documentação toLocaleDateString()
para mais detalhes.
Ao migrar seu script para o V8, teste e ajuste as expectativas do código em relação à saída de métodos de data e hora específicos da localidade:
// Rhino runtime var event = new Date( Date.UTC(2012, 11, 21, 12)); // Outputs "December 21, 2012" in Rhino console.log(event.toLocaleDateString()); // Also outputs "December 21, 2012", // ignoring the parameters passed in. console.log(event.toLocaleDateString( 'de-DE', { year: 'numeric', month: 'long', day: 'numeric' })); |
// V8 runtime var event = new Date( Date.UTC(2012, 11, 21, 12)); // Outputs "12/21/2012" in V8 console.log(event.toLocaleDateString()); // Outputs "21. Dezember 2012" console.log(event.toLocaleDateString( 'de-DE', { year: 'numeric', month: 'long', day: 'numeric' })); |
Evite usar Error.fileName
e Error.lineNumber
.
No untime do V8, o objeto
Error
JavaScript padrão não oferece suporte a fileName
ou lineNumber
como parâmetros
do construtor ou propriedades do objeto.
Ao migrar seu script para o V8, remova qualquer dependência de Error.fileName
e Error.lineNumber
.
Uma alternativa é usar o
Error.prototype.stack
.
Essa pilha também não é padrão, mas tem suporte no Rhino e no V8. O
formato do stack trace produzido pelas duas plataformas é um pouco diferente:
// Rhino runtime Error.prototype.stack // stack trace format at filename:92 (innerFunction) at filename:97 (outerFunction) |
// V8 runtime Error.prototype.stack // stack trace format Error: error message at innerFunction (filename:92:11) at outerFunction (filename:97:5) |
Ajustar o processamento de objetos enum stringificados
No ambiente de execução original do Rhino, o uso do método
JSON.stringify()
JavaScript em um objeto de enumeração retorna apenas {}
.
No V8, usar o mesmo método em um objeto de enumeração retorna o nome do tipo enumerado.
Ao migrar seu script para o V8,
teste e ajuste as expectativas do código em relação à saída de
JSON.stringify()
em objetos de enumeração:
// Rhino runtime var enumName = JSON.stringify(Charts.ChartType.BUBBLE); // enumName evaluates to {} |
// V8 runtime var enumName = JSON.stringify(Charts.ChartType.BUBBLE); // enumName evaluates to "BUBBLE" |
Ajustar o processamento de parâmetros indefinidos
No ambiente de execução original do Rhino, transmitir undefined
a um método como parâmetro
resultou na transmissão da string "undefined"
para esse método.
No V8, transmitir undefined
para métodos é equivalente a transmitir null
.
Ao migrar seu script para o V8,
teste e ajuste as expectativas do código em relação aos parâmetros undefined
:
// Rhino runtime SpreadsheetApp.getActiveRange() .setValue(undefined); // The active range now has the string // "undefined" as its value. |
// V8 runtime SpreadsheetApp.getActiveRange() .setValue(undefined); // The active range now has no content, as // setValue(null) removes content from // ranges. |
Ajustar o processamento de this
globais
O ambiente de execução do Rhino define um contexto especial implícito para os scripts que o utilizam.
O código de script é executado nesse contexto implícito, diferente do this
global real. Isso significa que as referências ao "this
global" no código realmente
avaliam o contexto especial, que contém apenas o código e as variáveis
definidos no script. Os serviços integrados do Apps Script e os objetos ECMAScript não são usados em this
. A situação é parecida com esta
estrutura do JavaScript:
// Rhino runtime // Apps Script built-in services defined here, in the actual global context. var SpreadsheetApp = { openById: function() { ... } getActive: function() { ... } // etc. }; function() { // Implicit special context; all your code goes here. If the global this // is referenced in your code, it only contains elements from this context. // Any global variables you defined. var x = 42; // Your script functions. function myFunction() { ... } // End of your code. }(); |
No V8, o contexto especial implícito é removido. As variáveis e funções globais definidas no script são colocadas no contexto global, ao lado dos serviços integrados do Apps Script e do ECMAScript, como Math
e Date
.
Ao migrar seu script para o V8, teste e ajuste as expectativas do código
em relação ao uso de this
em um contexto global. Na maioria dos casos, as diferenças
só serão aparentes se o código examinar as chaves ou os nomes de propriedades do
objeto this
global:
// Rhino runtime var myGlobal = 5; function myFunction() { // Only logs [myFunction, myGlobal]; console.log(Object.keys(this)); // Only logs [myFunction, myGlobal]; console.log( Object.getOwnPropertyNames(this)); } |
// V8 runtime var myGlobal = 5; function myFunction() { // Logs an array that includes the names // of Apps Script services // (CalendarApp, GmailApp, etc.) in // addition to myFunction and myGlobal. console.log(Object.keys(this)); // Logs an array that includes the same // values as above, and also includes // ECMAScript built-ins like Math, Date, // and Object. console.log( Object.getOwnPropertyNames(this)); } |
Ajustar o gerenciamento de instanceof
em bibliotecas
O uso de instanceof
em uma biblioteca em um objeto transmitido como um parâmetro em uma
função de outro projeto pode gerar falsos negativos. No ambiente de execução do V8, um
projeto e as bibliotecas dele são executados em diferentes contextos de execução e, portanto, têm
diferentes cadeias globais e de protótipos.
Observe que isso só acontecerá se a biblioteca usar instanceof
em um objeto
que não foi criado no projeto. O uso dele em um objeto criado no
projeto, seja no mesmo script ou em um script diferente,
deve funcionar conforme o esperado.
Se um projeto em execução no V8 usa seu script como uma biblioteca, verifique se ele
usa instanceof
em um parâmetro que será transmitido de outro projeto. Ajuste
o uso de instanceof
e use outras alternativas viáveis de acordo com seu caso
de uso.
Uma alternativa para a instanceof b
pode ser usar o construtor de a
nos
casos em que você não precisa pesquisar toda a cadeia de protótipos e apenas verificar
o construtor.
Uso: a.constructor.name == "b"
Considere o Projeto A e o Projeto B em que o Projeto A usa o Projeto B como biblioteca.
//Rhino runtime //Project A function caller() { var date = new Date(); // Returns true return B.callee(date); } //Project B function callee(date) { // Returns true return(date instanceof Date); } |
//V8 runtime //Project A function caller() { var date = new Date(); // Returns false return B.callee(date); } //Project B function callee(date) { // Incorrectly returns false return(date instanceof Date); // Consider using return (date.constructor.name == // “Date”) instead. // return (date.constructor.name == “Date”) -> Returns // true } |
Outra alternativa é introduzir uma função que verifique instanceof
no projeto principal
e transmita a função além de outros parâmetros ao chamar uma função de biblioteca. A função transmitida
pode ser usada para verificar instanceof
dentro da biblioteca.
//V8 runtime //Project A function caller() { var date = new Date(); // Returns True return B.callee(date, date => date instanceof Date); } //Project B function callee(date, checkInstanceOf) { // Returns True return checkInstanceOf(date); } |
Ajustar a transmissão de recursos não compartilhados para bibliotecas
Transmitir um recurso não compartilhado do script principal para uma biblioteca funciona de maneira diferente no ambiente de execução do V8.
No ambiente de execução do Rhino, a transmissão de um recurso não compartilhado não funcionará. A biblioteca usa o próprio recurso.
No tempo de execução do V8, a transmissão de um recurso não compartilhado para a biblioteca funciona. A biblioteca usa o recurso não compartilhado transmitido.
Não transmita recursos não compartilhados como parâmetros de função. Sempre declare recursos não compartilhados no mesmo script que os usa.
Considere o Projeto A e o Projeto B em que o Projeto A usa o Projeto B como biblioteca. Neste exemplo, PropertiesService
é um recurso não compartilhado.
// Rhino runtime // Project A function testPassingNonSharedProperties() { PropertiesService.getScriptProperties() .setProperty('project', 'Project-A'); B.setScriptProperties(); // Prints: Project-B Logger.log(B.getScriptProperties( PropertiesService, 'project')); } |
// V8 runtime // Project A function testPassingNonSharedProperties() { PropertiesService.getScriptProperties() .setProperty('project', 'Project-A'); B.setScriptProperties(); // Prints: Project-A Logger.log(B.getScriptProperties( PropertiesService, 'project')); } |
Atualizar o acesso a scripts independentes
Para scripts independentes em execução no ambiente de execução do V8, você precisa fornecer aos usuários pelo menos acesso de leitura ao script para que os gatilhos do script funcionem corretamente.