前端低代码开发工具【免费下载链接】blocklyThe web-based visual programming editor.项目地址https://gitcode.com/gh_mirrors/bloc/blockly点击查看免费下载导读本文基于仓库根目录 CHANGELOG.md 中 Blockly 8.0.02022-03-31 发布的完整发布说明逐项拆解该版本引入的破坏性变更Breaking Changes、新增特性Features、Bug 修复Bug Fixes与代码重构Code Refactoring并对照当前仓库源码逐一验证每一项变动的实际落地位置与调用方式。读完本文你将掌握 8.0.0 升级时可能触碰到的 API 迁移点如Blockly.blocks.all→Blockly.libraryBlocks、paste()返回值变化、内部常量可配置化以及自定义 tooltip、模块化命名空间等新能力的实战用法。文中所有结论均可通过文中给出的仓库相对路径回溯源码确认。一、版本背景与整体定位Blockly 8.0.0 是 Blockly 历史上一次重要的“清理 稳固化”版本它在功能上收敛了此前版本中大量被标记为“内部”的 API将一批内部常量开放为可配置同时为后续的模块化重构铺路最典型的就是块定义命名空间从Blockly.blocks.*迁移到Blockly.libraryBlocks.*。这一版本的核心信号是命名空间收敛内置块库从Blockly.blocks.*更名为Blockly.libraryBlocks.*返回值契约明确化Blockly.clipboard.paste()改为返回被粘贴的对象以支撑键盘导航内部状态外部化loopTypes循环块类型集合由不可见的内部结构变为可导出的Set常量治理移除internalConstants中不再使用的常量并让一部分原先内部的常量如颜色饱和度/亮度重新可配置。下面按 CHANGELOG 的四个分类逐一展开。二、破坏性变更Breaking ChangesCHANGELOG 明确列出了 4 条 Breaking Changes全部在 CHANGELOG.md 中声明它们同时也在仓库的迁移数据库 scripts/migration/renamings.json5 中留下了对应的迁移记录。逐一分析如下。1.paste()现在返回被粘贴的对象#5996变更内容Blockly.clipboard.paste的返回值从void改为“被粘贴的对象”ICopyableT | null粘贴成功时返回新生成的对象失败时返回null。此变更的直接动机是支持键盘导航keyboard nav——键盘操作在粘贴后需要拿到新对象以完成后续的选中与聚焦动作。源码验证当前仓库 core/clipboard.ts 中paste()的重载签名明确写出export function pasteT extends ICopyData( copyData: T, workspace: WorkspaceSvg, coordinate?: Coordinate, ): ICopyableT | null;其内部实现pasteFromData通过全局注册表查找对应类型的PASTER处理器并返回其paste()结果core/clipboard.ts。测试佐证测试用例 tests/mocha/clipboard_test.js 直接对返回值断言const newBlock Blockly.clipboard.paste(data, this.workspace); assert.deepEqual( newBlock.getRelativeToSurfaceXY(), ... );迁移提示如果你在自定义代码中覆盖或调用了paste()需要兼容“可能返回null”的情况如果过去依赖粘贴后重新查询 workspace 来找新块现在可以直接使用返回值。2. 块库命名空间Blockly.blocks.all→Blockly.libraryBlocks#5953变更内容Blockly.blocks.*系列模块更名为Blockly.libraryBlocks.*同时Blockly.blocks.all对应blocks/all.js更名为Blockly.libraryBlocks对应blocks/blocks.js。这是一次纯粹的模块级重命名用于更清晰地表达“这些是随库分发的内置块而不是用户自定义块”。源码验证当前仓库 blocks/blocks.ts 的模块注释即为Former goog.module ID: Blockly.libraryBlocks并且通过export {lists, logic, loops, math, procedures, texts, variables, variablesDynamic}将各子模块统一导出同时用Object.assign汇总出blocks字典blocks/blocks.ts。迁移记录迁移数据库 scripts/migration/renamings.json5 中逐条记录了全部 10 个对应映射例如{ oldName: Blockly.blocks.all, newName: Blockly.libraryBlocks, }, { oldName: Blockly.blocks.loops, newName: Blockly.libraryBlocks.loops, },升级动作所有Blockly.blocks.xxx的引用都应替换为Blockly.libraryBlocks.xxx若使用 ES Module 导入对应import {loops} from blockly/blocks的写法不变但访问的命名空间对象已改。3. 内部常量可配置化#5897变更内容一批“此前属于内部、无法被外部修改”的常量被开放为可配置。最典型的例子是块颜色的饱和度与亮度Blockly.HSV_VALUE、Blockly.HSV_SATURATION曾被移入内部模块此版本重新以可设置settable属性的形式暴露到Blockly命名空间。源码验证当前仓库中这两个量的存储与读写已落在 core/utils/colour.ts提供getHsvSaturation()/setHsvSaturation()与getHsvValue()/setHsvValue()四组访问器hsvToHex在生成块颜色时实时读取这两个值core/utils/colour.ts。迁移记录迁移数据库 scripts/migration/renamings.json5 中保留了从Blockly.HSV_SATURATION/Blockly.HSV_VALUE到Blockly.utils.colour的 get/set 方法映射方便工具链自动迁移。4. 移除internalConstants中未使用的常量#5889变更内容从Blockly.internalConstants中删除不再被引用的常量定义缩小内部公共面。源码验证当前 core/internal_constants.ts 中仅保留 4 个常量COLLAPSE_CHARS折叠块截断字符数30、OPPOSITE_TYPE连接类型取反查找表、RENAME_VARIABLE_ID、DELETE_VARIABLE_ID变量下拉菜单特殊选项 ID。这些常量仍通过 core/blockly.ts 以兼容别名暴露到Blockly顶层供外部沿用。而折叠相关的COLLAPSED_INPUT_NAME、COLLAPSED_FIELD_NAME已归属 core/constants.ts。迁移提示如果你此前直接引用了internalConstants中的某个已删除常量需要改为引用公开等价物如 core/blockly.ts 中导出的Blockly.COLLAPSE_CHARS等顶层别名。三、新特性Features1. 自定义 tooltip 渲染函数#5956变更内容开发者现在可以设置一个自定义函数来渲染 tooltip UI替代默认的文本渲染。这是 8.0.0 面向二次开发者的重要能力增强。源码验证当前 core/tooltip.ts 完整实现了这一机制类型定义CustomTooltip (p1: Element, p2: Element) ...core/tooltip.ts第一个参数是用于渲染内容的 div 元素第二个参数是鼠标悬停的目标元素全局状态customTooltip与设置/读取函数setCustomTooltip()/getCustomTooltip()core/tooltip.ts渲染时若存在自定义函数则调用之否则走默认渲染renderDefaultContent()core/tooltip.ts。用法示例对应测试 tests/mocha/tooltip_test.jsBlockly.Tooltip.setCustomTooltip((containerDiv, element) { containerDiv.textContent 自定义提示 element.getAttribute(data-tip); });相关默认参数默认 tooltip 的字符上限LIMIT 50、悬停延迟HOVER_MS 750毫秒、相对鼠标的偏移与边距OFFSET_X 0/OFFSET_Y 10、MARGINS 5、鼠标移动半径容差RADIUS_OK 10core/tooltip.ts这些常量在自定义实现中可作为行为参考。2. 导出内置块定义#5908变更内容将内置块的定义以结构化对象的形式导出方便开发者在不注册块的情况下复用、包装或生成内置块 JSON。源码验证当前 core/blocks.ts 定义并导出了Blocks字典{[key: string]: BlockDefinition}各块库模块如 blocks/loops.ts通过createBlockDefinitionsFromJsonArray([...])生成blocks字典并导出最终由 blocks/blocks.ts 汇总。这意味着你可以直接导入内置块的 JSON 定义做二次加工。3. Mocha 测试基础设施改进#5984 / #5981 / #5990#5984Mocha 失败信息输出到控制台方便在无浏览器环境下如 CI直接查看断言失败详情#5981Mocha 在遇到0 个测试时直接判失败避免“空跑通过”的假绿#5990测试使用官方的 semver.org 正则表达式校验语义化版本格式。验证途径仓库测试基础设施可在 package.json 看到test:browser、test:mocha:interactive等脚本Mocha 测试位于 tests/mocha/。4. 迁移数据库校验测试#5980新增测试用于校验scripts/migration/renamings.js即迁移数据库 scripts/migration/renamings.json5 对应的生成物格式与内容的正确性确保自动迁移工具链的输入数据可信。四、Bug 修复Bug Fixes要点解析8.0.0 的 Bug Fixes 条目众多CHANGELOG.md其中以下几类值得关注因为它们直接关系到升级后的运行行为1.procedures_defreturn的callType_修正#5974问题procedures_defreturn块的callType_被错误设置为无返回的调用块类型导致该定义块生成的调用块类型错误。源码验证当前 blocks/procedures.ts 中procedures_defnoreturn的callType_: procedures_callnoreturn而procedures_defreturn的callType_: procedures_callreturnblocks/procedures.ts。该字段在customContextMenu中用于生成“创建调用块”的菜单项blocks/procedures.ts。2. 撤销/重做相关的修复#5844、#5845、#6018#5844复制后撤销undo导致块 bump 出错——修复了“duplicate 打破 undo”后执行 bumping 的时序问题#5845过程参数编辑打破 undo 链——保证在 mutator 中编辑参数也能正确进入撤销栈#6018if-return 块的自动禁用auto disabling支持 undo/redo——注意这里与过程相关的禁用原因DISABLED_PROCEDURE_DEFINITION在 blocks/procedures.ts 中定义循环块相关禁用原因CONTROL_FLOW_NOT_IN_LOOP则在 blocks/loops.ts 定义。3. 工作区注释Workspace Comment修复#6011、#6024#6011拖拽过程中注释未被恢复#6024工作区注释无法被创建。源码现状注释相关实现分布在 core/comments/comment_view.ts、workspace_comment.ts、rendered_workspace_comment.ts以及 core/comments.ts。4. 类迁移与命名空间修复#5977 / #5978将Workspace类与 common renderer 转换为 ES6 class 写法配合 Closure 到 ES Module 的迁移#6003将alias注释从构造函数移到类上修正类型声明生成#6030正确导出Blockly.Names.NameType与Blockly.Input.Align#5979DropDownDiv从“只有静态成员的类”改为命名空间对象namespace当前 core/blockly.ts 中export const DropDownDiv dropDownDiv;即对应此变化#5813SVG 数学函数归位到正确的命名空间Blockly.utils.svgMath。源码验证SVG 数学函数如getRelativeXY、getInjectionDivXY、getViewportBBox、getDocumentScroll、screenToWsCoordinates、wsToScreenCoordinates现全部位于 core/utils/svg_math.ts迁移记录见 scripts/migration/renamings.json5。5. 其他值得注意的修复#5869触摸事件增加changedTouches检查修复移动端触摸处理的健壮性#5997WorkspaceSvg.setCachedParentSvgSize用显式null比较替代真值判断使 0 值能正确写入缓存#5805修正 keycodes 类型定义#5831主题中字体样式设为null不再出错#6012迁移数据库中事件数据的 module 归属修正#5890序列化函数的 TypeScript 导出修复#5685math_number_property生成器的运算符优先级问题——去除多余括号在 generators 目录中可查到对应语言生成器实现如 generators/javascript/math.ts 等。五、代码重构Code Refactoring1.loopTypes变为Set#5897 / #5953 系列变更内容将“哪些块类型属于循环块”的判断从数组/散落逻辑收敛为可导出的Setstring第三方可向其中追加自定义循环类型从而让break/continue块的“是否在循环内”检查正确覆盖自定义循环。源码验证当前 blocks/loops.ts 中export const loopTypes: Setstring new Set([ controls_repeat, controls_repeat_ext, controls_forEach, controls_for, controls_whileUntil, ]);其消费方是CONTROL_FLOW_IN_LOOP_CHECK_MIXIN的getSurroundLoop()blocks/loops.ts从当前块逐级向上查找命中loopTypes即认为在循环内否则对controls_flow_statements设置警告并禁用blocks/loops.ts。文件注释给出了三种注册自定义循环类型的方式例如浏览器端Blockly.libraryBlocks.loopTypes.add(custom_loop);2. 模块化重构的支撑性改动8.0.0 的重构主线是把大量 goog.module 改写为 ES Module 并收敛顶层命名空间。与本文主题直接相关的包括core/blocks.ts定义BlockDefinition类型与Blocks字典blocks/blocks.tslibraryBlocks汇总模块集中导出lists、logic、loops、math、procedures、texts、variables、variablesDynamic及汇总字典blockscore/blockly.ts顶层Blockly命名空间对子模块的 re-export如export {Blocks}、export {Tooltip}、export {clipboard}等core/blockly.ts。测试辅助迁移#5969测试辅助工具从 samples 移入 core统一测试基础设施的归属#5982 则回退了“测试辅助工具转 ES Module”的先行尝试说明该版本在模块化迁移上采取了审慎的渐进策略。六、升级到 8.0.0 的迁移清单结合上文升级时请按以下清单逐项检查检查项变更内容涉及文件块库命名空间Blockly.blocks.*→Blockly.libraryBlocks.*blocks/blocks.ts、scripts/migration/renamings.json5paste()返回值由void改为ICopyableT \| nullcore/clipboard.tsHSV 颜色常量由内部常量改为Blockly.utils.colour的 get/set 访问器core/utils/colour.ts循环块类型集改为可导出的Set可向其中add()自定义类型blocks/loops.ts内部常量清理internalConstants中未用常量被删除公开等价物移至Blockly顶层core/internal_constants.ts、core/constants.tsSVG 数学函数归位Blockly.utils.svgMath命名空间core/utils/svg_math.ts如需程序化迁移历史 API 引用仓库提供了迁移数据库 scripts/migration/renamings.json5其中以oldName → newName形式记录了本版本全部重命名映射可作为自动化工具的数据源。结语Blockly 8.0.0 表面上看是一个“修复为主”的版本但其背后的破坏性变更尤其libraryBlocks命名空间与paste()返回值契约为后续版本的模块化演进定下了基调同时它通过自定义 tooltip、可配置内部常量、可扩展的loopTypes集合把更多定制能力正式开放给了二次开发者。升级到该版本时建议以本文第六节的迁移清单为索引逐项核对代码中对旧命名空间与旧签名的引用并结合 tests/mocha/ 下的测试用例验证迁移结果。补充阅读相关实现与测试入口——core/tooltip.ts自定义 tooltip、tests/mocha/tooltip_test.js、tests/mocha/clipboard_test.jspaste()返回值、blocks/loops.tsloopTypes与循环内检查、scripts/migration/renamings.json5全部重命名映射。赞分享前端低代码开发工具【免费下载链接】blocklyThe web-based visual programming editor.项目地址https://gitcode.com/gh_mirrors/bloc/blockly点击查看免费下载相关推荐Pylint 3.0 大版本发布全解析新特性、破坏性变更与升级迁移指南Pylint 3.0 大版本发布全解析新特性、破坏性变更与升级迁移指南 Pylint 3.0 是 Pylint 历史上重要的主版本里程碑2023 10 02静态分析代码质量Lint开发工具Falcon 1.0.0 版本深度解读破坏性变更、新特性与升级迁移指南Falcon 1.0.0 版本深度解读破坏性变更、新特性与升级迁移指南 Falcon 1.0.0 是这一no magic Python Web 框架走向成后端Web框架API设计JSQMessagesViewController 8.0.0 升级指南破坏性变更、新特性与源码级解读JSQMessagesViewController 8.0.0 升级指南破坏性变更、新特性与源码级解读 本文以 JSQMessagesViewControllUI组件即时通讯上一篇开源项目推荐Awesome Electronics下一篇passport-local错误处理完全手册如何优雅处理认证失败与异常创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考