Blockly 由超過一百種 TypeScript 檔案組成。這些程式碼必須先由 TypeScript 編譯器 tsc
編譯為 JavaScript,才能使用。這會建立大量適合本機測試的 .js
檔案,但透過網際網路載入這類大量檔案,對使用者而言是順暢無礙的體驗。為了加快 Blockly 的載入速度,系統會使用 Closure Compiler 來壓縮 (縮小) 並將檔案合併為半個檔案 (「套裝組合」或「區塊」),總大小少於未壓縮檔案的一半。
在過程中,如果程式碼使用最新的 ECMAScript 功能 (可能與所有瀏覽器不相容),則會轉換為 ES6,這大致上與大多數最常用的瀏覽器相容。因此,請務必只為使用者提供壓縮的程式碼。
google/blockly 存放區只包含原始碼。先前也包含建構產品,但自 2019 年起,壓縮的套件已以 blockly
NPM 套件的形式發布,自 2022 年起,也以 .tgz
檔案的形式附加至每個 GitHub 版本,因此除非您已遭到入侵 (尤其是 core
、blocks
、generators
或 msg
目錄中的檔案),否則不必建構 Blockly。
使用 npm 指令碼執行 Gulp 工作,自動執行建構、測試和發布 Blockly 的程序。本頁面記錄了原理指令碼和分別的作用。
壓縮與未壓縮模式
直接從 TypeScript 編譯器產生的個別 .js
檔案載入 Blockly,此模式稱為「未壓縮模式」。這可避免數個緩慢的建構步驟,因此有助於快速編輯編譯執行週期;也有助於偵錯,因為執行的 JavaScript 程式碼幾乎與原始 TypeScript 來源一樣可讀取,因此您不必依賴來源對應。
從壓縮的套件載入區塊稱為「壓縮模式」。
當您將其做為另一個套件的依附元件使用時,這是測試 Blockly 變更的最佳方式,因為這個套件會測試 blockly
npm 套件 (未發布的版本)。
N.B.: 區塊存放區中有些地方會分別使用「未編譯模式」和「編譯模式」這兩個字詞,做為「未壓縮模式」和「壓縮模式」的同義詞。這種使用方法過去十分合理,因為 Closure Compiler 之前曾用來壓縮 (縮小) 程式碼,但現在即使在未壓縮模式下,也需要 TypeScript 編譯器,因此這個替代術語可能會令人混淆並不建議使用。
快速啟動
如果您已進行本機變更,且想確保這些變更並未損毀版本或任何測試,請執行
npm test
建構 Blockly 並執行測試套件
如要在瀏覽器中測試本機變更,請執行
npm start
這會編譯 Blockly,並開啟網路瀏覽器,指向在未壓縮模式下執行的 Blockly Playground。
系統會自動重新編譯
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 套件的內容,
在區塊化 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 Play 所需的所有操作。
package
npm run package
會執行 clean
和 build
工作,然後:
- 會在
build/msg/
中套用 UMD 包裝函式,將包裝過的版本放在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。這項作業應該在提交至區塊存放區的提取要求時執行 (並傳遞)。