建構指令碼

Blockly 由超過一百個 TypeScript 檔案組成。這些檔案必須先由 TypeScript 編譯器 tsc 編譯為 JavaScript，才能使用。這會產生同樣大量的 .js 檔案，適合用於本機測試，但透過網際網路載入這麼多檔案時，終端使用者會覺得速度緩慢。為加快 Blockly 的載入速度，我們使用 Closure 編譯器壓縮 (縮小) 這些檔案，並將其合併為六個檔案 (「套件」或「區塊」)，總大小不到未壓縮檔案的一半。

在此過程中，使用最新 ECMAScript 功能的程式碼 (可能與部分瀏覽器不相容) 會轉譯為 ES6，這通常與最常用的瀏覽器相容。因此，請務必只向使用者提供縮減後的程式碼。

google/blockly 存放區只包含原始碼。先前也包含建構產品，但自 2019 年起，縮小後的套件已發布為 blockly NPM 套件，且自 2022 年起，也以 .tgz 檔案形式附加至每個 GitHub 版本，因此除非您要修改 Blockly 本身 (特別是 core、blocks、generators 或 msg 目錄中的檔案)，否則不需要建構 Blockly。

建構、測試及發布 Blockly 的程序會使用 npm 指令碼自動執行，以執行 Gulp 工作。本頁面記錄主要指令碼和各項指令碼的用途。

壓縮和未壓縮模式

直接從 TypeScript 編譯器產生的個別 .js 檔案載入 Blockly，稱為「未壓縮模式」。由於可避免多個緩慢的建構步驟，因此有助於快速進行編輯、編譯及執行週期；此外，由於執行的 JavaScript 程式碼幾乎與原始 TypeScript 來源一樣容易閱讀，因此也有助於偵錯，不必依賴來源對應。

從縮小組合載入 Blockly 稱為「壓縮模式」。這是測試 Blockly 變更的最佳方式，因為 Blockly 是另一個套件的依附元件，而且會測試 (未發布的) blockly npm 套件。

N.B.: 在 Blockly 存放區中，有幾個地方會將「未編譯模式」和「已編譯模式」分別當做「未壓縮模式」和「已壓縮模式」的同義詞。過去使用這個詞彙很合理，因為 Closure 編譯器會壓縮 (縮小) 程式碼，但現在即使在未壓縮模式下，也一律需要 TypeScript 編譯器，因此這個替代詞彙可能會造成混淆，建議不要使用。

快速入門

  • 如果您已進行本機變更，並想確認這些變更是否未中斷建構或任何測試，請執行

    npm test

    建構 Blockly 並執行測試套件。

  • 如要在瀏覽器中測試本機變更，請執行

    npm start

    這會編譯 Blockly，並開啟網路瀏覽器，指向以未壓縮模式執行 Blockly 的 Blockly 測試區。

    系統會自動重新編譯 core/、blocks/ 和 generators/ 中修改的檔案；重新載入瀏覽器分頁即可查看變更。

  • 如要建構並測試您在本機修改的 Blockly 版本，請以壓縮模式將其做為另一個 npm 套件的依附元件，然後執行

    npm run package

    建構 Blockly 套件，然後

    cd dist && npm link

    ，告訴 npm 編譯後的檔案位置，然後在執行cd

    npm link blockly

    讓套件使用新編譯的 Blockly 版本，取代已發布的 blockly 套件。

詳細指令碼參考資料

本節列出 Blockly package.json 檔案中的主要 scripts，並說明其用途。

這些指令碼會在兩個位置產生檔案：

  • build/ 子目錄中的檔案是中介檔案，用於本機測試，或由建構管道的後續部分擷取。
  • dist/ 子目錄中的檔案會構成發布的 npm 套件內容。

blockly git 存放區不會追蹤這兩個目錄。

clean

npm run clean 會刪除 build/ 和 dist/ 目錄，清除先前的所有建構作業。有助於修正神秘的建構失敗問題，特別是因重新命名來源檔案而導致的問題。

messages

npm run messages 會根據 msg/messages.js 的變更，更新 msg/json/ 中的訊息檔案，因此每次修改該檔案後，都應執行這項指令。

langfiles

npm run langfiles 會從 msg/json 中的訊息檔案，在 build/msg/ 中產生已編譯的語言檔案。

tsc

npm run tsc 會對 core/、blocks/ 和 generators/ 目錄的內容執行 TypeScript 編譯器，並將個別 .js 檔案輸出至 build/src/。

minify

npm run minify 會執行 closure-make-deps 和 closure-calculate-chunks，判斷如何將編譯的 .js 檔案分割成區塊 (縮小的套件)，然後執行 closure-compiler 來建立區塊，如下所示：

  • build/src/core/ 的內容會變成 dist/blockly_compressed.js。
  • build/src/blocks/ 的內容會變成 dist/blocs_compressed.js。
  • build/src/generators/javascript/ (加上 build/src/generators/javascript.js) 的內容會變成 dist/javascript_compressed.js。
  • dart、lua、php 和 python 也比照完成同樣的處理。

產生的區塊會使用包裝函式，確保與通用模組定義相容，因此納入套件前不需額外處理。

build

npm run build 會執行 minify 和 langfiles 工作。這應該會完成所有必要作業，以便在壓縮或未壓縮模式中載入 Blockly 操場。

package

npm run package 會執行 clean 和 build 工作，然後：

  • 將 UMD 包裝函式套用至 build/msg/ 中的檔案，並將包裝後的版本放在 dist/msg/ 中。
  • 將各種額外的支援檔案新增至 dist/，並視情況加入 UMD 包裝函式。

publish

Blockly 團隊會使用 npm run publish 發布 blockly npm 套件。這項功能取決於 Google 內部基礎架構，因此對外部開發人員沒有用處。

lint

npm run lint 會執行 ESLint，對 Blockly 原始碼進行靜態分析，找出問題。

test

npm test (或 npm run test) 會執行 package 工作，然後執行各種自動化測試 (包括執行 ESLint)。針對 Blockly 存放區以提取要求形式提交的任何程式碼，都應執行並通過這項測試。