前端低代码UI组件【免费下载链接】blocklyThe web-based visual programming editor.项目地址https://gitcode.com/gh_mirrors/bl/blockly点击查看免费下载blockly/workspace-minimap 是 Blockly 官方生态中的工作区小地图Minimap插件它以主工作区的缩小镜像形式悬浮在工作区之上让开发者一眼看清整个代码块的布局结构并可通过点击、拖拽或键盘方向键快速平移主工作区视口。本文以该插件在仓库中的 CHANGELOG.md 为时间主线结合 README.md、src/ 源码与 test/minimap_tests.mocha.js 测试用例系统梳理插件的安装用法、实现原理、焦点区域、键盘无障碍与版本演进帮助读者既能在项目中快速接入也能理解其内部工作机制。一、插件是什么按 src/minimap.ts 中的定义小地图是主工作区积木的微型版本悬浮在主工作区之上用于提供你的代码长什么样、如何组织的整体概览。它天然附带一个焦点区域Focus Region——一个高亮矩形用于标示用户当前在主工作区中的视口位置该功能默认开启。该插件包名为blockly/workspace-minimap当前仓库中的版本为13.3.0见 package.json其peerDependencies声明blockly: ^13.2.0即要求宿主项目使用 Blockly v13 及以上版本。插件以 Apache-2.0 协议开源。二、从 CHANGELOG 看插件演进史小地图插件自 2023 年 8 月的0.1.0初始版本源自 blockly-samples 仓库的插件模板起步历经版本号跳跃式升级最终在 2026 年并入 Blockly 主仓库并直接对齐主版本号13.x。其演进脉络清晰体现了功能从无到有、质量持续打磨、跟随 Blockly 大版本三条主线。1. 0.1.0核心能力一次到位首个正式版本2023-08-24在短短一个月内密集完成了如下特性形成了今天插件能力的全部骨架镜像渲染Mirroring实现主工作区与最小地图之间的内容同步#1749交互能力实现与小地图的点击、拖拽交互用于控制主工作区视口#1768焦点模式Focus mode实现视口焦点高亮#1848响应式尺寸随窗口与主工作区尺寸自适应缩放#1756、#1850CSS 定制能力允许对小地图进行样式定制#1860同时修复了主工作区缩放时焦点区域定位错误#1851、阴影块在小地图中被复制#1867、以及小地图 playground 的测试#1875。2. 0.1.x打磨与健壮性修复后续小版本修复了大量细节问题这些修复在今天的源码中都能找到对应实现0.1.2修复页面重新加载后小地图焦点区域失准#1890与小地图渲染异常#19310.1.4打包优化——不再声明不存在的 ESM 入口#2022更新 tsconfig 以精确发布类型声明并用includes取代excludes控制发布文件0.1.7清理 15 个 ESLint 告警#20650.1.11正式发布小地图的 TypeScript 类型#2122——此前用户无法获得类型提示0.1.12消除被禁止的非空断言#21280.1.13阻止小地图内部的 click 处理器冒泡到主工作区#2133——防止在小地图上点击意外触发主工作区的点击逻辑这一行为与源码中event.stopImmediatePropagation()的调用一一对应。3. 0.2.x跟随 Blockly v11/v120.2.02024-05-21破坏性变更全插件升级到 Blockly v11同时升级 TypeScript 版本并修复字段校验器0.2.1修复多 Blockly 实例共存时的问题#2375确保一个页面内注入多个工作区各自的小地图互不干扰0.2.8/0.2.9修复 lerna v8 构建链#2446与 predeploy 脚本问题#2449属工程化维护0.2.10移除字段插件中不必要的fieldRegistry.unregister调用#24540.3.02025-05-16破坏性变更全插件升级到 Blockly v12#2538。4. 13.x并入主仓库并适配 v130.3.7将插件相关 URL 全部迁移到 RaspberryPiFoundation 组织#266513.1.02026-06-30破坏性变更——将 Blockly 依赖升级到 v13#2704并针对性修复小地图在 v13 下的运行问题#2702与键盘导航#273013.3.02026-09-10版本号跟随主仓库统一发布节奏。从版本号演变可以看出插件在并入 Blockly 主仓库后采用了与 Blockly 主版本完全对齐的发布策略因此当前 13.3.0 对应 Blockly v13 系列。三、快速开始安装与两种接入方式安装# Yarn yarn add blockly/workspace-minimap # npm npm install blockly/workspace-minimap --save方式一PositionedMinimap定位式小地图定位式小地图是一个悬浮在主工作区上方的嵌入式组件尺寸由窗口大小决定位置由主工作区的布局配置决定自动避开工具箱与滚动条。这也是最常用的接入方式import * as Blockly from blockly; import {PositionedMinimap} from blockly/workspace-minimap; // 注入 Blockly。 const workspace Blockly.inject(blocklyDiv, { toolbox: toolboxCategories, }); // 初始化插件。 const minimap new PositionedMinimap(workspace); minimap.init();方式二Minimap非定位式小地图裸Minimap的尺寸与位置完全由 CSS 控制适合需要自定义布局的场景import * as Blockly from blockly; import {Minimap} from blockly/workspace-minimap; // 注入 Blockly。 const workspace Blockly.inject(blocklyDiv, { toolbox: toolboxCategories, }); // 初始化插件。 const minimap new Minimap(workspace); minimap.init();.blockly-minimap { position: absolute; box-shadow: none; width: 200px; height: 150px; top: 0px; left: 50vw; }两种类均从 src/index.ts 导出。四、源码级实现原理1. 镜像机制事件过滤与回放小地图本质上是一个独立的、只读的 Blockly 工作区。在 src/minimap.ts 的init()中插件用Blockly.inject创建一个小地图工作区并显式继承主工作区的 RTL、主题与渲染器配置this.minimapWorkspace Blockly.inject(this.minimapWrapper.id, { rtl: this.primaryWorkspace.RTL, move: { scrollbars: true, // 开启内部滚动 drag: false, // 禁止直接拖拽积木 wheel: false, // 禁止滚轮缩放 }, zoom: { maxScale: Infinity, minScale: 0, // 移除缩放边界保证 zoomToFit 正确 }, readOnly: true, theme: this.primaryWorkspace.getTheme(), renderer: this.primaryWorkspace.options.renderer, });镜像的核心是事件过滤 事件回放。源码顶部定义了一个事件白名单集合const blockEvents new Setstring([ Blockly.Events.BLOCK_CHANGE, Blockly.Events.BLOCK_CREATE, Blockly.Events.BLOCK_DELETE, Blockly.Events.BLOCK_DRAG, Blockly.Events.BLOCK_MOVE, Blockly.Events.VAR_CREATE, Blockly.Events.VAR_DELETE, Blockly.Events.VAR_RENAME, ]);mirror()方法监听主工作区的变更仅放行白名单内的事件类型将事件序列化为 JSON 后在小地图工作区中重建并执行随后在渲染队列清空后调用zoomToFit()重新缩放居中private mirror(event: Blockly.Events.Abstract): void { if (!blockEvents.has(event.type)) { return; // 过滤无关事件 } const json event.toJson(); if (this.minimapWorkspace) { const duplicate Blockly.Events.fromJson(json, this.minimapWorkspace); duplicate.run(true); } Blockly.renderManagement.finishQueuedRenders().then(() { if (this.minimapWorkspace) { this.minimapWorkspace.zoomToFit(); } }); }这也解释了 CHANGELOG 中0.1.13的修复阻止 minimap 内部 click 处理器干扰主工作区小地图工作区虽为只读但仍可能响应点击因此在 src/minimap.ts 的 pointerdown 处理中通过event.stopImmediatePropagation()阻止事件穿透且该监听器以捕获阶段capture phase绑定优先于工作区中其他处理器。2. 点击与拖拽平移坐标换算在小地图上点击或拖拽会平移主工作区视口。核心是静态方法minimapToPrimaryCoords()它将小地图上的像素坐标换算为主工作区的滚动坐标static minimapToPrimaryCoords(primaryMetrics, minimapMetrics, offsetX, offsetY) { // 减去小地图内容外留白 offsetX - (minimapMetrics.svgWidth - minimapMetrics.contentWidth) / 2; offsetY - (minimapMetrics.svgHeight - minimapMetrics.contentHeight) / 2; // 按内容比例放大到主工作区尺度 const scale primaryMetrics.contentWidth / minimapMetrics.contentWidth; offsetX * scale; offsetY * scale; // 换算为相对主内容左上角的坐标 let x -primaryMetrics.contentLeft - offsetX; let y -primaryMetrics.contentTop - offsetY; // 居中到主视口 x primaryMetrics.viewWidth / 2; y primaryMetrics.viewHeight / 2; return [x, y]; }交互流程为pointerdown在小地图上先执行一次primaryScroll()同时绑定mousemove持续平移onMouseMovemouseup事件绑定在主注入 div 上确保拖拽拖出小地图范围后也能正确解绑避免事件泄漏。3. 焦点区域SVG Mask 高亮src/focus_region.ts 实现了视口高亮。其结构为一个blockly-focus-region的 SVGg组内含一个 maskmask 中黑色圆角矩形圆角半径 6px对应视口区域白色背景用于遮罩其余部分最终背景矩形引用该 mask实现视口之外变暗的效果。update()方法根据主工作区与小地图的 metrics 计算视口在小地图尺度下的位置与大小const scale minimapContent.width / minimapMetrics.getContentMetrics(true).width; const width primaryView.width * scale; const height primaryView.height * scale; let left (primaryView.left - primaryContent.left) * scale; let top (primaryView.top - primaryContent.top) * scale; left (minimapSvg.width - minimapContent.width) / 2; // 补回内容外留白 top (minimapSvg.height - minimapContent.height) / 2;焦点区域同样监听一组白名单事件VIEWPORT_CHANGE、BLOCK_CHANGE、BLOCK_CREATE、BLOCK_DELETE、BLOCK_DRAG、BLOCK_MOVE、VAR_RENAME以及窗口resize/load事件来触发重绘。CHANGELOG 中0.1.2修复的reload 后焦点区域失准问题正是由于load事件监听需要等待页面完全加载后再重算 metrics。五、定位算法与样式配置1. PositionedMinimap 的定位策略src/positioned_minimap.ts 中的PositionedMinimap继承Minimap并实现Blockly.IPositionable注册到主工作区的ComponentManager权重为 3从而纳入 Blockly 的 UI 布局体系默认尺寸width 225、height 150边距margin 20响应式尺寸setSize()以Math.max(200, viewWidth / 5)计算宽度最小 200px高度恒为宽度的 2/3位置计算setPosition()依据工具箱位置左/右/上/下与滚动条可见性把小地图放在视口相对角落并扣除Scrollbar.scrollbarThickness避免遮挡滚动条若与既有 UI 组件矩形savedPositions相交则自动向上或向下顶开避让碰撞规避通过getBoundingRectangle()返回包围矩形并与savedPositions逐个求交发生碰撞时重新计算top并重置遍历保证与其他悬浮组件不重叠。仓库 test/minimap_tests.mocha.js 中用 mock 数据覆盖了 LTR/RTL × 纵向/横向布局 × 工具箱开始/结束位置共 8 种组合的定位断言例如 LTR 纵向布局、工具箱在左侧时期望top 20, left 872视口宽 1000、最小图宽 225、边距 20、扣掉滚动条宽度验证了定位算法的边界行为。2. CSS 定制小地图整体使用blockly-minimap类如 box-shadow 阴影焦点区域使用blockly-focus-region类默认填充色#e6e6e6。插件通过Blockly.Css.register()注册了默认样式见 src/positioned_minimap.ts 与 src/focus_region.ts开发者可覆盖这两个类实现主题定制。3. 生命周期与多实例init()与dispose()成对使用dispose()会先关闭焦点区域、销毁小地图工作区、移除 wrapper 节点并逐一解绑全部事件监听键盘、焦点、鼠标、窗口 resize防止内存泄漏。测试 test/index.ts 中每个工作区重建前都会先minimap.dispose()正是多实例场景对应 CHANGELOG0.2.1的修复的标准写法。六、键盘无障碍小地图在页面 Tab 顺序中是单个制表位minimapWrapper被设置tabIndex 0、role application与描述性的aria-label默认文案来自Blockly.Msg[MINIMAP_ARIA_LABEL]。当小地图获得焦点时方向键可平移主工作区按键动作ArrowUp工作区向上平移ArrowDown工作区向下平移ArrowLeft工作区向左平移ArrowRight工作区向右平移默认平移距离为每次按键 40 个工作区像素源码常量DEFAULT_PAN_STEP 40可配置minimap.setKeyboardPanStep(80); // 每次按键平移 80px实现细节src/minimap.ts 的onKeyDown带修饰键Ctrl/Alt/Shift/Meta的组合键直接放行、不平移避免覆盖浏览器或应用快捷键方向键处理后调用event.preventDefault()与event.stopPropagation()防止页面滚动或事件冒泡从 Blockly 的 FocusManager 中注销小地图工作区focusManager.unregisterTree保证键盘焦点永远无法落入小地图内部聚焦时通过 CSS 变量--blockly-active-tree-color、--blockly-selection-width绘制与工作区一致的焦点环focus-visible时生效。test/minimap_tests.mocha.js 中的键盘导航测试套件逐项验证了小地图工作区未注册进 FocusManager、wrapper 的tabIndex与aria-label、四个方向键的滚动方向与步长ArrowDown 传-step、ArrowUp 传step等、修饰键组合不平移、非方向键不平移以及preventDefault/stopPropagation的行为。七、公开 API 一览API说明init()初始化小地图dispose()销毁小地图并清理事件监听isFocusEnabled()返回焦点区域是否启用enableFocusRegion()开启焦点区域disableFocusRegion()关闭焦点区域setKeyboardPanStep(stepPixels)设置每次方向键平移的像素数主工作区像素getKeyboardPanStep()返回当前方向键平移步长主工作区像素PositionedMinimap实例额外提供API说明position()定位小地图 UI 元素getBoundingRectangle()返回 UI 元素相对 Blockly 注入 div 的包围矩形像素单位八、测试验证与注意事项仓库为插件提供了三组自动化测试test/minimap_tests.mocha.js坐标转换测试以三组不同比例正方形居中、宽扁左上偏移、窄高右下偏移的 metrics 输入断言小地图四角/中心点击换算出的主工作区滚动坐标覆盖minimapToPrimaryCoords的纯函数逻辑定位测试8 种 LTR/RTL × 布局组合的setPosition/setSize结果断言镜像与键盘测试验证变量重命名能同步到小地图variables_set块的字段文本随之更新、FocusManager 注销、方向键平移行为等。接入时需要注意几点初始化时机init()要求工作区已注入页面init()中会校验getInjectionDiv().parentNode否则抛出错误版本匹配blockly/workspace-minimap13.x 对应 Blockly v13见 package.json 的peerDependenciesCHANGELOG 中 v11/v12/v13 均为破坏性升级升级 Blockly 主版本时需同步升级插件只读设计小地图禁止拖拽积木与滚轮缩放readOnly: true保证镜像不被误操作破坏焦点区域默认开启如需关闭可调用disableFocusRegion()。九、总结blockly/workspace-minimap 从 2023 年的初始版本到当前 13.3.0能力演进路线清晰镜像渲染、点击拖拽交互、焦点区域、响应式尺寸四大核心能力在0.1.0即全部落地随后历经坐标换算与定位算法的修复打磨、Blockly v11/v12/v13 三次破坏性升级适配、键盘无障碍与多实例支持的完善最终成为 Blockly v13 官方生态中成熟稳定的小地图解决方案。理解其独立只读工作区 事件白名单回放 坐标映射的实现模型开发者便可以在任何 Blockly 项目中快速接入甚至基于Minimap/PositionedMinimap二次定制出符合自身需求的导航组件。赞分享前端低代码UI组件【免费下载链接】blocklyThe web-based visual programming editor.项目地址https://gitcode.com/gh_mirrors/bl/blockly点击查看免费下载相关推荐Midscene.js 浏览器自动化 Chrome 扩展新手指南安装、Bridge 连接与调试一次讲清Midscene.js 浏览器自动化 Chrome 扩展新手指南安装、Bridge 连接与调试一次讲清 Midscene.js 是一款用自然语言驱动浏览器自动前端低代码UI组件Blockly 工作区小地图Workspace Minimap插件安装配置、键盘导航与源码原理全解析Blockly 工作区小地图Workspace Minimap插件安装配置、键盘导航与源码原理全解析 小地图Minimap是主工作区右上角悬浮的代码缩前端低代码UI组件10 分钟把任意网页装进桌面PakePlus 可视化打包实操指南10 分钟把任意网页装进桌面PakePlus 可视化打包实操指南 PakePlus 是一个开源打包工具给它一个网址或 Vue/React 项目编译后的 d前端低代码UI组件上一篇酷安UWP 4 步装上手在电脑上刷动态的完整教程下一篇酷安 UWP 桌面版安装指南三步装好大屏刷动态教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考