完整上手 Blockly 可视化编程编辑器：最小示例到自定义积木生成代码

完整上手 Blockly 可视化编程编辑器：最小示例到自定义积木生成代码

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

Blockly 是谷歌开源的 Web 可视化编程编辑器：把变量、逻辑、循环等编程概念封装成可拼接的图形积木，拖拽完成后一键编译成 JavaScript、Python、PHP、Lua、Dart 等真实代码。读完本文，你能用最少代码在本地跑通一个最小示例，并注册一块自定义积木、让它产出可执行代码。

阅读路线：

• 第一节：理解工作区、积木、生成器三者的分工
• 第二节：三条命令跑通最小页面
• 第三节：定义自定义积木并生成 JavaScript

Blockly 工作区、积木与生成器的分工

本节建立全局认知：知道代码写在哪个目录、各部件各管什么。

Blockly 解决的问题是"语法劝退"：新手先和分号、括号搏斗，而不是先表达逻辑。它把程序拆成一块块带插槽的积木，拼对就能运行，天然没有语法错误。

核心部件只有三件：

• workspace（工作区）：承载所有积木，负责摆放、选中、缩放与事件；入口类在 core/workspace.ts
• block（积木）：描述单块积木的结构、字段与连接规则；core/block.ts
• generator（生成器）：把积木逻辑翻译成目标语言文本；实现在 generators/

默认积木库（逻辑、循环、数学、文本、变量）位于 blocks/，每种语言各有一个生成器目录，如 generators/javascript/。

Blockly 最小安装命令与运行片段

本节把编辑器跑起来：装依赖，用Blockly.inject得到一个可用的工作区。

1. 环境：现代浏览器 + Node.js 16 及以上
2. 安装：npm install blockly
3. 运行以下最小片段

import * as Blockly from 'blockly'; import 'blockly/blocks'; const workspace = Blockly.inject('blocklyDiv', { grid: { spacing: 20, colour: '#ccc', snap: true }, trashcan: true, toolbox: { kind: 'flyoutToolbox', contents: [ { kind: 'block', type: 'controls_if' }, { kind: 'block', type: 'math_number' }, ], }, });

<div id="blocklyDiv" style="width: 600px; height: 400px"></div>

注意两点：Blockly.inject必须绑定一个真实存在的 DOM 容器；上面示例省略了 toolbox 时，工作区只是一个空白画布，这是正常现象。

自定义积木 JSON 配置与 JavaScript 生成器

本节完成第一次改造：注册一块hello积木，并让它产出 JavaScript 代码。

自定义积木 = 定义 + 生成器，两处都要写：

Blockly.defineBlocksWithJsonArray([ { type: 'hello', message0: '向 %1 打招呼', args0: [{ type: 'field_input', name: 'WHO', text: '世界' }], previousStatement: null, nextStatement: null, colour: 160, }, ]); Blockly.JavaScript['hello'] = (block) => { const who = Blockly.JavaScript.valueToCode( block, 'WHO', Blockly.JavaScript.ORDER_NONE ); return `console.log('你好，${who}');\n`; }; console.log(Blockly.JavaScript.workspaceToCode(workspace));

在工具箱加入{ kind: 'block', type: 'hello' }后拖出该积木，workspaceToCode会把它编译成一行console.log。若输出里没有这段代码，多半是生成器忘了注册。

进阶能力按路径定位：主题、事件、工具箱

本节只给地图：每个能力在哪看、看什么文件。

• 主题定制：Theme.defineTheme修改积木颜色、字体与间距，参考 core/theme/zelos.ts
• 事件监听：workspace.addChangeListener捕获拖动、删除等变化，适合做自动保存；源码在 core/events/
• 工具箱分类：改用categoryToolboxJSON 即可得到侧边栏分类，解析逻辑在 core/utils/toolbox.ts
• 云存储集成：appengine/ 提供完整的存取后端 demo

高频踩坑速查：积木不显示、无代码输出

每个问题按"现象 → 原因 → 解法"三行处理：

现象：积木在工具箱里不出现 原因：积木未定义，或工具箱 JSON 中没有引用它的type解法：检查defineBlocksWithJsonArray与 toolboxcontents里的type是否一致

现象：workspaceToCode输出为 undefined 或空 原因：该积木没有对应语言的生成器 解法：为每种目标语言补上生成函数，如Blockly.JavaScript['hello']

现象：容器已存在但页面只有空白画布 原因：未配置 toolbox，工作区默认无积木来源 解法：像第二节那样在 options 中加入toolbox

现象：拼错积木名仍无任何报错 原因：Blockly 对未知 type 静默忽略 解法：在控制台打印Blockly.Blocks.hello，确认对象已注册

参考路径：blocks/、generators/、tests/generators/、demos/、tests/playground.html。

建议下一步：打开 playground 示例，把任意一块积木改成你自己的逻辑，再用生成器看它输出什么。

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