Blockly 由一百多个 TypeScript 文件组成。这些内容必须先由 TypeScript 编译器 tsc
编译为 JavaScript,然后才能使用。这会创建同样大量的适合本地测试的 .js
文件,但通过互联网加载如此大量的文件会让最终用户体验非常迟缓。为提高 Blockly 加载速度,系统会使用 Closure Compiler 进行压缩(缩减)并将它们合并为六个文件(“软件包”或“区块”),且总大小小于未压缩文件的一半。
在这个过程中,使用最新 ECMAScript 功能的代码(这些功能可能并非与所有浏览器都兼容)会转译到 ES6,后者通常与大多数广泛使用的浏览器兼容。因此,请务必仅向最终用户提供经过简化的代码。
google/blockly 代码库中只包含源代码。此版本之前也包含 build 产品,但自 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.: 在块代码库中的某些位置,术语“未编译模式”和“编译模式”分别用作“未压缩模式”和“压缩模式”的同义词。这种用法过去很合理,因为 Closure Compiler 过去用于压缩(缩减)代码,但现在始终需要使用 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 软件包的内容。
在块式 Git 代码库中,不会跟踪任何目录。
clean
npm run clean
通过删除 build/
和 dist/
目录来清理之前的所有 build。对于修复神秘的构建失败,尤其是因重命名源文件而导致的构建失败问题,此功能非常有用。
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
。
生成的 chuk 使用封装容器来确保与通用模块定义兼容,因此无需进行额外的处理,即可将其包含在软件包中。
build
npm run build
会运行 minify
和 langfiles
任务。这样就完成了在压缩或未压缩模式下加载 Blockly 游乐场所需的全部工作。
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)。这应该对作为拉取请求针对块存储库提交的任何代码运行并传递。