Blockly besteht aus über hundert TypeScript-Dateien. Diese müssen vom TypeScript-Compiler tsc
in JavaScript kompiliert werden, bevor sie verwendet werden können. Dadurch wird eine ähnlich große Anzahl von .js
-Dateien erstellt, die für lokale Tests geeignet sind. Das Laden einer so großen Anzahl von Dateien über das Internet ist jedoch für Endnutzer sehr mühsam. Damit Blockly schneller geladen wird, wird der Closure Compiler verwendet, um sie zu komprimieren (minimieren) und zu einem halben Dutzend Dateien ("Bundles" oder "Chunks") mit einer Gesamtgröße von weniger als der Hälfte der nicht komprimierten Dateien zusammenzufassen.
Dabei wird Code mit den neuesten ECMAScript-Funktionen – die möglicherweise nicht mit allen Browsern kompatibel sind – in ES6 umgewandelt, das im Allgemeinen mit den gängigsten Browsern kompatibel ist. Daher ist es wichtig, dass Sie Ihren Endnutzern nur den minimierten Code bereitstellen.
Das google/blockly-Repository enthält nur den Quellcode. Sie enthielt zuvor auch die Build-Produkte. Seit 2019 wurden die reduzierten Bundles jedoch als blockly
-NPM-Paket veröffentlicht und seit 2022 auch als .tgz
-Datei an jeden GitHub-Release angehängt. Es ist also nicht erforderlich, Blockly zu erstellen, es sei denn, Sie hacken auf Blockly selbst, insbesondere bei Dateien in den Verzeichnissen core
, blocks
, generators
oder msg
.
Das Erstellen, Testen und Veröffentlichen von Blockly wird mithilfe von npm-Skripts automatisiert, um Gulp-Aufgaben auszuführen. Auf dieser Seite werden die Hauptskripts und ihre Funktion dokumentiert.
Komprimierter und unkomprimierter Modus
Das Laden von Blockly direkt aus den einzelnen .js
-Dateien, die vom TypeScript-Compiler generiert wurden, wird als „unkomprimierter Modus“ bezeichnet. Da mehrere langsame Build-Schritte vermieden werden, wird ein schneller Zyklus des Bearbeitens, Kompilierens und Ausführens erleichtert. Außerdem wird die Fehlerbehebung erleichtert, da der ausgeführte JavaScript-Code fast so lesbar ist wie die ursprünglichen TypeScript-Quellen, wodurch die Notwendigkeit von Sourcemaps überflüssig wird.
Das Laden von Blockly aus den reduzierten Bundles wird als „komprimierter Modus“ bezeichnet.
Dies ist die beste Methode, um Änderungen an Blockly zu testen, wenn es als Abhängigkeit eines anderen Pakets verwendet wird, weil das npm-Paket blockly
(eine unveröffentlichte Version) getestet wird.
N.B.: Im blockly Repository gibt es einige Stellen, an denen die Begriffe „nicht kompilierter Modus“ und „kompilierter Modus“ als Synonyme für „unkomprimierter Modus“ bzw. „komprimierter Modus“ verwendet werden. In der Vergangenheit war diese Verwendung sinnvoll, da Closure Compiler zum Komprimieren (Minify) des Codes verwendet wurde. Jetzt wird jedoch der TypeScript-Compiler immer benötigt, auch im unkomprimierten Modus, sodass diese alternative Terminologie möglicherweise verwirrend ist und nicht empfohlen wird.
Schnellstart
Wenn Sie lokale Änderungen vorgenommen haben und sicherstellen möchten, dass der Build oder Tests dadurch nicht beeinträchtigt werden, führen Sie folgenden Befehl aus:
npm test
um Blockly zu erstellen und seine Testsuite auszuführen.
Wenn Sie lokale Änderungen im Browser testen möchten, führen Sie den folgenden Befehl aus:
npm start
Dadurch wird Blockly kompiliert und ein Webbrowser geöffnet, der auf den Blockly Playground verweist, der Blockly im unkomprimierten Modus ausführt.
Alle geänderten Dateien in
core/
,blocks/
undgenerators/
werden automatisch neu kompiliert. Laden Sie den Browsertab neu, um die Änderungen zu sehen.Um Ihre lokal geänderte Version von Blockly zu erstellen und als Abhängigkeit eines anderen npm-Pakets im komprimierten Modus zu testen, führen Sie folgenden Befehl aus:
npm run package
um das Blockly-Paket zu erstellen,
cd dist && npm link
um npm anzuweisen, wo die kompilierten Dateien zu finden sind, und dann vor der Ausführung mit
cd
in das Verzeichnis Ihres Projekts wechseln.npm link blockly
, damit Ihr Paket die neu kompilierte Version von Blockly anstelle des veröffentlichten
blockly
-Pakets verwendet.
Detaillierte Skriptreferenz
In diesem Abschnitt wird das Prinzip scripts
in der package.json
-Datei von Blockly aufgeführt und seine Funktion wird erläutert.
Diese Skripts generieren Dateien an zwei Orten:
- Dateien im Unterverzeichnis
build/
sind Zwischendateien, die für lokale Tests verwendet oder von späteren Teilen der Build-Pipeline aufgenommen werden. - Dateien im Unterverzeichnis
dist/
bilden den Inhalt des veröffentlichten npm-Pakets.
Keines der beiden Verzeichnisse wird im blockly-Git-Repository erfasst.
clean
npm run clean
bereinigt alle vorherigen Builds, indem die Verzeichnisse build/
und dist/
gelöscht werden. Nützlich zum Beheben von schwerwiegenden Build-Fehlern, insbesondere solchen, die durch das Umbenennen einer Quelldatei verursacht werden.
messages
npm run messages
aktualisiert die Nachrichtendateien in msg/json/
mit allen an msg/messages.js
vorgenommenen Änderungen und sollte jedes Mal ausgeführt werden, wenn diese Datei geändert wird.
langfiles
npm run langfiles
generiert die kompilierten Sprachdateien in build/msg/
aus den Nachrichtendateien in msg/json
.
tsc
npm run tsc
führt den TypeScript-Compiler für die Inhalte der Verzeichnisse core/
, blocks/
und generators/
aus und gibt einzelne .js
-Dateien in build/src/
aus.
minify
npm run minify
führt closure-make-deps
und closure-calculate-chunks
aus, um zu bestimmen, wie die kompilierten .js
-Dateien in Blöcke (minimierte Bundles) aufgeteilt werden sollen. Anschließend wird closure-compiler
ausgeführt, um die Blöcke wie folgt zu erstellen:
- Der Inhalt von
build/src/core/
wird zudist/blockly_compressed.js
. - Der Inhalt von
build/src/blocks/
wird zudist/blocs_compressed.js
. - Der Inhalt von
build/src/generators/javascript/
(plusbuild/src/generators/javascript.js
) wird zudist/javascript_compressed.js
. - Dasselbe gilt für
dart
,lua
,php
undpython
.
Die generierten Chuks verwenden einen Wrapper, um die Kompatibilität mit der universellen Moduldefinition zu gewährleisten, sodass keine zusätzliche Verarbeitung erforderlich ist, bevor sie in das Paket aufgenommen werden.
build
npm run build
führt die Aufgaben minify
und langfiles
aus. Damit sollte alles erledigt werden, was zum Laden des Blockly-Playgrounds im komprimierten oder unkomprimierten Modus erforderlich ist.
package
npm run package
führt die Aufgaben clean
und build
aus und führt dann folgende Schritte aus:
- Wendet einen UMD-Wrapper auf die Dateien in
build/msg/
an und platziert die umschlossenen Versionen indist/msg/
. - Fügt
dist/
verschiedene zusätzliche Supportdateien mit UMD-Wrappern hinzu, sofern zutreffend.
publish
npm run publish
wird vom Blockly-Team verwendet, um das npm-Paket blockly
zu veröffentlichen. Es hängt von der Google-internen Infrastruktur ab und ist daher für externe Entwickler nicht hilfreich.
lint
npm run lint
führt ESLint aus und führt eine statische Analyse des Blockly-Quellcodes durch, um Probleme zu finden.
test
npm test
(oder npm run test
) führt die Aufgabe package
und dann verschiedene automatisierte Tests (einschließlich ESLint) aus. Dies sollte für jeden Code ausgeführt und übergeben werden, der als Pull-Anfrage an das blockly Repository gesendet wird.