Wenn Sie ein Script haben, das die Rhino-Laufzeit verwendet, und die V8-Syntax und ‐Funktionen nutzen möchten, müssen Sie das Script zu V8 migrieren.
Die meisten Skripts, die mit der Rhino-Laufzeit geschrieben werden, können mit einer V8-Laufzeit ohne Anpassung 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 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 Skript zu V8:
- Aktivieren Sie die V8-Laufzeit für das Skript.
- Prüfen Sie sorgfältig die unten aufgeführten Inkompatibilitäten. Prüfen Sie Ihr Skript, um festzustellen, ob eine der Inkompatibilitäten vorliegt. Wenn eine oder mehrere Inkompatibilitäten vorhanden sind, passen Sie den Skriptcode an, um das Problem zu entfernen oder zu vermeiden.
- Prüfen Sie sorgfältig die anderen Unterschiede, die unten aufgeführt sind. Überprüfen Sie Ihr Skript, um festzustellen, ob sich einer der aufgeführten Unterschiede auf das Verhalten Ihres Codes auswirkt. Passen Sie das Skript an, um das Verhalten zu korrigieren.
- Nachdem Sie alle erkannten Inkompatibilitäten oder anderen Unterschiede korrigiert haben, können Sie damit beginnen, Ihren Code so zu aktualisieren, dass er die V8-Syntax und andere Funktionen wie gewünscht verwendet.
- Testen Sie Ihr Skript nach Ihren Codeanpassungen gründlich, um zu prüfen, ob es erwartungsgemäß funktioniert.
- Wenn das Skript eine Webanwendung oder ein veröffentlichtes Add-on ist, müssen Sie mit den V8-Anpassungen eine neue Version des Skripts erstellen. Um die V8-Version für Nutzer verfügbar zu machen, müssen Sie das Skript 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 standardkonform ist, wird dieses Verhalten 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 zu JavaScript 1.6 hinzugefügt und zugunsten von for...of entfernt.
Vermeiden Sie bei der Migration Ihres Skripts zu V8 die Verwendung von 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() gemäß ECMAScript-Standards stattdessen das Jahr minus 1.900 zurück.
Verwenden Sie bei der Migration Ihres Scripts zu V8 immer Date.prototype.getFullYear(), das unabhängig vom Datum ein vierstelliges Jahr zurückgibt.
Reservierte Keywords nicht als Namen verwenden
ECMAScript untersagt die Verwendung bestimmter reservierter Schlüsselwörter in Funktions- und Variablennamen. In der Rhino-Laufzeit waren viele dieser Wörter zulässig. Wenn sie in Ihrem Code verwendet werden, müssen Sie daher Ihre Funktionen oder Variablen umbenennen.
Wenn Sie Ihr Script zu V8 migrieren, sollten Sie Variablen oder Funktionen nicht mit einem der reservierten Keywords benennen.
Benennen Sie eine Variable oder Funktion um, damit der Keyword-Name nicht verwendet wird. In Namen werden häufig Keywords wie class, import und export verwendet.
Vermeiden Sie es, const-Variablen neu zuzuweisen
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 zum 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 Skripts 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
|
XML-Literale und XML-Objekt vermeiden
Durch diese nicht standardmäßige Erweiterung für ECMAScript können Apps Script-Projekte die XML-Syntax direkt verwenden.
Vermeiden Sie bei der Migration Ihres Skripts zu V8 direkte XML-Literale oder das XML-Objekt.
Verwenden Sie stattdessen XmlService zum Parsen von 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
|
Keine benutzerdefinierten Iterator-Funktionen mit __iterator__ erstellen
In JavaScript 1.7 wurde eine Funktion hinzugefügt, die es ermöglicht, beliebigen Klassen einen benutzerdefinierten Iterator hinzuzufügen, indem eine __iterator__-Funktion im Prototyp dieser Klasse deklariert wird. Diese Funktion wurde auch zur Rhino-Laufzeit von Apps Script hinzugefügt, um Entwickler zu erleichtern. Diese Funktion war jedoch nie Teil des ECMA-262-Standards und wurde in ECMAScript-kompatiblen JavaScript-Engines entfernt. Skripte, die V8 nutzen, können diese Iterator-Konstruktion nicht verwenden.
Vermeiden Sie bei der Migration Ihres Skripts zu V8 die Funktion __iterator__, um benutzerdefinierte Iteratoren zu erstellen. Verwenden Sie stattdessen ECMAScript 6-Iteratoren.
Betrachten Sie die folgende Arraykonstruktion:
// 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 erstellt werden kann und wie Sie einen Ersatz-Iterator in der V8-Laufzeit erstellen:
// 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 bedingten Catch-catch..if-Klauseln, da diese 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 eine Methode Object.prototype.toSource(), die nie Teil eines ECMAScript-Standards war. Es wird in der V8-Laufzeit nicht unterstützt.
Wenn Sie Ihr Skript zu V8 migrieren, dürfen Sie Object.prototype.toSource() nicht aus Ihrem Code verwenden.
Weitere Unterschiede
Zusätzlich zu den oben genannten Inkompatibilitäten, die zu Skriptfehlern führen können, gibt es ein paar weitere Unterschiede, die zu unerwartetem Verhalten des V8-Laufzeitskripts führen können, wenn sie nicht korrigiert werden.
In den folgenden Abschnitten wird erläutert, wie Sie Ihren Skriptcode aktualisieren, um diese unerwarteten Überraschungen zu vermeiden.
Sprachspezifische Datums- und Uhrzeitformatierung anpassen
Die Date-Methoden toLocaleString(), toLocaleDateString() und toLocaleTimeString() verhalten sich in der V8-Laufzeit anders als die Rhino-Methoden.
In Rhino ist das Standardformat das long-Format. Alle übergebenen Parameter werden ignoriert.
In der V8-Laufzeit ist das Standardformat das Kurzformat und die übergebenen Parameter werden nach dem ECMA-Standard gehandhabt. Weitere Informationen finden Sie in der Dokumentation zu toLocaleDateString().
Testen und passen Sie bei der Migration Ihres Skripts zu V8 die Anforderungen Ihres Codes in Bezug auf die Ausgabe landesspezifischer 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' }));
|
Error.fileName und Error.lineNumber vermeiden
In der V8-Untime unterstützt das standardmäßige JavaScript-Objekt Error fileName oder lineNumber nicht als Konstruktorparameter oder Objekteigenschaften.
Entfernen Sie bei der Migration Ihres Skripts zu V8 die Abhängigkeit von Error.fileName und Error.lineNumber.
Alternativ können Sie Error.prototype.stack verwenden.
Dieser Stack ist ebenfalls kein Standard, 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)
|
Handhabung von 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.
Testen Sie bei der Migration Ihres Skripts zu V8 die Anforderungen Ihres Codes hinsichtlich der Ausgabe von JSON.stringify() für Enum-Objekte:
// 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 führte die Übergabe von undefined als Parameter an eine Methode zur Übergabe des Strings "undefined" an diese Methode.
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 Skripts, die ihn verwenden.
Der Skriptcode wird in diesem impliziten Kontext ausgeführt, und zwar getrennt vom tatsächlichen globalen this. Das bedeutet, dass Verweise auf das „globale this“ im Code tatsächlich im speziellen Kontext ausgewertet werden, der nur den im Skript definierten Code und die Variablen enthält. Die integrierten Apps Script-Dienste und ECMAScript-Objekte sind von der Verwendung von this ausgeschlossen. Diese Situation sah in etwa
dieser JavaScript-Struktur aus:
// 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 Spezialkontext entfernt. Globale Variablen und Funktionen, die im Skript definiert sind, werden im globalen Kontext neben den integrierten Apps Script-Diensten und ECMAScript-Integrationen wie Math und Date platziert.
Wenn du dein Script zu V8 migrierst, solltest du die Anforderungen deines Codes in Bezug auf die Verwendung von this in einem globalen Kontext testen und anpassen. 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));
}
|
Verarbeitung von instanceof in Bibliotheken anpassen
Die Verwendung von instanceof in einer Bibliothek für ein Objekt, das als Parameter in einer Funktion aus einem anderen Projekt übergeben wird, kann zu falsch negativen Ergebnissen führen. 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. Wenn Sie es für ein Objekt verwenden, das in Ihrem Projekt erstellt wurde, sollte dies wie erwartet funktionieren. Dies kann im selben oder in einem anderen Skript innerhalb Ihres Projekts erfolgen.
Wenn Ihr Skript in einem Projekt, das mit V8 ausgeführt wird, als Bibliothek verwendet wird, prüfen Sie, ob es instanceof für einen Parameter verwendet, der von einem anderen Projekt übergeben wird. Passen Sie die Verwendung von instanceof an und verwenden Sie je nach Anwendungsfall andere mögliche Alternativen.
Eine Alternative für a instanceof b kann die Verwendung des Konstruktors von a sein, wenn Sie nicht die gesamte Prototypkette durchsuchen und nur den Konstruktor prüfen müssen.
Nutzung: a.constructor.name == "b"
Nehmen wir als Beispiel Projekt A und Projekt B, bei dem Projekt A Projekt B als Bibliothek verwendet.
//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);
}
|
Übergabe nicht freigegebener Ressourcen an Bibliotheken anpassen
Das Übergeben einer nicht freigegebenen Ressource vom Hauptskript an eine Bibliothek funktioniert in der V8-Laufzeit anders.
In der Rhino-Laufzeit funktioniert die Übergabe 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 nicht freigegebene Ressourcen nicht als Funktionsparameter. Deklarieren Sie nicht freigegebene Ressourcen immer in dem Skript, 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 Skripts 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.