Blockly 实战速览：10 分钟跑通可视化编辑器，搞定积木自定义与代码生成

发布时间：2026/11/4 6:16:48
Blockly 实战速览：10 分钟跑通可视化编辑器，搞定积木自定义与代码生成

Blockly 实战速览：10 分钟跑通可视化编辑器，搞定积木自定义与代码生成

【免费下载链接】blocklyThe web-based visual programming editor.项目地址: https://gitcode.com/gh_mirrors/bloc/blockly

让最终用户在浏览器里拖拽积木拼出程序，不用碰一行语法——这是 Blockly 要解决的问题。作为 Google 开源的可视化编程编辑器库，它用互相咬合的图形积木表示变量、逻辑判断、循环这些代码概念，并把拼好的积木导出成 JavaScript、Python、PHP、Lua、Dart 五种语言之一。下面围绕"装好一个能用的编辑器"这个目标，把关键步骤走一遍。

3 条命令让 Blockly 编辑器出现在浏览器里

环境要求不高：现代浏览器加 Node.js 18 以上（package.json 中 engines 声明为>=18）。

npm install blockly

编辑器本体只需一个空容器和一次inject调用：

import * as Blockly from 'blockly'; const workspace = Blockly.inject('blocklyDiv', { toolbox: [ { kind: 'category', name: 'Logic', contents: [{ kind: 'block', type: 'controls_if' }] }, ], });

toolbox支持 JSON 数组或 XML 两种描述方式。注入后 Blockly 会把 SVG 画布、侧边工具栏、缩放控件全部挂进#blocklyDiv，返回值workspace是后续一切操作的入口。注入逻辑的完整实现可以看 core/inject.ts，所有可传配置项的说明在 core/blockly_options.ts。

工具栏、主题、事件监听：编辑器三件套

想让编辑器"像产品"而不是"像 demo"，通常要补三处配置。

工具栏分两类。积木少时用一个平铺 flyout（kind: 'flyout'）；积木多时用带分类的 toolbox（kind: 'category'），用户点分类再展开积木，仓库自带的 tests/playground.html 里就放了三种工具栏样例可直接抄。

主题控制配色。内置主题在 core/theme/，比如Blockly.Themes.Classic。想换一套颜色，声明自己的主题并指定积木样式即可：

const myTheme = Blockly.Theme.defineTheme('myTheme', { blockStyles: { logic_blocks: { colourPrimary: '#4a6785' }, }, });

事件监听用于业务联动。自动保存、实时校验这类需求都走同一个入口：

workspace.addChangeListener((e) => { if (e.type === Blockly.Events.BLOCK_CHANGE) { // 积木被修改：触发自动保存 } });

事件体系的所有类型定义在 core/events/ 目录，按积木增删、移动、字段变化等拆分得很细。

自定义积木块：两种定义方式

自定义积木是 Blockly 使用频率最高的能力，有两种写法。

方式一：JSON 声明（推荐）。积木外观用 JSON 描述，defineBlocksWithJsonArray一次性注册：

Blockly.defineBlocksWithJsonArray([ { 'type': 'say_hello', 'message0': '说 %1', 'args0': [{ 'type': 'field_input', 'name': 'TEXT', 'text': 'World' }], 'previousStatement': null, 'nextStatement': null, 'colour': 160, 'tooltip': '打印一句话', }, ]);

message0里的%1是占位符，按顺序对应args0的字段；previousStatement/nextStatement声明积木可以上下拼接。仓库里上千行积木定义基本都是这种写法，blocks/logic.ts 的controls_if是很好的参照——它还演示了mutator（可折叠分支）和extensions机制。

方式二：用 Block 类在代码里搭。需要运行时动态决定字段时才用new Blockly.Block(...)加appendField/appendInput手工构建。JSON 方式覆盖不了的需求再用它。

定义完别忘了把type加进 toolbox，否则积木只注册不显示。

从积木到可执行代码：代码生成 4 行搞定

自定义积木能拖了，最后一步是让拼出来的东西真的能跑。仓库 generators/ 目录内置五个生成器，以 JavaScript 为例：

import {javascriptGenerator} from 'blockly/javascript'; javascriptGenerator.forBlock['say_hello'] = function (block, generator) { const text = generator.quote_(block.getFieldValue('TEXT')); return `console.log(${text});\n`; }; const code = javascriptGenerator.workspaceToCode(workspace);

逻辑很简单：生成器按积木树递归遍历，每个type对应forBlock里的一个函数，函数返回该积木对应的代码片段，生成器负责处理缩进、变量声明和运算符优先级（优先级规则见 javascript_generator.ts 中的Order定义）。内置积木都有现成生成函数，你只需要为自己的积木补上缺失的那一个。

保存与还原工作区：JSON 状态与 XML

积木程序要跨会话保存，有两种序列化格式：

// JSON（v11 推荐的持久化格式） const state = Blockly.serialization.workspaces.save(workspace); Blockly.serialization.workspaces.load(state, workspace); // XML（旧格式，兼容存量数据） const xml = Blockly.Xml.workspaceToDom(workspace);

JSON 格式同时保存积木、变量和工作区注释，还原用Blockly.serialization.workspaces.load；XML 走Blockly.Xml系列函数。两套格式的读写逻辑分别在 core/serialization/ 和 core/xml.ts。tests/playground.html 里的 Save JSON / Save XML / Load 按钮就是这两个 API 的最小封装，可以直接参考它的事件绑定方式。

三个高频坑

  1. 积木不显示。九成是 toolbox 里没有引用该type，另一成是忘了加载积木包。npm 包按子路径拆分，标准积木库不在blockly主入口里，需要import 'blockly/blocks'或按需import 'blockly/blocks/logic'这类引入。
  2. 旧教程的 API 失效。大量文章还在用Blockly.JavaScript.workspaceToCode，v11 起生成器已从主包移到子路径（blockly/javascript、blockly/python等，见 package.json 的exports字段）。主入口只保留核心 API。
  3. 代码生成报 "No generator for block"。自定义积木忘了注册forBlock函数时生成器会直接抛错，而不是静默跳过。控制台看到这条报错，就去补对应语言的生成函数。

下一步做什么，去哪找源码

想动手验证，最快的路径是把源码拉下来跑官方 playground：

git clone https://gitcode.com/gh_mirrors/bloc/blockly cd blockly npm install npm start

npm start会构建后打开 tests/playground.html，一个自带工具栏切换、代码导出、事件日志的完整实验台。

常用入口导航：

  • 标准积木定义：blocks/（logic / math / loops / procedures 等分类清晰）
  • 五种语言生成器：generators/
  • 可运行示例：demos/（代码演示、云存储、移动端 WebView）
  • 完整 API 类型声明：typings/
  • 事件系统：core/events/

建议的练习顺序：先在 playground 里用内置积木拼一个小程序并导出五段代码，对比同一逻辑在不同语言的产物；然后定义一个自己的积木（JSON 方式 + JS 生成函数）；最后给它接上addChangeListener做自动保存。这三件事做完，就具备了做一套可视化编程产品的基本盘。

【免费下载链接】blocklyThe web-based visual programming editor.项目地址: https://gitcode.com/gh_mirrors/bloc/blockly

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考