Wenn Sie ein vorhandenes Script mit der Rhino-Laufzeit haben und die Syntax und Funktionen von V8 verwenden möchten, müssen Sie das Script zu V8 migrieren.
Die meisten Scripts, die mit der Rhino-Laufzeit geschrieben wurden, können ohne Anpassung mit einer V8-Laufzeit ausgeführt werden. Häufig ist die einzige Voraussetzung zum Hinzufügen von V8-Syntax und -Funktionen zu einem Skript die Aktivierung der V8-Laufzeit.
Es gibt jedoch einige Inkompatibilitäten und andere Unterschiede, die dazu führen können, dass ein Script nach der Aktivierung der V8-Laufzeit fehlschlägt oder sich unerwartet verhält. Wenn Sie ein Skript zu V8 migrieren, müssen Sie das Skriptprojekt auf diese Probleme durchsuchen und alle gefundenen Fehler korrigieren.
V8-Migrationsverfahren
So migrieren Sie ein Script zu V8:
- Aktivieren Sie die V8-Laufzeit für das Script.
- Lesen Sie sich die unten aufgeführten Inkompatibilitäten sorgfältig durch. Prüfen Sie Ihr Script, um festzustellen, ob eine oder mehrere der Inkompatibilitäten vorliegen. Falls ja, passen Sie den Scriptcode an, um das Problem zu beheben oder zu vermeiden.
- Lesen Sie sich die anderen Unterschiede unten sorgfältig durch. Prüfen Sie Ihr Script, um festzustellen, ob sich eine der aufgeführten Unterschiede auf das Verhalten Ihres Codes auswirkt. Passen Sie das Script an, um das Verhalten zu korrigieren.
- Sobald Sie alle gefundenen Inkompatibilitäten oder anderen Unterschiede korrigiert haben, können Sie Ihren Code so aktualisieren, dass er die V8-Syntax und andere Funktionen verwendet.
- Testen Sie Ihr Script gründlich, nachdem Sie die Codeanpassungen vorgenommen haben, um sicherzustellen, dass es wie erwartet funktioniert.
- Wenn es sich bei Ihrem Skript um eine Webanwendung oder ein veröffentlichtes Add-on handelt, müssen Sie mit den V8-Anpassungen eine neue Version des Skripts erstellen. Damit die V8-Version für Nutzer verfügbar ist, müssen Sie das Script mit dieser Version noch einmal veröffentlichen.
Inkompatibilitäten
Die ursprüngliche Rhino-basierte Apps Script-Laufzeit erlaubte leider mehrere nicht standardmäßige ECMAScript-Verhaltensweisen. Da V8 standardskonform ist, werden diese Verhaltensweisen nach der Migration nicht mehr unterstützt. Wenn Sie diese Probleme nicht beheben, führt dies nach der Aktivierung der V8-Laufzeit zu Fehlern oder einem fehlerhaften Skriptverhalten.
In den folgenden Abschnitten werden diese Verhaltensweisen und Schritte beschrieben, die Sie ausführen müssen, um Ihren Skriptcode während der Migration zu V8 zu korrigieren.
Auf for each(variable in object) verzichten
Die Anweisung for each (variable in object) wurde in JavaScript 1.6 hinzugefügt und zugunsten von for...of entfernt.
Verwenden Sie bei der Migration Ihres Scripts zu V8 keine for each (variable in object)-Anweisungen.
Verwenden Sie stattdessen 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); } |
Auf Date.prototype.getYear() verzichten
In der ursprünglichen Rhino-Laufzeit gibt Date.prototype.getYear() zweistellige Jahre für die Jahre von 1900 bis 1999 zurück, für andere Daten jedoch vierstellige Jahre. Dies war das Verhalten von JavaScript 1.2 und früheren Versionen.
In der V8-Laufzeit gibt Date.prototype.getYear() stattdessen das Jahr abzüglich 1900 zurück, wie es die ECMAScript-Standards erfordern.
Verwenden Sie bei der Migration Ihres Scripts zu V8 immer Date.prototype.getFullYear(), das unabhängig vom Datum eine vierstellige Jahreszahl zurückgibt.
Vermeiden Sie die Verwendung reservierter Keywords als Namen.
ECMAScript verbietet die Verwendung bestimmter reservierter Keywords in Funktions- und Variablennamen. Die Rhino-Laufzeit erlaubte viele dieser Wörter. Wenn Sie sie in Ihrem Code verwenden, müssen Sie Ihre Funktionen oder Variablen umbenennen.
Verwenden Sie beim Migrieren Ihres Scripts zu V8 keine reservierten Keywords für Variablen oder Funktionen.
Benennen Sie alle Variablen oder Funktionen um, um den Namen des Keywords zu vermeiden. Gängige Keywords für Namen sind class, import und export.
const-Variablen nicht neu zuweisen
In der ursprünglichen Rhino-Laufzeit können Sie eine Variable mit const deklarieren. Das bedeutet, dass sich der Wert des Symbols nie ändert und zukünftige Zuweisungen an das Symbol ignoriert werden.
In der neuen V8-Laufzeit ist das Schlüsselwort const standardkonform. Die Zuweisung einer Variablen, die als const deklariert ist, führt zu einem TypeError: Assignment to constant variable-Laufzeitfehler.
Versuchen Sie bei der Migration Ihres Scripts zu V8 nicht, den Wert einer const-Variablen neu zuzuweisen:
// 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 |
Vermeiden Sie XML-Literale und das XML-Objekt
Mit dieser nicht standardmäßigen Erweiterung von ECMAScript können Apps Script-Projekte die XML-Syntax direkt verwenden.
Verwenden Sie beim Migrieren Ihres Scripts zu V8 keine direkten XML-Literale oder das XML-Objekt.
Verwenden Sie stattdessen den XmlService, um XML zu parsen:
// 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 |
Benutzerdefinierte Iteratorfunktionen nicht mit __iterator__ erstellen
In JavaScript 1.7 wurde eine Funktion hinzugefügt, mit der jeder Klasse ein benutzerdefinierter Iterator hinzugefügt werden kann. Dazu wird im Prototyp der Klasse eine __iterator__-Funktion deklariert. Diese Funktion wurde auch der Rhino-Laufzeit von Apps Script hinzugefügt, um Entwicklern die Arbeit zu erleichtern. Diese Funktion war jedoch nie Teil des ECMA-262-Standards und wurde aus ECMAScript-kompatiblen JavaScript-Engines entfernt. Bei Scripts, die V8 verwenden, kann diese Iteratorkonstruktion nicht verwendet werden.
Verwenden Sie beim Migrieren Ihres Scripts zu V8 keine __iterator__-Funktion, um benutzerdefinierte Iteratoren zu erstellen. Verwenden Sie stattdessen ECMAScript 6-Iterator.
Betrachten Sie die folgende Array-Konstruktion:
// 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. |
Die folgenden Codebeispiele zeigen, wie ein Iterator in der Rhino-Laufzeit und wie ein Ersatziterator in der V8-Laufzeit erstellt werden kann:
// 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); } |
Bedingte Catch-Klauseln vermeiden
Die V8-Laufzeit unterstützt keine catch..if bedingten Catch-Klauseln, da sie nicht standardkonform sind.
Wenn Sie Ihr Skript zu V8 migrieren, verschieben Sie alle Catch-Bedingungen in den Catch-Text:
// 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 } } |
Object.prototype.toSource() vermeiden
JavaScript 1.3 enthielt die Methode Object.prototype.toSource(), die nie Teil eines ECMAScript-Standards war. Es wird in der V8-Laufzeit nicht unterstützt.
Entfernen Sie bei der Migration Ihres Scripts zu V8 alle Verwendungen von Object.prototype.toSource() aus Ihrem Code.
Weitere Unterschiede
Zusätzlich zu den oben genannten Inkompatibilitäten, die zu Scriptfehlern führen können, gibt es einige weitere Unterschiede, die bei Nichtbehebung zu unerwartetem Verhalten von V8-Laufzeitscripts führen können.
In den folgenden Abschnitten wird erläutert, wie Sie Ihren Skriptcode aktualisieren, um diese unerwarteten Überraschungen zu vermeiden.
Landesspezifische Datums- und Uhrzeitformatierung anpassen
Die Date-Methoden toLocaleString(), toLocaleDateString() und toLocaleTimeString() verhalten sich in der V8-Laufzeit anders als in Rhino.
In Rhino ist das Standardformat das long-Format. Alle übergebenen Parameter werden ignoriert.
In der V8-Laufzeit ist das Kurzformat das Standardformat und übergebene Parameter werden gemäß dem ECMA-Standard verarbeitet. Weitere Informationen finden Sie in der toLocaleDateString()-Dokumentation.
Wenn Sie Ihr Script zu V8 migrieren, testen und passen Sie die Erwartungen Ihres Codes an die Ausgabe von länderspezifischen Datums- und Uhrzeitmethoden an:
// 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' })); |
Vermeiden Sie die Verwendung von Error.fileName und Error.lineNumber
In der V8-Untime-Umgebung unterstützt das standardmäßige JavaScript-Objekt Error weder fileName noch lineNumber als Konstruktorparameter oder Objekteigenschaften.
Entfernen Sie bei der Migration Ihres Scripts zu V8 alle Abhängigkeiten von Error.fileName und Error.lineNumber.
Alternativ können Sie Error.prototype.stack verwenden.
Dieser Stack ist ebenfalls nicht standardmäßig, wird aber sowohl in Rhino als auch in V8 unterstützt. Das Format des von den beiden Plattformen erstellten Stacktrace ist etwas anders:
// 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) |
Umgang mit stringifizierten Enum-Objekten anpassen
In der ursprünglichen Rhino-Laufzeit wird bei Verwendung der JavaScript-Methode JSON.stringify() für ein Enum-Objekt nur {} zurückgegeben.
In V8 wird der Name der Aufzählung zurückgegeben, wenn die gleiche Methode für ein enum-Objekt verwendet wird.
Wenn Sie Ihr Script zu V8 migrieren, testen und passen Sie die Erwartungen Ihres Codes an die Ausgabe von JSON.stringify() auf Enum-Objekte an:
// 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" |
Handhabung nicht definierter Parameter anpassen
In der ursprünglichen Rhino-Laufzeit wurde undefined als Parameter an eine Methode übergeben, was dazu führte, dass der String "undefined" an diese Methode übergeben wurde.
In V8 entspricht die Übergabe von undefined an Methoden der Übergabe von null.
Testen und passen Sie bei der Migration Ihres Skripts zu V8 die Anforderungen Ihres Codes in Bezug auf die undefined-Parameter an:
// 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. |
Handhabung des globalen this anpassen
Die Rhino-Laufzeit definiert einen impliziten speziellen Kontext für Scripts, die sie verwenden.
Der Skriptcode wird in diesem impliziten Kontext ausgeführt, und zwar getrennt vom tatsächlichen globalen this. Das bedeutet, dass Verweise auf „global this“ im Code tatsächlich auf den speziellen Kontext ausgewertet werden, der nur den im Script definierten Code und die Variablen enthält. Die integrierten Apps Script-Dienste und ECMAScript-Objekte sind von dieser Verwendung von this ausgenommen. Diese Situation ähnelte dieser JavaScript-Struktur:
// 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. }(); |
In V8 wird der implizite spezielle Kontext entfernt. Im Script definierte globale Variablen und Funktionen werden neben den integrierten Apps Script-Diensten und ECMAScript-Einbauten wie Math und Date in den globalen Kontext eingefügt.
Wenn Sie Ihr Script zu V8 migrieren, testen und passen Sie die Erwartungen Ihres Codes an die Verwendung von this in einem globalen Kontext an. In den meisten Fällen sind die Unterschiede nur dann sichtbar, wenn der Code die Schlüssel oder Attributnamen des globalen this-Objekts untersucht:
// 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)); } |
Umgang mit instanceof in Bibliotheken anpassen
Wenn Sie instanceof in einer Bibliothek auf einem Objekt verwenden, das als Parameter in einer Funktion aus einem anderen Projekt übergeben wird, kann es zu Falsch-Negativ-Ergebnissen kommen. In der V8-Laufzeit werden ein Projekt und seine Bibliotheken in unterschiedlichen Ausführungskontexten ausgeführt und haben daher unterschiedliche Globales und Prototypenketten.
Dies ist nur der Fall, wenn Ihre Bibliothek instanceof für ein Objekt verwendet, das nicht in Ihrem Projekt erstellt wurde. Die Verwendung auf einem Objekt, das in Ihrem Projekt erstellt wird, sei es im selben oder in einem anderen Script in Ihrem Projekt, sollte wie erwartet funktionieren.
Wenn Ihr Script in einem Projekt verwendet wird, das unter V8 ausgeführt wird, prüfen Sie, ob in Ihrem Script instanceof für einen Parameter verwendet wird, der von einem anderen Projekt übergeben wird. Passen Sie die Verwendung von instanceof an und verwenden Sie je nach Anwendungsfall andere praktikable Alternativen.
Eine Alternative für a instanceof b ist der Konstruktor von a, wenn Sie nicht die gesamte Prototypkette durchsuchen, sondern nur den Konstruktor prüfen möchten.
Nutzung: a.constructor.name == "b"
Angenommen, Projekt A verwendet Projekt B als Bibliothek.
//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 } |
Eine weitere Alternative kann die Einführung einer Funktion sein, die instanceof im Hauptprojekt prüft und die Funktion beim Aufrufen einer Bibliotheksfunktion zusätzlich zu anderen Parametern übergibt. Mit der übergebenen Funktion kann dann instanceof in der Bibliothek geprüft werden.
//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); } |
Weitergabe nicht freigegebener Ressourcen an Bibliotheken anpassen
Das Übergeben einer nicht freigegebenen Ressource aus dem Hauptscript an eine Bibliothek funktioniert in der V8-Laufzeit anders.
In der Rhino-Laufzeit funktioniert das Übergeben einer nicht freigegebenen Ressource nicht. Die Bibliothek verwendet stattdessen eine eigene Ressource.
In der V8-Laufzeit funktioniert das Übergeben einer nicht freigegebenen Ressource an die Bibliothek. Die Bibliothek verwendet die übergebene nicht freigegebene Ressource.
Übergeben Sie keine nicht freigegebenen Ressourcen als Funktionsparameter. Deklarieren Sie nicht freigegebene Ressourcen immer in dem Script, in dem sie verwendet werden.
Nehmen wir als Beispiel Projekt A und Projekt B, bei dem Projekt A Projekt B als Bibliothek verwendet. In diesem Beispiel ist PropertiesService eine nicht freigegebene Ressource.
// 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')); } |
Zugriff auf eigenständige Scripts aktualisieren
Bei eigenständigen Skripts, die in der V8-Laufzeit ausgeführt werden, müssen Sie Nutzern mindestens Lesezugriff auf das Skript gewähren, damit die Trigger des Skripts ordnungsgemäß funktionieren.