Tworzenie skryptów

Blockly składa się z ponad 100 plików TypeScript. Muszą one zostać skompilowane przez kompilator TypeScriptu tsc do JavaScriptu, zanim będzie można ich użyć. Powoduje to utworzenie równie dużej liczby plików .js, które nadają się do testowania lokalnego, ale wczytywanie tak dużej liczby plików przez internet jest dla użytkowników powolne. Aby przyspieszyć wczytywanie Blockly, używamy kompilatora Closure, który kompresuje (minimalizuje) i łączy pliki w kilka plików („pakietów” lub „fragmentów”) o łącznym rozmiarze mniejszym niż połowa rozmiaru nieskompresowanych plików.

W tym procesie kod korzystający z najnowszych funkcji ECMAScript, które mogą nie być zgodne ze wszystkimi przeglądarkami, jest transpilowany do ES6, który jest ogólnie zgodny z najczęściej używanymi przeglądarkami. Dlatego ważne jest, aby użytkownikom udostępniać tylko zminimalizowany kod.

Repozytorium RaspberryPiFoundation/blockly zawiera tylko kod źródłowy. Wcześniej zawierało ono również produkty kompilacji, ale od 2019 r. zminimalizowane pakiety są publikowane jako pakiet NPM blockly, a od 2022 r. są też dołączane jako plik .tgz do każdej wersji w GitHubie. Nie ma więc potrzeby kompilowania Blockly, chyba że chcesz zmodyfikować samą bibliotekę, a w szczególności pliki w katalogach core, blocks, generators lub msg.

Proces kompilowania, testowania i publikowania Blockly jest zautomatyzowany za pomocą skryptów npm, które uruchamiają zadania Gulp. Na tej stronie znajdziesz informacje o głównych skryptach i ich działaniu.

Tryb skompresowany i nieskompresowany

Ładowanie Blockly bezpośrednio z poszczególnych plików .js wygenerowanych przez kompilator TypeScriptu jest nazywane „trybem nieskompresowanym”. Unika on kilku powolnych etapów kompilacji, co ułatwia szybki cykl edytowania, kompilowania i uruchamiania. Ułatwia też debugowanie, ponieważ wykonywany kod JavaScript jest prawie tak czytelny jak oryginalne źródła TypeScript, co eliminuje konieczność korzystania z map źródłowych.

Ładowanie Blockly ze zminimalizowanych pakietów jest nazywane „trybem skompresowanym”. To najlepszy sposób na testowanie zmian w Blockly, gdy jest on używany jako zależność innego pakietu, ponieważ testuje (nieopublikowaną wersję) blocklypakietu npm.

N.B.: W repozytorium Blockly w niektórych miejscach terminy „tryb nieskompilowany” i „tryb skompilowany” są używane jako synonimy odpowiednio terminów „tryb nieskompresowany” i „tryb skompresowany”. W przeszłości miało to sens, ponieważ kompilator Closure służył do kompresowania (minimalizowania) kodu, ale teraz kompilator TypeScript jest zawsze potrzebny, nawet w trybie nieskompresowanym, więc ta alternatywna terminologia może być myląca i jest odradzana.

Szybki start

  • Jeśli wprowadzisz lokalne zmiany i chcesz się upewnić, że nie spowodowały one błędów w kompilacji ani w testach, uruchom

    npm test

    aby skompilować Blockly i uruchomić jego pakiet testów.

  • Jeśli chcesz przetestować lokalne zmiany w przeglądarce, uruchom

    npm start

    Spowoduje to skompilowanie Blockly i otwarcie przeglądarki internetowej wskazującej na plac zabaw Blockly, na którym Blockly działa w trybie nieskompresowanym.

    Wszelkie zmodyfikowane pliki w folderach core/, blocks/ i generators/ są automatycznie ponownie kompilowane. Aby zobaczyć zmiany, ponownie wczytaj kartę przeglądarki.

  • Aby skompilować lokalnie zmodyfikowaną wersję Blockly i przetestować ją w trybie skompresowanym jako zależność innego pakietu npm, uruchom

    npm run package

    aby utworzyć pakiet Blockly, a następnie

    cd dist && npm link

    aby poinformować npm, gdzie znajdują się skompilowane pliki, a następnie cd do katalogu projektu przed uruchomieniem

    npm link blockly

    aby pakiet korzystał z nowo skompilowanej wersji Blockly zamiast opublikowanego pakietu blockly.

Szczegółowe materiały referencyjne dotyczące skryptu

W tej sekcji znajdziesz listę głównych scripts w pliku package.json Blockly wraz z wyjaśnieniem ich działania.

Skrypty te generują pliki w 2 miejscach:

  • Pliki w podkatalogu build/ to pliki pośrednie używane do testowania lokalnego lub wczytywane przez późniejsze części potoku kompilacji.
  • Pliki w podkatalogu dist/ stanowią zawartość opublikowanego pakietu npm.

Żaden z tych katalogów nie jest śledzony w repozytorium git Blockly.

clean

npm run clean usuwa poprzednie kompilacje, usuwając katalogi build/ i dist/. Przydatne do naprawiania skomplikowanych błędów kompilacji, zwłaszcza tych spowodowanych zmianą nazwy pliku źródłowego.

messages

npm run messages aktualizuje pliki wiadomości w msg/json/ o wszelkie zmiany wprowadzone w msg/messages.js. Należy go uruchamiać po każdej modyfikacji tego pliku.

langfiles

npm run langfiles generuje skompilowane pliki językowe w folderze build/msg/ na podstawie plików z wiadomościami w folderze msg/json.

tsc

npm run tsc uruchamia kompilator TypeScript na zawartości katalogów core/,blocks/ i generators/ oraz zapisuje poszczególne pliki .js w katalogu build/src/.

minify

npm run minify uruchamia closure-make-deps i closure-calculate-chunks, aby określić, jak podzielić skompilowane pliki .js na części (zminimalizowane pakiety), a następnie uruchamia closure-compiler, aby utworzyć części w ten sposób:

  • Zawartość build/src/core/ staje się dist/blockly_compressed.js.
  • Zawartość build/src/blocks/ staje się dist/blocs_compressed.js.
  • Zawartość build/src/generators/javascript/ (plus build/src/generators/javascript.js) staje się dist/javascript_compressed.js.
  • To samo dotyczy błędów dart, lua, php i python.

Wygenerowane pliki chunk używają otoczki, która zapewnia zgodność z definicją modułu uniwersalnego, więc przed włączeniem ich do pakietu nie jest wymagane żadne dodatkowe przetwarzanie.

build

npm run build uruchamia zadania minify i langfiles. Powinno to zrobić wszystko, co jest potrzebne do wczytania placu zabaw Blockly w trybie skompresowanym lub nieskompresowanym.

package

npm run package uruchamia zadania clean i build, a następnie:

  • Stosuje otoczkę UMD do plików w build/msg/ i umieszcza otoczone wersje w dist/msg/.
  • Dodaje różne dodatkowe pliki pomocnicze do dist/, z otoczkami UMD w odpowiednich przypadkach.

publish

npm run publish jest używany przez zespół Blockly do publikowania blocklypakietu npmblockly. Korzysta z infrastruktury wewnętrznej Google, więc nie jest przydatny dla deweloperów zewnętrznych.

lint

npm run lint uruchamia ESLint, przeprowadzając statyczną analizę kodu źródłowego Blockly w celu znalezienia problemów.

test

npm test (lub npm run test) wykonuje zadanie package, a następnie przeprowadza różne testy automatyczne (w tym ESLint). Należy go uruchomić i sprawdzić w przypadku każdego kodu przesłanego jako żądanie wycofania zmian w repozytorium Blockly.